Get started

Quickstart#

Ten minutes, five steps, no configuration. By the end you will have the dashboard running, know what your agents cost, and have Claude Code able to query its own history.

1. Install and onboard#

pip install clawmetry
clawmetry onboard --local

--local skips every account prompt and writes a marker so nothing ever leaves the machine. Drop it if you want the cloud dashboard and phone approvals; you can connect later either way.

The wizard starts the sync daemon and opens http://localhost:8900.

2. Confirm your agents were found#

clawmetry runtimes

You should see the runtimes that are actually installed on this machine marked as detected. Detection is a filesystem check — it looks for each runtime's real store, not for a binary on your PATH.

clawmetry runtimes --json | jq '.runtimes[] | select(.detected) | .id'

If a runtime you use is missing, its data directory has probably been relocated. Every runtime's reference page lists the environment variable that points ClawMetry at it — for example CODEX_HOME for Codex or CLAWMETRY_CURSOR_DB for Cursor.

3. Read a session#

Open the dashboard and go to Conversations. Pick a session and you get the transcript with thinking separated from replies, every tool call with its arguments and result, and per-turn tokens and cost.

The same thing from the command line, because the store is queryable:

# five most recent sessions
curl -s 'http://localhost:8900/api/local/sessions?limit=5' | jq '.rows'

# everything that happened in one of them
curl -s 'http://localhost:8900/api/local/transcript/<session-id>' | jq '.rows[] | {ts, event_type, tool_name}'

4. Answer a cost question#

Go to Cost. The first question most people have is "what did this week cost, and where did it go" — that is the runtime and model breakdown at the top of the page.

curl -s 'http://localhost:8900/api/local/aggregates' | jq '.rows[-7:]'

Cost is derived at ingest from the token split and the model, using a multi-provider pricing table. Where a runtime records real dollars — Cline, opencode, Pi, Copilot, Exo — ClawMetry uses those instead of estimating. Where neither is available it says so. How cost is computed explains which is which.

5. Let your agent query its own history#

This is the part people underestimate. Start the MCP server:

clawmetry mcp

Then register it with Claude Code:

claude mcp add clawmetry -- clawmetry mcp

Now you can ask, inside Claude Code:

Using clawmetry, what did I spend on Cursor versus Claude Code this week, and which of my sessions had the most repeated tool failures?

The agent calls get_cost_summary and list_sessions, reads its own telemetry, and answers. Agents & MCP covers the full tool surface and a set of recipes worth copying.

Where to go next#