---
title: ClawMetry Documentation
description: Install, the CLI, all {{RUNTIME_COUNT}} agent runtimes, the dashboard page by page, the MCP server, Guard policies, the query API and every environment variable.
keywords: ClawMetry documentation, AI agent observability, agent telemetry, Claude Code monitoring, Cursor usage tracking, LLM cost tracking, agent governance, MCP server
eyebrow: 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 **{{RUNTIME_COUNT}} 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.

```bash title="Install"
pip install clawmetry && clawmetry onboard
```

## Start here

<div class="card-grid">
<a class="card" href="/docs/start/quickstart/"><span class="card-title">Quickstart</span><p>Install, point it at your agents, and read your first session in about five minutes.</p></a>
<a class="card" href="/docs/start/how-it-works/"><span class="card-title">How it works</span><p>The daemon, the store, the dashboard and the three ingest paths, in one diagram.</p></a>
<a class="card" href="/docs/runtimes/overview/"><span class="card-title">Runtime support</span><p>All {{RUNTIME_COUNT}} runtimes, what each one exposes, and where its data actually lives.</p></a>
<a class="card" href="/docs/mcp/overview/"><span class="card-title">Agents & MCP</span><p>Let Claude Code — or any MCP client — read its own history and diagnose itself.</p></a>
<a class="card" href="/docs/cli/overview/"><span class="card-title">CLI reference</span><p>Every command, every flag, every JSON output shape.</p></a>
<a class="card" href="/docs/guard/overview/"><span class="card-title">Guard</span><p>Detect agents that go off track, and stop them — with the safety interlocks spelled out.</p></a>
</div>

## What ClawMetry answers

| Question | Where to look |
|---|---|
| What are my agents doing right now? | [Activity](/docs/dashboard/activity/), [Home](/docs/dashboard/home/) |
| What did last week cost, and which agent spent it? | [Cost](/docs/dashboard/cost/), [How cost is computed](/docs/cost/model/) |
| Why did that session burn $40 and produce nothing? | [Detectors](/docs/guard/detectors/), [Reducing spend](/docs/cost/optimization/) |
| Is one of my agents stuck in a loop *right now*? | [Guard](/docs/dashboard/guard/) |
| Can I stop it without killing my terminal? | [Pause, stop, kill](/docs/guard/process-control/) |
| Can my coding agent look up what it did yesterday? | [MCP self-diagnosis](/docs/mcp/self-diagnosis/) |
| Where is my data, and who can read it? | [The local store](/docs/data/store/), [End-to-end encryption](/docs/cloud/encryption/) |
| How do I feed in an agent that isn't on the list? | [Custom runtime ingest](/docs/runtimes/custom-ingest/), [OpenTelemetry](/docs/runtimes/opentelemetry/) |

## The shape of the system

Three things run, and only the first one is required:

1. **The dashboard** (`clawmetry`) serves the UI on `http://localhost:8900`. It
   reads; it never writes to the store.
2. **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.
3. **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](/docs/start/how-it-works/) for the full picture, including
why handlers read through the daemon instead of opening the database directly.

:::note New to agent observability?
If you are not sure what belongs in this category at all, the
[What is ClawMetry?](/docs/start/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.md` to its URL,
  and the whole map is at [/docs/llms.txt](/docs/llms.txt) — both for the
  benefit of agents reading this.