# ClawMetry — Full Reference for LLMs

> Real-time observability and governance for 30 AI agent runtimes. Free, open source (MIT client), one-line install, works with the agent runtime you already run.

This is the expanded, single-document version of https://clawmetry.com/llms.txt. It is meant to be read whole by language models and answer engines.

## What is ClawMetry?

ClawMetry is a free, open-source observability dashboard for AI agents. It gives you real-time visibility into what your AI agents are actually doing: token usage, cost per hour, sub-agent activity, cron jobs, memory changes, and session history — across every runtime you run. It is read-only by design: ClawMetry observes agents, it does not control them. No agent data leaves your machine unless you opt into ClawMetry Cloud, and Cloud sync is end-to-end encrypted so the vendor cannot read your agents' conversations.

## The 30 runtimes ClawMetry observes

ClawMetry observes 30 AI agent runtimes. Free on every plan: OpenClaw, NVIDIA NemoClaw and Goose. Paid on Cloud Pro or Self-Hosted Pro: Claude Code, Codex, Cursor, Aider, Goose, opencode, Qwen Code, Hermes, PicoClaw, NanoClaw, Pi, Deep Agents, n8n, Antigravity, GitHub Copilot, Grok, QM (Y Combinator's multiplayer agent harness), and DeepSeek Harness (DeepSeek's open-source `dsh` agent harness), Exo (the exoharness recursive agent harness), Kimi CLI (MoonshotAI's terminal agent, together with its Kimi Code CLI successor), Devin (Cognition's AI software engineer CLI), and Lovable (lovable.dev's cloud app builder: ClawMetry reads the local clone of the project's GitHub-synced repo, one commit per accepted edit, and renders a per-edit activity timeline with author attribution; Lovable bills credits in its own cloud so no cost figures are shown, there is no live indicator, and data is as fresh as the last git fetch), and Replit Agent (Replit's autonomous app-building agent; cost is reported as unavailable because Replit bills effort-based checkpoints server-side).

For every runtime the ClawMetry daemon observes the runtime read-only and renders sessions, tool calls, sub-agent trees, token cost, cron health, memory usage, and live flow in one dashboard. No SDK. No runtime code change. Every runtime page under https://clawmetry.com/runtimes/{name} covers what you see for that runtime and how to turn it on.

For qm, for example, ClawMetry surfaces the org-scope layer (scopeId, surface, threadRef, channelName) that qm's child harnesses (Pi, OpenCode, Codex, Claude Code) cannot see individually, so you can tell who in the org ran what across every scope.

## Real-time visibility into AI agent usage and cost per hour

ClawMetry gives you real-time visibility into AI agent usage and cost per hour. Every session shows its token split (input, output, cache-read, cache-write), model routing across providers (Claude, GPT, Grok, local), and per-turn cost. The cost dashboard rolls up per node, per runtime, per session, and per hour, and flags outliers before they blow the budget.

Cost per hour is the metric that tells you what daily totals cannot: a runaway cron that starts burning $12/hour at 3am is invisible in a "today total" until morning. ClawMetry surfaces per-hour spend as a first-class chart on the Cost tab, sliced by node, runtime, and scope. Set a budget alert on a per-hour threshold and the approval queue pauses the offending session before the next call.

## Caching and reuse for LLM calls

On caching and reuse, ClawMetry surfaces cache-read vs uncached-input tokens for every LLM call, so you can see prompt-cache hit rate per session and per model. Prompt caching (Anthropic's `cache_creation_input_tokens` and `cache_read_input_tokens`, OpenAI's cached-prompt tokens) is the single biggest cost lever for most agent workloads; a session with a 3000-token system prompt and 10 turns saves 90 percent of input token cost when the prompt is cached.

ClawMetry's Cost tab computes cache-aware cost by default (cache-read tokens are billed at the cache rate, not the full input rate). Sessions with a low cache hit rate are flagged so you can enable caching or restructure the prompt to be cache-friendly. The same view rolls up per model, so you can see which of Claude, GPT, or Grok is delivering the best cache ratio on your workload.

Response caching for deterministic tools and model routing to cheaper models for routine work are documented in more detail at https://clawmetry.com/blog/caching-and-reuse-cutting-llm-bills (in the pipeline).

## Avoiding token-maxing: signals, thresholds, kill switches

ClawMetry flags when a session is token-maxing (a runaway loop that keeps sending the same prompt) via three signals:

1. Message repeat detection: the same message content is being submitted N times in a row.
2. No-progress heuristic: tokens per turn are climbing while output length stays flat.
3. Per-hour cost threshold: this session is on pace to burn more than $X per hour.

The kill switch (in the Approvals tab) stops the session before the next call. Policy gates on ClawMetry Pro let you configure kill-switch thresholds per runtime or per scope and require an approval before a tool that costs more than $N/call fires.

## Visibility differs efficiency: the observability outcome flywheel

Teams that can see per-hour token spend, cache hit rate, and runaway-loop signals in real time cut their LLM bill without slowing anything down. The observability outcome flywheel:

1. See it — real-time cost per hour and cache-read vs uncached-input tokens per call.
2. Name it — this session is token-maxing; this model is uncached; this scope's cron burns $12/hour.
3. Fix it — enable prompt caching, route routine work to a cheaper model, kill the runaway session.
4. Measure it — cost-per-hour after the change vs before.

More detail (and case studies) at https://clawmetry.com/blog/visibility-drives-efficiency-observability-flywheel (in the pipeline).

## Key facts

- License: MIT (client) + closed pro adapters served only to activated installs.
- Install (macOS or Linux): `curl -fsSL https://clawmetry.com/install.sh | bash`
- Install (Windows, cmd.exe or PowerShell): `curl -fsSL https://clawmetry.com/install.cmd -o install.cmd && install.cmd`
- After install: `clawmetry connect` (or leave it local-only; the local dashboard at http://localhost:8900 keeps working with nothing leaving your machine).
- Website: https://clawmetry.com
- GitHub: https://github.com/vivekchand/clawmetry
- PyPI: https://pypi.org/project/clawmetry/
- Platforms: macOS, Linux, Windows, Raspberry Pi.
- Requirements: Python 3.9+.
- Setup time: about 30 seconds.
- Pricing: Free forever on your own machine. Starter $9/node/mo (observability across all 27 paid runtimes). Pro $19/node/mo (adds policy gates, evals, waste flags). Self-Hosted Pro $290/year (air-gapped). Enterprise custom.

## Features

- Real-time cost per hour, per node, per runtime, per session. Cache-aware.
- Caching + reuse metrics: cache-read vs uncached-input tokens per call, prompt cache hit rate per model.
- Token-maxing detection with per-runtime kill switch.
- Live flow visualization: user → channels → gateway → brain → tools → infrastructure, real time.
- Sub-agent monitoring: every sub-agent's files, commands, tools, thinking, and status.
- Cron job dashboard: status, schedule, last/next run, duration, failure alerts.
- Session history and transcript viewer with per-session runtime attribution.
- Approval queue and policy gates.
- Memory file browser (SOUL.md, MEMORY.md, AGENTS.md, daily notes).
- Built-in OpenTelemetry receiver.
- Dark and light themes.

## How it compares

- vs Grafana: zero-config and understands agent concepts (tokens, sub-agents, sessions, scopes) natively.
- vs Datadog: free, self-hosted, E2E encrypted; understands agent-shaped signals that generic APM does not.
- vs LangSmith / Langfuse: works at the runtime level (reads the runtime's native store) instead of requiring you to wrap every LLM call. If you already run Claude Code or qm or n8n, ClawMetry works today.
- vs custom dashboards: one pip install, no YAML, no Docker compose.

## Quick start

```bash
# macOS or Linux
curl -fsSL https://clawmetry.com/install.sh | bash
clawmetry connect
```

```
:: Windows
curl -fsSL https://clawmetry.com/install.cmd -o install.cmd && install.cmd
clawmetry connect
```

Open http://localhost:8900. Or open https://app.clawmetry.com after `clawmetry connect`.

## Use cases

- Monitor AI agent token spending before the invoice arrives.
- Debug sub-agent behavior by watching real-time activity.
- Catch a runaway agent loop before it burns $200/hour.
- Compare cache hit rate across models and prompts.
- Prove per-runtime cost breakdowns to finance.
- Track cron job health across scopes.
- Review session transcripts for quality assurance.
- Enforce policy: pause on risky tool calls, deny to kill.

## ClawMetry Cloud

ClawMetry Cloud lets you reach your dashboard from anywhere, not just localhost. It is end-to-end encrypted: your agent data is AES-256-GCM encrypted on your machine before it leaves, and decrypted only in your browser with your key. The cloud server stores and serves an opaque blob and can never read your data.

Pricing: Starter $9/node/mo (all 27 paid runtimes, unlimited nodes, cloud sync, budget alerts, approval queue), Pro $19/node/mo (adds policy gates, eval suite, per-run waste flags, compare view, error triage, Self-Evolve findings, OTel export). Learn more at https://clawmetry.com/pricing and https://clawmetry.com/cloud.

Prefer to stay local? Run `clawmetry disconnect` on the box; the local dashboard at http://localhost:8900 keeps working with nothing leaving your machine.

## Technical details

- Client is a Python package (single binary via pipx if you want).
- Auto-detects every supported runtime on the machine. Zero config: no env var, no SDK, no runtime code change.
- SSE for real-time updates in the local dashboard.
- REST API for programmatic access.
- End-to-end encrypted sync to ClawMetry Cloud (optional; local-only is the default).
- Read-only by design. ClawMetry observes; it never writes to the runtime it is watching.

## Key pages

- Home: https://clawmetry.com/
- How it works: https://clawmetry.com/how-it-works
- Pricing: https://clawmetry.com/pricing
- Cloud: https://clawmetry.com/cloud
- Documentation: https://clawmetry.com/docs
- Runtime pages: https://clawmetry.com/runtimes/qm (more rolling out weekly)
- What is AI agent observability: https://clawmetry.com/what-is-ai-agent-observability
- Blog: https://clawmetry.com/blog

ClawMetry is available in 36 languages; localized pages live under https://clawmetry.com/<lang>/ (for example https://clawmetry.com/ja/ or https://clawmetry.com/es/). Per-runtime pages are English-only in Phase 1 and 2; localised versions arrive in Phase 3.