# ClawMetry

> Real-time observability and governance for 19 AI agent runtimes. The Grafana for your AI agents.

## What is ClawMetry?

ClawMetry is a free, open-source observability dashboard for AI agents. It gives you real-time visibility into what your AI agents are doing — token usage, cost per hour, sub-agent activity, cron jobs, memory changes, and session history — across every runtime you run.

## The 19 runtimes ClawMetry observes

Free on every plan: **OpenClaw**, **NVIDIA NemoClaw**.

Paid (Cloud Pro $19/node/month or Self-Hosted Pro): **Claude Code**, **Codex**, **Cursor**, **Aider**, **Goose**, **opencode**, **Qwen Code**, **Hermes**, **PicoClaw**, **NanoClaw**, **Pi**, **Deep Agents**, **n8n**, **Antigravity**, **GitHub Copilot**, **Grok**, **QM** (YC's multiplayer agent harness).

For each runtime the ClawMetry daemon reads the runtime's native session store (JSONL, SQLite, or Postgres) in read-only mode. No SDK to add. No runtime code change. Per-runtime docs land under `https://clawmetry.com/runtimes/<name>` — `https://clawmetry.com/runtimes/qm` is the first, more roll out weekly.

## Key facts

- **License:** MIT (client) + closed pro adapters served only to activated installs
- **Install (macOS or Linux):** `curl -fsSL https://clawmetry.com/install.sh | bash`
- **Install (Windows):** `curl -fsSL https://clawmetry.com/install.cmd -o install.cmd && install.cmd`
- **Then:** `clawmetry connect` (or leave it local-only at `http://localhost:8900`)
- **Website:** https://clawmetry.com
- **GitHub:** https://github.com/vivekchand/clawmetry
- **PyPI:** https://pypi.org/project/clawmetry/
- **Platforms:** macOS, Linux, Windows, Raspberry Pi
- **Requirements:** Python 3.9+
- **Setup time:** about 30 seconds

## Features

- **Real-time cost per hour, per node, per runtime, per session.** Every session shows its token split (input, output, cache-read, cache-write), model routing, and per-turn cost. The Cost tab rolls up per hour and flags outliers before they blow the budget.
- **Caching and reuse metrics.** ClawMetry surfaces cache-read vs uncached-input tokens per call, so you can see prompt-cache hit rate per session and per model. Cache-aware cost accounting is on by default.
- **Token-maxing detection and kill switch.** ClawMetry flags a session when it is token-maxing (a runaway loop that keeps sending the same prompt). The kill switch stops the session before the next call.
- **Live flow visualization** from user → channels → gateway → brain → tools → infrastructure, updating in real time.
- **Sub-agent monitoring.** Every sub-agent's files, commands, tools, thinking, and status in real time.
- **Cron job dashboard.** Scheduled jobs with status, schedule, last and next run, duration, and failure alerts.
- **Session history and transcript viewer.** Chat-bubble UI, color-coded roles, per-session runtime attribution.
- **Approval queue and policy gates.** Pause a session before it fires a risky tool; deny to kill.
- **Memory file browser.** Track changes to SOUL.md, MEMORY.md, AGENTS.md, daily notes.
- **Dark and light themes.**

## Visibility drives efficiency

ClawMetry's core claim: teams that can see per-hour token spend, cache hit rate, and runaway-loop signals in real time cut their LLM bill without slowing anything down. The observability → outcome loop is see-it, name-it, fix-it, measure-it.

- See it: real-time cost per hour and cache-read vs uncached-input tokens per call.
- Name it: this session is token-maxing; this model is uncached; this scope's cron burns $12/hour.
- Fix it: enable prompt caching, route routine work to a cheaper model, kill the runaway session.
- Measure it: cost-per-hour after the change vs before.

## How it compares

- **vs Grafana:** ClawMetry is zero-config and understands AI agent concepts (tokens, sub-agents, sessions, scopes) natively. Grafana needs an ingest pipeline and a schema you own.
- **vs Datadog:** ClawMetry is free, self-hosted, and your agents' conversations stay end-to-end encrypted under your key. Datadog is a great generic observability platform but costs 10x and does not understand agent-shaped signals.
- **vs LangSmith / Langfuse:** ClawMetry works at the runtime level (reads the runtime's native store) rather than requiring you to wrap every LLM call. If you already run Claude Code or qm or n8n, ClawMetry works today.
- **vs custom dashboards:** one pip install, no YAML, no Docker compose.

## Quick start

```bash
# macOS or Linux
curl -fsSL https://clawmetry.com/install.sh | bash
clawmetry connect
```

```
:: Windows (cmd.exe or PowerShell)
curl -fsSL https://clawmetry.com/install.cmd -o install.cmd && install.cmd
clawmetry connect
```

## Use cases

- Monitor AI agent token spending before the invoice arrives.
- Debug sub-agent behavior by watching real-time activity.
- Catch a runaway agent loop before it burns $200/hour.
- Compare cache hit rate across models and prompts.
- Prove per-runtime cost breakdowns to finance.
- Track cron job health across scopes.
- Review session transcripts for quality assurance.

## Technical details

- Client is a single Python package with minimal dependencies (Flask).
- Auto-detects the runtime's native session store.
- SSE (Server-Sent Events) for real-time updates.
- REST API for programmatic access.
- End-to-end encrypted sync to ClawMetry Cloud (optional; local-only is the default).