Get started

Install#

ClawMetry is a Python package with four dependencies. The install puts a clawmetry command on your path and, on first run, sets up a background sync daemon.

Requirements#


Python	3.9 or newer (CI covers 3.9 and 3.11 on Linux, macOS and Windows)
Disk	The DuckDB store grows with your agent activity; a few hundred MB is typical. Retention bounds it.
Network	None required. Cloud sync is opt-in.
Agents	Anything from the runtime list. ClawMetry finds them itself.

pip#

The direct route, and the one every other method wraps.

bash

pip install clawmetry
clawmetry onboard

clawmetry onboard is the first-run wizard: it detects your runtimes, offers local-only or cloud mode, starts the sync daemon, and opens the dashboard. See onboard / setup for every flag, including the non-interactive forms.

To stay entirely local and never be asked about an account:

bash

clawmetry onboard --local

One-line installer#

Detects the OS, installs into a sensible interpreter, and starts ClawMetry.

macOS, Linux, WSL

curl -fsSL https://clawmetry.com/install.sh | bash

Windows PowerShell

iwr -useb https://clawmetry.com/install.ps1 | iex

Windows CMD

curl -fsSL https://clawmetry.com/install.cmd -o install.cmd && install.cmd && del install.cmd

Two Python installs

The single most common install problem is a machine with more than one Python: pip install clawmetry lands in one interpreter and clawmetry resolves to a shim from another. If the version you get from clawmetry --version is not the version you just installed, run python3 -m pip install --upgrade clawmetry and check which -a clawmetry.

Docker#

The container has no access to your host's agent directories unless you mount them, so mount whichever runtimes you want observed, read-only.

bash

docker build -t clawmetry .
docker run -p 8900:8900 \
  -v ~/.openclaw:/root/.openclaw:ro \
  -v ~/.claude:/root/.claude:ro \
  clawmetry

See Docker for volume layout, persisting the store across restarts, and the environment variables that matter in a container.

macOS desktop app#

A native menubar shell that pip-installs and supervises the same package. It runs alongside the CLI rather than replacing it — the daemon, store and dashboard are identical. Download it from the homepage.

Ask your agent to do it#

The setup is interactive, so run it in a long-lived terminal session rather than a one-shot command:

text

Help me install ClawMetry in a long-running PTY:
pip install clawmetry && clawmetry setup && set up clawmetry sync via supervisord

Verify the install#

bash

clawmetry --version          # the package version
clawmetry status             # daemon state, store size, last ingest
clawmetry runtimes           # what was detected on this machine
clawmetry diagnose           # entitlement + resolver inputs, if something looks locked

Then open http://localhost:8900.

If clawmetry status says the daemon is not running, start it with clawmetry sync. If the dashboard loads but every tab is empty, the daemon is the thing to look at first — the dashboard reads through it and shows nothing on its own. Troubleshooting walks the whole chain.

Keeping it current#

bash

clawmetry update             # or: pip install --upgrade clawmetry

The daemon also checks PyPI on a cadence and can update itself. That behaviour, and how to turn it off, is documented in Upgrades.

Edit this page View as Markdown Report an issue