# ClawMetry documentation

> Real-time observability and governance for AI agents across 32 runtimes. Every link below is the raw Markdown of that docs page; drop the trailing index.md for the rendered HTML.

## Get started

- [What is ClawMetry?](https://clawmetry.com/docs/start/what-is-clawmetry/index.md): ClawMetry is a local-first observability and governance layer for AI coding agents. It reads what 32 runtimes already write to disk and makes it answerable.
- [Install](https://clawmetry.com/docs/start/install/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): All 32 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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.
- [Muse Code](https://clawmetry.com/docs/runtime/muse-code/index.md): How ClawMetry observes Muse Code — 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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.
- [OpenExecutive](https://clawmetry.com/docs/runtime/openexecutive/index.md): How ClawMetry observes OpenExecutive — 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): Running the ClawMetry dashboard — every flag, the background service subcommands, and the workspace and directory options.
- [onboard / setup](https://clawmetry.com/docs/cli/onboard/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): Getting data out of ClawMetry — session and trace exports, CSV from the reports browser, the raw query API, OTLP push and SIEM export.

## Cloud & fleet

- [What the cloud adds](https://clawmetry.com/docs/cloud/overview/index.md): 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/index.md): How ClawMetry protects session content in the cloud — AES-256-GCM with a key the server never stores, the plaintext split, and how to verify it yourself.
- [Nodes and fleet](https://clawmetry.com/docs/cloud/nodes/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): Keeping ClawMetry alive across reboots — launchd on macOS, systemd on Linux, supervisord, and the pattern for containers.
- [Docker](https://clawmetry.com/docs/config/docker/index.md): 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/index.md): 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/index.md): Running ClawMetry safely — the read-only contract, redaction, credential scanning, what the store contains, the intervention surfaces and a hardening checklist.

## Enterprise

- [Fleet rollout guide](https://clawmetry.com/docs/enterprise/rollout/index.md): Silent install, virtual desktop images, shared Linux hosts, enrollment, proxy and CA, and a self-hosted server in your tenant, with what each was tested on.

## HTTP API

- [API overview](https://clawmetry.com/docs/api/overview/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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/index.md): 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.