Documentation
ClawMetry documentation#
ClawMetry is a real-time observability and governance layer for AI agents. It reads what your agents already write to disk, stores it in a local DuckDB database on your machine, and gives you one dashboard across 31 runtimes — OpenClaw, Claude Code, Codex, Cursor, Copilot, Gemini CLI, Goose, Cline, OpenHands and the rest.
Observation is read-only. Intervention — pausing, stopping or killing a running agent — exists, is off by default, and is gated behind locks this documentation describes precisely.
pip install clawmetry && clawmetry onboardStart here#
Install, point it at your agents, and read your first session in about five minutes.
How it worksThe daemon, the store, the dashboard and the three ingest paths, in one diagram.
Runtime supportAll 31 runtimes, what each one exposes, and where its data actually lives.
Agents & MCPLet Claude Code — or any MCP client — read its own history and diagnose itself.
CLI referenceEvery command, every flag, every JSON output shape.
GuardDetect agents that go off track, and stop them — with the safety interlocks spelled out.
What ClawMetry answers#
| Question | Where to look |
|---|---|
| What are my agents doing right now? | Activity, Home |
| What did last week cost, and which agent spent it? | Cost, How cost is computed |
| Why did that session burn $40 and produce nothing? | Detectors, Reducing spend |
| Is one of my agents stuck in a loop right now? | Guard |
| Can I stop it without killing my terminal? | Pause, stop, kill |
| Can my coding agent look up what it did yesterday? | MCP self-diagnosis |
| Where is my data, and who can read it? | The local store, End-to-end encryption |
| How do I feed in an agent that isn't on the list? | Custom runtime ingest, OpenTelemetry |
The shape of the system#
Three things run, and only the first one is required:
- The dashboard (
clawmetry) serves the UI onhttp://localhost:8900. It
reads; it never writes to the store.
- The sync daemon (
clawmetry sync) does the ingesting. It owns the DuckDB
writer lock, watches every runtime it can find, and — if you connected a cloud account — pushes an encrypted snapshot upward.
- The enforcement proxy (
clawmetry proxy start) is optional and sits in
front of your model calls to apply budget limits and loop detection.
Read How it works for the full picture, including why handlers read through the daemon instead of opening the database directly.
New to agent observability?
If you are not sure what belongs in this category at all, the What is ClawMetry? page explains the problem before the product.
Conventions in these docs#
- Commands are shown for a POSIX shell. Windows equivalents are given where
they differ in more than the path separator.
~/.clawmetry/is ClawMetry's own state directory;~/.openclaw/and the
other ~/.<runtime>/ directories belong to the agents and are only ever read.
- Where a runtime does not persist something, these docs say so rather than
describing a feature that would quietly return nothing.
- Every page is available as raw Markdown by appending
index.mdto its URL,
and the whole map is at /docs/llms.txt — both for the benefit of agents reading this.