Get started

Your first week#

Installing takes a minute. Getting value takes a handful of deliberate choices. This is the order that works, and each step is useful on its own if you stop there.

Day 1 — look at what is already there#

Do nothing but read. The daemon has now ingested your history, so the numbers are real rather than a sample.

• Cost → this month. Which runtime dominates? Which model? Almost everyone

is surprised by at least one row.

• Agents. Every agent on the machine, what it runs, what it costs, whether

it is alive. Look for things you forgot were running.

• Activity. Watch a live session step through. This is the fastest way to

understand what your agent actually does with a prompt.

If a runtime you use is missing, fix that now — its reference page names the environment variable.

Day 2 — set a budget#

A budget is worth setting before an alert, because it is the thing that makes an alert actionable.

clawmetry proxy config --daily-budget 25 --monthly-budget 400 --action warn

Start with warn. Move to block or downgrade once you trust the numbers. See Budgets and limits.

Day 3 — wire exactly one alert#

One. The failure mode here is configuring eight rules on day three and muting all of them by day ten.

Pick the one that would actually have caught your worst recent surprise — usually a spend velocity rule or a repeated-tool-failure rule. Set it up in Alerts, then send a test so you know the delivery path works.

Day 4 — set retention#

The store grows with your agents. Decide how much history you need.

clawmetry retention              # what the current window is and why

Free tiers cap at 7 days, paid tiers extend it, and CLAWMETRY_RETENTION_DAYS overrides within what your tier allows. See Retention.

Day 5 — read one bad session end to end#

Find a session in Guard or Cost that cost more than it should have. Open it in Conversations and read it. Then look at what the detectors said about it.

This is the step that changes how you write prompts, and it is the reason the transcript view separates thinking from replies.

Week 2 — decide about Guard#

Now that you have seen the incidents, decide whether ClawMetry may act on them.

Start in monitor mode. A new policy defaults to monitor, which records what it would have done and changes nothing:

# leave CLAWMETRY_POLICY_ENFORCE unset — the default is 0, dry run

Let it run for a few days and read the decision log. If the policy would have fired on the right sessions and nothing else, then — and only then — turn on enforcement:

export CLAWMETRY_POLICY_ENFORCE=1

The full model, including escalation ladders and the three locks every action passes, is in Policies and escalation.

Week 2 — connect your coding agent#

claude mcp add clawmetry -- clawmetry mcp

Then start asking it about its own work. The self-diagnosis recipes are the fastest way to see why this is more than a party trick.

What to skip at first#

• Custom runtime ingest, unless you already have an agent that writes nothing

to disk.

• The eval suite, until you have a failure you want to stop recurring.
• Multi-node fleet, until you actually have a second node.