# ClawMetry documentation

> Real-time observability and governance for AI agents across 31 runtimes. Every page below is also available as raw Markdown at the same URL + index.md.

## Get started
- [What is ClawMetry?](https://clawmetry.com/docs/start/what-is-clawmetry/): ClawMetry is a local-first observability and governance layer for AI coding agents. It reads what 31 runtimes already write to disk and makes it answerable.
- [Install](https://clawmetry.com/docs/start/install/): Install ClawMetry with pip, the one-line installer, Homebrew-style scripts, Docker, or the macOS desktop app — plus what each method actually sets up.
- [Quickstart](https://clawmetry.com/docs/start/quickstart/): From pip install to reading your first agent session, answering your first cost question, and letting your coding agent query its own history.
- [How it works](https://clawmetry.com/docs/start/how-it-works/): The sync daemon that owns the DuckDB writer lock, the three ingest paths, the localhost query server, and how the dashboard reads without contending for it.
- [Local, cloud, or self-hosted](https://clawmetry.com/docs/start/deployment-modes/): The three ways to run ClawMetry — fully local, local compute with an encrypted cloud display, or a self-hosted ingest — and what each implies for your data.
- [Your first week](https://clawmetry.com/docs/start/first-week/): An ordered sequence for getting real value out of ClawMetry — see the spend, set a budget, wire one alert, set retention, then decide whether Guard may act.

## Runtimes
- [Runtime support](https://clawmetry.com/docs/runtimes/overview/): All 31 agent runtimes ClawMetry observes — OpenClaw, Claude Code, Codex, Cursor, Copilot, Gemini CLI, Goose, Cline, OpenHands and more — and what each exposes.
- [How detection works](https://clawmetry.com/docs/runtimes/detection/): How ClawMetry finds agent runtimes — filesystem probes rather than PATH lookups, discovery order, environment overrides, and why one can be detected but empty.
- [What each runtime exposes](https://clawmetry.com/docs/runtimes/coverage/): A side-by-side of what token and cost data every supported agent runtime genuinely persists — and where ClawMetry reports unknown rather than estimating.
- [Chat channels](https://clawmetry.com/docs/runtimes/channels/): The 22 chat-channel adapters ClawMetry reads — Telegram, Signal, WhatsApp, Discord, Slack, iMessage, Matrix and more — and the concurrent-channel cap per tier.
- [Track any SDK agent](https://clawmetry.com/docs/runtimes/sdk-agents/): Two lines of Python capture cost, tokens, latency and errors from any agent built on the OpenAI Agents SDK, LangChain, LlamaIndex, the Vercel AI SDK or httpx.
- [Custom runtime ingest API](https://clawmetry.com/docs/runtimes/custom-ingest/): Push runs and events into ClawMetry over HTTP from any agent runtime — the endpoint reference, event payload schema, auth modes, and idempotency rules.
- [OpenTelemetry ingest](https://clawmetry.com/docs/runtimes/opentelemetry/): Send OTLP traces, metrics and logs into ClawMetry from any agent framework, and export ClawMetry's own telemetry back out to your existing observability stack.

## Runtime reference
- [Aider](https://clawmetry.com/docs/runtime/aider/): How ClawMetry observes Aider — where its data lives, the environment variables that move it, what cost data is real, and the traps in its store.
- [Antigravity](https://clawmetry.com/docs/runtime/antigravity/): How ClawMetry observes Antigravity — where its data lives, the environment variables that move it, what cost data is real, and the traps in its store.
- [Claude Code](https://clawmetry.com/docs/runtime/claude-code/): How ClawMetry observes Claude Code — where its data lives, the environment variables that move it, what cost data is real, and the traps in its store.
- [Cline](https://clawmetry.com/docs/runtime/cline/): How ClawMetry observes Cline — where its data lives, the environment variables that move it, what cost data is real, and the traps in its store.
- [Codex](https://clawmetry.com/docs/runtime/codex/): How ClawMetry observes Codex — where its data lives, the environment variables that move it, what cost data is real, and the traps in its store.
- [Cursor](https://clawmetry.com/docs/runtime/cursor/): How ClawMetry observes Cursor — where its data lives, the environment variables that move it, what cost data is real, and the traps in its store.
- [Deep Agents](https://clawmetry.com/docs/runtime/deep-agents/): How ClawMetry observes Deep Agents — where its data lives, the environment variables that move it, what cost data is real, and the traps in its store.
- [DeepSeek Harness](https://clawmetry.com/docs/runtime/deepseek-harness/): How ClawMetry observes DeepSeek Harness — where its data lives, the environment variables that move it, what cost data is real, and the traps in its store.
- [Devin](https://clawmetry.com/docs/runtime/devin/): How ClawMetry observes Devin — where its data lives, the environment variables that move it, what cost data is real, and the traps in its store.
- [Exo](https://clawmetry.com/docs/runtime/exo/): How ClawMetry observes Exo — where its data lives, the environment variables that move it, what cost data is real, and the traps in its store.
- [Gemini CLI](https://clawmetry.com/docs/runtime/gemini-cli/): How ClawMetry observes Gemini CLI — where its data lives, the environment variables that move it, what cost data is real, and the traps in its store.
- [GitHub Copilot](https://clawmetry.com/docs/runtime/copilot/): How ClawMetry observes GitHub Copilot — where its data lives, the environment variables that move it, what cost data is real, and the traps in its store.
- [Goose](https://clawmetry.com/docs/runtime/goose/): How ClawMetry observes Goose — where its data lives, the environment variables that move it, what cost data is real, and the traps in its store.
- [Grok](https://clawmetry.com/docs/runtime/grok/): How ClawMetry observes Grok — where its data lives, the environment variables that move it, what cost data is real, and the traps in its store.
- [Grok Bot](https://clawmetry.com/docs/runtime/grok-bot/): How ClawMetry observes Grok Bot — where its data lives, the environment variables that move it, what cost data is real, and the traps in its store.
- [Hermes](https://clawmetry.com/docs/runtime/hermes/): How ClawMetry observes Hermes — where its data lives, the environment variables that move it, what cost data is real, and the traps in its store.
- [Kimi](https://clawmetry.com/docs/runtime/kimi/): How ClawMetry observes Kimi — where its data lives, the environment variables that move it, what cost data is real, and the traps in its store.
- [Lovable](https://clawmetry.com/docs/runtime/lovable/): How ClawMetry observes Lovable — where its data lives, the environment variables that move it, what cost data is real, and the traps in its store.
- [n8n](https://clawmetry.com/docs/runtime/n8n/): How ClawMetry observes n8n — where its data lives, the environment variables that move it, what cost data is real, and the traps in its store.
- [NanoClaw](https://clawmetry.com/docs/runtime/nanoclaw/): How ClawMetry observes NanoClaw — where its data lives, the environment variables that move it, what cost data is real, and the traps in its store.
- [NemoClaw](https://clawmetry.com/docs/runtime/nemoclaw/): How ClawMetry observes NemoClaw — where its data lives, the environment variables that move it, what cost data is real, and the traps in its store.
- [OpenClaw](https://clawmetry.com/docs/runtime/openclaw/): How ClawMetry observes OpenClaw — where its data lives, the environment variables that move it, what cost data is real, and the traps in its store.
- [opencode](https://clawmetry.com/docs/runtime/opencode/): How ClawMetry observes opencode — where its data lives, the environment variables that move it, what cost data is real, and the traps in its store.
- [OpenHands](https://clawmetry.com/docs/runtime/openhands/): How ClawMetry observes OpenHands — where its data lives, the environment variables that move it, what cost data is real, and the traps in its store.
- [OpenWorker](https://clawmetry.com/docs/runtime/openworker/): How ClawMetry observes OpenWorker — where its data lives, the environment variables that move it, what cost data is real, and the traps in its store.
- [Pi](https://clawmetry.com/docs/runtime/pi/): How ClawMetry observes Pi — where its data lives, the environment variables that move it, what cost data is real, and the traps in its store.
- [PicoClaw](https://clawmetry.com/docs/runtime/picoclaw/): How ClawMetry observes PicoClaw — where its data lives, the environment variables that move it, what cost data is real, and the traps in its store.
- [QM](https://clawmetry.com/docs/runtime/qm/): How ClawMetry observes QM — where its data lives, the environment variables that move it, what cost data is real, and the traps in its store.
- [Qwen Code](https://clawmetry.com/docs/runtime/qwen-code/): How ClawMetry observes Qwen Code — where its data lives, the environment variables that move it, what cost data is real, and the traps in its store.
- [Replit Agent](https://clawmetry.com/docs/runtime/replit/): How ClawMetry observes Replit Agent — where its data lives, the environment variables that move it, what cost data is real, and the traps in its store.

## Dashboard
- [Dashboard tour](https://clawmetry.com/docs/dashboard/overview/): Every page of the ClawMetry dashboard, what question it answers, and where its data comes from — Home, Agents, Activity, Cost, Guard, Alerts and the rest.
- [Home](https://clawmetry.com/docs/dashboard/home/): The ClawMetry overview page — live agent status, spend today, session activity timeline, health signals, and the badges that tell you something needs attention.
- [Agents](https://clawmetry.com/docs/dashboard/agents/): The agent inventory — one row per agent on the node with its runtime, spend, liveness and owner, plus how liveness is actually derived.
- [Activity](https://clawmetry.com/docs/dashboard/activity/): The live step-by-step feed of what every agent is doing — reasoning, tool calls, results and errors — with a streaming SSE endpoint and per-event drill-down.
- [Cost](https://clawmetry.com/docs/dashboard/cost/): Token and spend analytics across every runtime and model — breakdowns, trends, cache efficiency, attribution, anomaly detection and the optimizer.
- [Conversations](https://clawmetry.com/docs/dashboard/conversations/): Session transcripts across every runtime and chat channel — thinking split from replies, per-turn tokens and cost, tool timelines, compactions and sub-agents.
- [Approvals](https://clawmetry.com/docs/dashboard/approvals/): The human-in-the-loop approval queue — how an agent asks permission, where the request surfaces, how a decision is delivered, and what if nobody answers.
- [Guard](https://clawmetry.com/docs/dashboard/guard/): The Guard tab — live sessions ranked by spend at risk, detector incidents, Pause/Stop/Kill with honest per-session capability, and the policy decision log.
- [Alerts](https://clawmetry.com/docs/dashboard/alerts/): Alert rules, webhooks and delivery channels — spend velocity, budget breaches, failure patterns and agent silence — and how to avoid alerts everyone mutes.
- [Developer views](https://clawmetry.com/docs/dashboard/developer/): The deep-dive tabs — Flow, Models, LLM Context, Agent Graph, Tools, Context usage, Runtime extras and Ask — and what each one is genuinely useful for.
- [Advanced views](https://clawmetry.com/docs/dashboard/advanced/): Schedules, Memory, Notifications, Logs, Security, Tool permissions, Skills, Self-Evolve, Version impact and NemoClaw governance.

## CLI reference
- [CLI overview](https://clawmetry.com/docs/cli/overview/): Every ClawMetry command in one table, the global flags, the shape of --json output, and how the dashboard flags differ from the subcommands.
- [clawmetry](https://clawmetry.com/docs/cli/clawmetry/): Running the ClawMetry dashboard — every flag, the background service subcommands, and the workspace and directory options.
- [onboard / setup](https://clawmetry.com/docs/cli/onboard/): The ClawMetry first-run wizard — every flag, local-only mode, non-interactive cloud onboarding, and what the wizard actually does.
- [connect / disconnect](https://clawmetry.com/docs/cli/connect/): Connecting a node to ClawMetry Cloud — every flag on connect, the ownership OTP, deferred sync, key-only mode, and how to cleanly disconnect.
- [sync](https://clawmetry.com/docs/cli/sync/): The ClawMetry sync daemon — what it does on each cycle, how to start and restart it safely, running it in the foreground, and the environment that tunes it.
- [status](https://clawmetry.com/docs/cli/status/): clawmetry status — the daemon, store and cloud state at a glance, the live one-line status bar, and the JSON envelope for scripting.
- [mcp](https://clawmetry.com/docs/cli/mcp/): clawmetry mcp — start the Model Context Protocol server that lets coding agents query their own ClawMetry telemetry over stdio.
- [proxy](https://clawmetry.com/docs/cli/proxy/): The ClawMetry enforcement proxy — budget limits, loop detection and model routing on port 4100, with every subcommand and flag.
- [eval](https://clawmetry.com/docs/cli/eval/): clawmetry eval — run golden eval suites against your agents, watch mode for the dev loop, JSON output for CI, and regression replay of last week's failures.
- [tier, runtimes, features…](https://clawmetry.com/docs/cli/entitlement-commands/): The entitlement inspection commands — tier, runtimes, features, channels, nodes, retention and bundle — with their JSON shapes and --why lock-reason payloads.
- [license / activate](https://clawmetry.com/docs/cli/license/): Managing a self-hosted Pro or Enterprise license — activate, verify, deactivate, the machine fingerprint, and offline verification.
- [diagnose / verify-integrity](https://clawmetry.com/docs/cli/diagnose/): clawmetry diagnose shows every input the entitlement resolver used; clawmetry verify-integrity checks the tamper-evident hash chain over local events.
- [update / uninstall / reports](https://clawmetry.com/docs/cli/maintenance/): Keeping ClawMetry current, removing it completely, browsing generated reports, and inspecting loaded plugins.
- [Exit codes and JSON output](https://clawmetry.com/docs/cli/exit-codes/): How ClawMetry commands behave in scripts and CI — exit codes, the shared --json envelope conventions, and patterns for monitoring wrappers.

## Agents & MCP
- [Let agents read their own telemetry](https://clawmetry.com/docs/mcp/overview/): The ClawMetry MCP server gives Claude Code, Cursor and any MCP client their own session history, cost and traces — so a coding agent can diagnose itself.
- [Connect the MCP server](https://clawmetry.com/docs/mcp/install/): Register ClawMetry's MCP server with Claude Code, Cursor, Codex, Goose and any other MCP client — with verification steps and the troubleshooting table.
- [MCP tool reference](https://clawmetry.com/docs/mcp/tools/): Complete reference for the five ClawMetry MCP tools — arguments, defaults, limits, the query shape each one maps to, and the JSON-RPC calls behind them.
- [Self-diagnosis recipes](https://clawmetry.com/docs/mcp/self-diagnosis/): Prompts and patterns for letting a coding agent diagnose itself — catching its own loops, checking whether it has failed this way before, and costing its plan.
- [Cross-runtime questions](https://clawmetry.com/docs/mcp/cross-runtime/): ClawMetry's store holds every runtime on the machine, so an agent in one tool can compare cost, tool reliability and which harness actually finishes work.
- [Skills and prompts](https://clawmetry.com/docs/mcp/skills/): Turning ClawMetry MCP recipes into reusable skills and agent instructions, so self-diagnosis happens without anyone remembering to ask.

## Guard & governance
- [What Guard does](https://clawmetry.com/docs/guard/overview/): Guard detects agents that have gone off track and, only when you opt in, stops them. The detectors, the policy engine, the actuator and the three locks.
- [Detectors](https://clawmetry.com/docs/guard/detectors/): The eight ClawMetry detectors — four trajectory signals that find a stuck agent, four behavioural ones that find an unusual one — with thresholds and evidence.
- [Thresholds and baselines](https://clawmetry.com/docs/guard/thresholds/): How ClawMetry decides what unusual means — four layers from module default to learned cohort baseline, the clamping band, and per-runtime environment overrides.
- [Policies and escalation](https://clawmetry.com/docs/guard/policies/): Guard policies turn a detector incident into an enforcement decision — matching fields, five actions, escalation ladders, the durable latch and the three locks.
- [Pause, stop, kill](https://clawmetry.com/docs/guard/process-control/): What ClawMetry's process controls do — POSIX signals, the Windows native equivalents, pid-reuse guarding, and why an OpenClaw pause needs the enforcement proxy.
- [Enforcement proxy](https://clawmetry.com/docs/guard/proxy/): The optional ClawMetry proxy in front of model calls — hard budget limits, in-flight loop detection, model routing, and the OpenClaw pause it makes real.
- [Approvals and pre-tool gates](https://clawmetry.com/docs/guard/approvals/): Holding an agent action before the tool runs — how pre-tool hooks work per runtime, which are fail-closed, the HITL queue, and phone approvals.
- [Tool permissions](https://clawmetry.com/docs/guard/tool-policy/): Which tools an agent may run, where it may run them, and what was approved or blocked — the pre-tool permission axis, kept separate from Guard policies.

## Cost & usage
- [How cost is computed](https://clawmetry.com/docs/cost/model/): Where ClawMetry's dollar figures come from — derivation at ingest, the multi-provider pricing table, cache-aware accounting, and the cost honesty states.
- [Attribution](https://clawmetry.com/docs/cost/attribution/): Turning a cost total into an answer — attribution by runtime, model, session, agent, skill, tool and team, plus the sub-agent rules that stop double-counting.
- [Budgets and limits](https://clawmetry.com/docs/cost/budgets/): Setting spend limits that actually hold — the proxy for hard limits, budget alerts for soft ones, per-agent budgets, emergency stop, and how they combine.
- [Anomaly detection](https://clawmetry.com/docs/cost/anomalies/): Spotting spend that does not look like your normal pattern — how the baseline is built, what token velocity measures, and why a fixed threshold is wrong.
- [Reducing spend](https://clawmetry.com/docs/cost/optimization/): The levers that actually move agent cost — cache hit rate, model routing, context discipline and cutting work that produces nothing — and how to measure each.

## Data & storage
- [The local DuckDB store](https://clawmetry.com/docs/data/store/): Where ClawMetry keeps your data — the DuckDB file, the writer-lock model, the localhost query server, sizing and compaction, and how to back it up safely.
- [Query API](https://clawmetry.com/docs/data/query-api/): The q/1 query contract — thirteen live shapes with their arguments, limits and trust classes, plus the three ways to call them: HTTP, the daemon proxy, and MCP.
- [Event schema](https://clawmetry.com/docs/data/schema/): The unified event shape every runtime is normalised into — fields, event types, session identity and runtime namespacing, and the extension points.
- [Retention](https://clawmetry.com/docs/data/retention/): How long ClawMetry keeps events, the tier caps, the override variable, and what actually gets deleted when a window expires.
- [Tamper-evident integrity](https://clawmetry.com/docs/data/integrity/): ClawMetry's hash chain over local events — what it proves, what it does not, how to verify it, and how to read could not check against check failed.
- [Exports](https://clawmetry.com/docs/data/export/): Getting data out of ClawMetry — session and trace exports, CSV from the reports browser, the raw query API, OTLP push, SIEM export and the evidence pack.

## Cloud & fleet
- [What the cloud adds](https://clawmetry.com/docs/cloud/overview/): What connecting a node to ClawMetry Cloud gives you — a dashboard from anywhere, multi-node fleet, phone approvals, the device display — and what it does not.
- [End-to-end encryption](https://clawmetry.com/docs/cloud/encryption/): How ClawMetry protects session content in the cloud — AES-256-GCM with a key that never leaves your machine, the plaintext split, and how to verify it yourself.
- [Nodes and fleet](https://clawmetry.com/docs/cloud/nodes/): Running ClawMetry across several machines — node identity, naming, the fleet view, node caps, and the two identities a browser can hold.
- [Self-hosted ingest](https://clawmetry.com/docs/cloud/self-hosted/): Running the ClawMetry ingest endpoint yourself — the surface nodes push to, configuration, data residency, and when this is the right deployment.

## Configuration
- [Environment variables](https://clawmetry.com/docs/config/environment/): Every ClawMetry environment variable, grouped by what it controls — paths, ingest, store, Guard, cost, cloud, security and the per-runtime overrides.
- [Files and directories](https://clawmetry.com/docs/config/paths/): Every path ClawMetry reads or writes — its own state directory, the runtime directories it only ever reads, and what to back up.
- [Run it as a service](https://clawmetry.com/docs/config/service/): Keeping ClawMetry alive across reboots — launchd on macOS, systemd on Linux, supervisord, and the pattern for containers.
- [Docker](https://clawmetry.com/docs/config/docker/): Running ClawMetry in a container — mounting runtime directories read-only, persisting the store, the daemon-plus-dashboard split, and compose examples.
- [Ports and networking](https://clawmetry.com/docs/config/networking/): Which ports ClawMetry uses, why the dashboard binds to loopback by default, how to expose it safely behind a reverse proxy, and the API token model.
- [Hardening](https://clawmetry.com/docs/config/security/): Running ClawMetry safely — the read-only contract, redaction, credential scanning, what the store contains, the intervention surfaces and a hardening checklist.

## HTTP API
- [API overview](https://clawmetry.com/docs/api/overview/): How ClawMetry's HTTP surface is organised — the query API, the feature APIs, the ingest surfaces, authentication and response conventions.
- [Endpoint index](https://clawmetry.com/docs/api/index/): Every HTTP endpoint ClawMetry serves, grouped by feature, with methods — the query API, the dashboard feature APIs, the ingest surfaces and the controls.
- [Authentication](https://clawmetry.com/docs/api/auth/): How ClawMetry's HTTP surfaces authenticate — loopback by default, API tokens, the daemon query-server token, ingest tokens, OTLP auth and origin checks.

## Operations
- [Troubleshooting](https://clawmetry.com/docs/ops/troubleshooting/): A diagnostic order for ClawMetry — empty dashboard, missing runtime, no cost data, stalled sync, store problems, MCP failures and cloud sync issues.
- [Upgrades](https://clawmetry.com/docs/ops/upgrades/): How ClawMetry keeps itself current — the daemon update-check worker, the auto-update rails, the crash-loop rollback guard, and every switch that turns it off.
- [Uninstall](https://clawmetry.com/docs/ops/uninstall/): Removing ClawMetry completely — what the uninstaller takes, what it deliberately leaves alone, per-platform notes, and how to keep your account.
- [Plans and entitlements](https://clawmetry.com/docs/ops/plans/): How ClawMetry decides what this install can do — the seven tiers, the five capacity axes, feature and runtime tables, resolution order, grace mode and expiry.