vivekchand/clawmetry

What ClawMetry does

ClawMetry is a local dashboard that watches the session logs that AI‑coding agents already write. By reading those read‑only files it builds a timeline of every tool call, token usage and cost, letting you see at a glance whether an agent is making progress or just looping forever.

It works out‑of‑the‑box – you install the Python package and run clawmetry. The program starts a web UI on http://localhost:8900 and automatically discovers any of the 33 supported agent runtimes on the machine (e.g. Claude Code, OpenAI Codex, Cursor, OpenClaw, NVIDIA NemoClaw, etc.). No code changes, SDK imports, or instrumentation are required.

---

Core capabilities

Feature	What you see	How it’s obtained
Session replay	Turn‑by‑turn transcript with timestamps, tool calls and model replies.	Reads the runtime’s session files (read‑only).
Cost & token breakdown	Daily, weekly, monthly spend per agent, per model, with anomaly flags.	Parses token‑count and pricing data exposed by each runtime.
Flow diagram	Live graph showing messages moving from user → gateway → model → tools.	Built from the same session logs; no extra network traffic.
Context‑window usage	Percent of each provider’s context window, compaction events, overflow warnings.	Uses a built‑in table of provider‑specific window sizes (Anthropic, OpenAI, Google, etc.).
Memory/skill loading	Files and “skills” each agent actually loaded.	Extracted from runtime metadata.
Health & alerts	Disk/memory usage, rate‑limit hits, error spikes, budget caps; can push to Slack, Discord, PagerDuty, Telegram, Email.	Monitored locally; optional outbound webhook.
Approvals	Pause risky tool calls (e.g., sudo, secret expose) and approve/deny from a phone.	Requires the optional enforcement proxy; off by default.
SDK tracking	If you build an agent on LangChain, Pydantic‑AI, etc., ClawMetry can attribute LLM calls to your code.	Via an interceptor that can be enabled (CLAWMETRY_INTERCEPT=1).

---

How you use it

1. Install – pip install clawmetry (Python 3.8+).
2. Run – clawmetry starts the daemon and opens the UI.
3. Explore – The header lets you switch between runtimes; each tab shows the views listed above.
4. (Optional) Connect – clawmetry connect uploads an encrypted snapshot to the cloud for remote viewing; otherwise everything stays on your machine.

If you have no agents yet, clawmetry --sample loads three synthetic sessions so you can explore the UI.

---

Pricing & licensing

• Free tier – Works locally with OpenClaw, NVIDIA NemoClaw, Goose and Qwen Code. No data leaves the box.
• Starter ($9 / node / month) – Adds the other 28 runtimes and cloud‑sync of snapshots.
• Pro ($19 / node / month) – Adds approvals, policy engine, anomaly detection, cost optimizer, OpenTelemetry export, tamper‑evident audit log, etc.

All tiers are MIT‑licensed source; paid features are delivered via a closed‑source companion (clawmetry‑pro).

---

Data‑privacy & network traffic

• By default no session content is sent anywhere.
• The only outbound calls are an anonymous install ping, a PyPI version check, and a one‑time public‑IP lookup for a banner.
• Both are opt‑out and documented in docs/EGRESS.md.
• When you explicitly run clawmetry connect, the snapshot is end‑to‑end encrypted; the decryption happens in the browser using a static JS file whose integrity is verified.

---

Performance impact

Instrumentation point	Added latency (typical)	Default state
Session‑file tailing	0 ms (separate process)	on
HTTP interceptor	+0.44 ms per LLM call	off
Pre‑tool hook gate	+44 ms per gated call	off
Enforcement proxy	+9.7 ms per LLM call	off

The daemon itself uses about 12 % of one CPU core and ~70 KB per 100 k events on disk. Benchmarks are provided in benchmarks/overhead.py.

---

Who might benefit?

• Developers running multiple coding agents (e.g., on a CI server or personal workstation) who need a single pane of glass to spot stuck loops, cost overruns, or risky tool usage.
• Team leads who want to enforce budget caps or require manual approval for dangerous actions.
• Researchers comparing the behaviour of different agent runtimes without modifying their code.

---

Limitations & caveats

• The dashboard can only show data that each runtime actually logs; some runtimes expose no cost information, which is reflected in the compatibility matrix.
• Context‑window percentages are calculated against a provider‑specific window size; if a runtime uses a model with a larger window than the table entry, the percentage may appear inflated.
• Approvals and policy enforcement require the optional proxy component, which is off by default.
• The free tier only supports four runtimes; the rest need a paid plan or the clawmetry‑pro companion.

---

Quick start snippet

pip install clawmetry               # install the package
clawmetry                           # start the daemon & open the UI
# If you have no agents yet:
clawmetry --sample                  # load synthetic sessions for demo

---

Where to learn more

• Docs – docs/ contains detailed guides on compatibility, context blowout, overhead, approvals, OpenTelemetry export, and how to add your own agent runtime.
• Screenshots – The README includes several screenshots showing cost breakdowns, flow diagrams, alerts, and quality grades.
• Pricing – Full pricing table at https://clawmetry.com/pricing.

ClawMetry is essentially a monitoring and observability layer for AI coding agents, giving you visibility, cost awareness, and safety controls without requiring any changes to the agents themselves.