Metadata-Version: 2.4
Name: clawmetry
Version: 0.12.725
Summary: ClawMetry - Real-time observability for 21 AI agent runtimes (OpenClaw, NVIDIA NemoClaw, Claude Code, Codex & more)
Home-page: https://github.com/vivekchand/clawmetry
Author: Vivek Chand
Author-email: vivek@clawmetry.com
License: MIT
Project-URL: Homepage, https://clawmetry.com
Project-URL: Bug Reports, https://github.com/vivekchand/clawmetry/issues
Project-URL: Source, https://github.com/vivekchand/clawmetry
Keywords: clawmetry openclaw moltbot dashboard observability ai agent monitoring opentelemetry
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: flask<4,>=2.0
Requires-Dist: waitress>=2.0
Requires-Dist: cryptography>=3.0
Requires-Dist: duckdb>=0.10
Requires-Dist: websocket-client>=1.6
Requires-Dist: truststore>=0.8; python_version >= "3.10"
Provides-Extra: otel
Requires-Dist: opentelemetry-proto>=1.20.0; extra == "otel"
Requires-Dist: protobuf>=4.21.0; extra == "otel"
Provides-Extra: relay
Provides-Extra: deepeval
Requires-Dist: deepeval<5,>=4.1; python_version >= "3.10" and extra == "deepeval"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# 🦞 ClawMetry

[![PyPI Downloads](https://static.pepy.tech/badge/clawmetry)](https://clickpy.clickhouse.com/dashboard/clawmetry)
[![PyPI Downloads/week](https://static.pepy.tech/badge/clawmetry/week)](https://clickpy.clickhouse.com/dashboard/clawmetry)
[![PyPI version](https://img.shields.io/pypi/v/clawmetry?color=E5443A&label=version)](https://pypi.org/project/clawmetry/)
[![GitHub stars](https://img.shields.io/github/stars/vivekchand/clawmetry?style=flat&color=E5443A)](https://github.com/vivekchand/clawmetry/stargazers)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

<a href="https://www.producthunt.com/products/clawmetry?embed=true&utm_source=badge-top-post-badge&utm_medium=badge&utm_campaign=badge-clawmetry-for-openclaw" target="_blank"><img src="https://api.producthunt.com/widgets/embed-image/v1/top-post-badge.svg?post_id=1081207&theme=light&period=daily&t=1771491508782" alt="ClawMetry - #5 Product of the Day on Product Hunt" width="250" height="54" /></a>

**See your agent think.** Real-time observability for **21 AI agent runtimes**: [OpenClaw](https://github.com/openclaw/openclaw), [NVIDIA NemoClaw](https://github.com/NVIDIA/NemoClaw), Claude Code, OpenAI Codex & 17 more. One dashboard for your whole agent fleet.

> 🌐 **Read this in:** [English](README.md) · [简体中文](docs/i18n/zh-CN/README.md) · [日本語](docs/i18n/ja/README.md) · [한국어](docs/i18n/ko/README.md) · [Español](docs/i18n/es/README.md) · [Português (BR)](docs/i18n/pt-BR/README.md) · [Français](docs/i18n/fr/README.md) · [Deutsch](docs/i18n/de/README.md) · [हिन्दी](docs/i18n/hi/README.md) · [العربية](docs/i18n/ar/README.md) · [Русский](docs/i18n/ru/README.md) · [more →](docs/i18n/)

One command. Zero config. Auto-detects everything.

```bash
pip install clawmetry && clawmetry
```

Opens at **http://localhost:8900** and you're done.

![Flow Visualization](https://clawmetry.com/screenshots/flow.png)

## Works with 21 agent runtimes

ClawMetry started as observability for OpenClaw, and now meters your **whole agent fleet** in one dashboard, auto-detecting each runtime on your machine:

🦞 **[OpenClaw](https://clawmetry.com/runtimes/openclaw)** · 🟩 **[NVIDIA NemoClaw](https://clawmetry.com/nemoclaw)** · ◆ **[Claude Code](https://clawmetry.com/runtimes/claude-code)** · ⬡ **[OpenAI Codex](https://clawmetry.com/runtimes/codex)** · **[Cursor](https://clawmetry.com/runtimes/cursor)** · 🪿 **[Goose](https://clawmetry.com/runtimes/goose)** · ⚡ **[Hermes](https://clawmetry.com/runtimes/hermes)** · **[opencode](https://clawmetry.com/runtimes/opencode)** · ◈ **[Qwen Code](https://clawmetry.com/runtimes/qwen-code)** · **[Aider](https://clawmetry.com/runtimes/aider)** · **[NanoClaw](https://clawmetry.com/runtimes/nanoclaw)** · **[PicoClaw](https://clawmetry.com/runtimes/picoclaw)** · **[Pi](https://clawmetry.com/runtimes/pi)** · **[Deep Agents](https://clawmetry.com/runtimes/deep-agents)** · 🔗 **[n8n](https://clawmetry.com/runtimes/n8n)** · 🪐 **[Antigravity](https://clawmetry.com/runtimes/antigravity)** · 🐙 **[GitHub Copilot](https://clawmetry.com/runtimes/copilot)** · **[Grok](https://clawmetry.com/runtimes/grok)** · **[QM](https://clawmetry.com/runtimes/qm)** · 🐋 **[DeepSeek Harness](https://clawmetry.com/runtimes/deepseek-harness)** · 🦾 **Exo**

Each link is that runtime's setup + observability guide. Every runtime gets the same dashboard: live sessions, token costs, tool calls, transcripts, alerts.

OpenClaw and NemoClaw are free in the open-source app; the other runtimes light up with ClawMetry Cloud or a self-hosted Pro license. Switch runtimes from the header and every tab — cost, tokens, tools, traces — re-scopes to that runtime. See **[docs/ENTITLEMENTS.md](docs/ENTITLEMENTS.md)** for the exact free/paid split, tier matrix, `/api/entitlement` shape, and the `clawmetry license` CLI.

## What You Get

- **Flow** — Live animated diagram showing messages flowing through channels, brain, tools, and back
- **Overview** — Health checks, activity heatmap, session counts, model info
- **Usage** — Token and cost tracking with daily/weekly/monthly breakdowns
- **Sessions** — Active agent sessions with model, tokens, last activity
- **Crons** — Scheduled jobs with status, next run, duration
- **Logs** — Color-coded real-time log streaming
- **Memory** — Browse SOUL.md, MEMORY.md, AGENTS.md, daily notes
- **Transcripts** — Chat-bubble UI for reading session histories
- **Alerts** — Budget caps, error-rate triggers, agent-offline detection; routes to Slack, Discord, PagerDuty, Telegram, Email
- **Approvals** — Gate destructive deletes, force pushes, DB mutations, sudo, package installs, network calls behind one-click sign-off

## Screenshots

### 🧠 Brain — Live agent event stream
![Brain tab](https://raw.githubusercontent.com/vivekchand/clawmetry/main/screenshots/brain.png)

### 📊 Overview — Token usage & session summary
![Overview tab](https://raw.githubusercontent.com/vivekchand/clawmetry/main/screenshots/overview.png)

### ⚡ Flow — Real-time tool call feed
![Flow tab](https://raw.githubusercontent.com/vivekchand/clawmetry/main/screenshots/flow.png)

### 💰 Tokens — Cost breakdown by model & session
![Tokens tab](https://raw.githubusercontent.com/vivekchand/clawmetry/main/screenshots/tokens.png)

### 🧬 Memory — Workspace file browser
![Memory tab](https://raw.githubusercontent.com/vivekchand/clawmetry/main/screenshots/memory.png)

### 🔐 Security — Posture & audit log
![Security tab](https://raw.githubusercontent.com/vivekchand/clawmetry/main/screenshots/security.png)

### 🚨 Alerts — Budget caps, error-rate triggers, webhooks to Slack / Discord / PagerDuty / Email
![Alerts tab](https://raw.githubusercontent.com/vivekchand/clawmetry/main/screenshots/alerts.png)

### ✋ Approvals — Gate risky tool calls behind manual sign-off; policy-backed protection rules
![Approvals tab](https://raw.githubusercontent.com/vivekchand/clawmetry/main/screenshots/approvals.png)

**Pre-execution blocking for Claude Code** — one command installs a
PreToolUse hook that pauses matching tool calls *before* they run and waits
for your decision (one tap from your phone with
[cloud push notifications](https://app.clawmetry.com/push) enabled):

```bash
clawmetry hooks install     # writes ~/.claude/settings.json (idempotent)
clawmetry hooks status      # what's wired + how many policies are active
clawmetry hooks uninstall   # removes only ClawMetry's entries
```

A deny blocks just that one tool call — the agent keeps its session and can
try another approach. Approving on your phone skips Claude Code's own
permission prompt (you already answered). Unmatched tools cost ~40ms and
fall through to Claude Code's normal permission flow. You also get a phone
push when Claude Code itself is waiting on you (`permission_prompt` /
`idle_prompt` notifications).

## Install

**One-liner (recommended):**
```bash
curl -sSL https://raw.githubusercontent.com/vivekchand/clawmetry/main/install.sh | bash
```

**pip:**
```bash
pip install clawmetry
clawmetry
```

**From source:**
```bash
git clone https://github.com/vivekchand/clawmetry.git
cd clawmetry && pip install flask && python3 dashboard.py
```

## v2 Frontend Development

The v2 React app lives in `frontend/` and is served at `/v2` when the Flask
server is started with v2 enabled.

Use two terminals while developing:

```bash
# Terminal 1: Flask API/server on :8900
CLAWMETRY_V2=1 python3 dashboard.py
```

```bash
# Terminal 2: Vite dev server on :5173
cd frontend
nvm use
npm ci
npm run dev
```

Open `http://localhost:5173/v2/`. Vite proxies `/api` requests to
`http://localhost:8900`, so the React app can talk to the local Flask server
without extra CORS setup.

To build the bundle that ships with the Python package:

```bash
cd frontend
npm run build
```

The production bundle is written to `clawmetry/static/v2/dist/`.

## Runtime / Agent Compatibility

ClawMetry observes many AI-agent runtimes, not just OpenClaw. Each non-OpenClaw runtime ships a dedicated reader adapter that translates its native session format into ClawMetry's unified shapes; the daemon ingests them into the same DuckDB store + cloud snapshot, tagged with the runtime, and the Session replay tab shows a **runtime switcher** when more than one is present. See [`docs/compatibility.md`](docs/compatibility.md) for the full matrix + a guide to adding runtimes, and [`docs/RUNTIME_FAMILY.md`](docs/RUNTIME_FAMILY.md) for the OpenClaw-family primer.

Running [Perplexity's numbat](https://github.com/perplexityai/numbat) agent-security tool? ClawMetry ingests its findings and enforcement decisions out of the box — see [`docs/NUMBAT.md`](docs/NUMBAT.md).

| Runtime / Agent | Status | Notes |
|---|---|---|
| **OpenClaw** | Native | Reference runtime, auto-detected |
| **PicoClaw** | Beta adapter | Flat `providers.Message` JSONL (`~/.picoclaw/workspace/sessions`). Transcripts, model, tool calls. |
| **NanoClaw** | Beta adapter | Per-session SQLite (`data/v2-sessions`). Transcripts + message counts. |
| **Hermes** | Beta adapter | SQLite `~/.hermes/state.db`. Transcripts, model, tokens/cost. |
| **Claude Code** | Beta adapter | JSONL `~/.claude/projects/.../<id>.jsonl`. Transcripts, model, tool calls + thinking, token usage. |
| **Codex** | Beta adapter | Rollout JSONL `~/.codex/sessions/...`. Transcripts, model, tool calls, token usage. |
| **Cursor** | Beta adapter | SQLite `state.vscdb`. Chat/composer transcripts, model. |
| **Aider** | Beta adapter | `.aider.chat.history.md` per project. Transcripts, model, token counts. |
| **Goose** | Beta adapter | SQLite `~/.local/share/goose`. Transcripts, model, tool calls, token totals. |
| **opencode** | Beta adapter | SQLite `~/.local/share/opencode`. Transcripts, model, tool calls, tokens + cost. |
| **Qwen Code** | Beta adapter | JSONL `~/.qwen/projects/.../chats`. Transcripts, model, tool calls, token usage. |
| **Pi** | Beta adapter | JSONL `~/.pi/agent/sessions`. Transcripts, model, tool calls, tokens + cost. |
| **Deep Agents** | Beta adapter | SQLite `~/.deepagents/.state/sessions.db`. Transcripts, model, tool calls, tokens + cost. |
| **n8n** | Beta adapter | SQLite `~/.n8n/database.sqlite`. Workflow executions, node runs, AI Agent prompts, model + tokens where n8n records them. |
| **Antigravity** | Beta adapter | Brain JSONL under `~/.gemini/<flavor>/brain/`. Conversations, tool steps, thinking, per-generation Gemini token split + cost, background-generation burn. |
| **GitHub Copilot** | Beta adapter | Copilot CLI `events.jsonl` under `~/.copilot/session-state/` + the `session-store.db` per-call usage ledger. Conversations, tool calls, model routing, cache-aware token split, vendor-billed AI-credit cost. |
| **Grok** | Beta adapter | xAI Grok Build CLI (Rust binary under `~/.grok/bin/grok`): global event log `~/.grok/logs/unified.jsonl` + per-session `~/.grok/sessions/<enc-cwd>/<uuid>/{events.jsonl,summary.json}`. Conversations, per-turn token split, model routing, and the CLI's outbound repo payload staged under `~/.grok/upload_queue/` so you can see what left your machine. |

"Beta adapter" means ClawMetry ships a reader for that runtime's real on-disk format, each built + verified against a real install on a real machine (see `tests/fixtures/runtimes/<rt>/`). Adapters are read-only; each is honest about what its runtime actually stores (e.g. PicoClaw/NanoClaw/Cursor don't write token cost to disk). When several runtimes run on one node, the runtime switcher scopes the sessions view to one for a clean deep-dive.

## Track any SDK agent — out-loop cost attribution

The runtimes above all write sessions to disk. Your own **production agent** — the one you built on the OpenAI Agents SDK, LangChain, the Vercel AI SDK, LlamaIndex, E2B, or a plain `httpx` loop — doesn't. ClawMetry's zero-config interceptor still captures its LLM calls (cost, tokens, latency, errors) by monkey-patching `httpx`/`requests`:

```python
import clawmetry.track            # activate the interceptor
clawmetry.track.set_source("support-agent")   # name this product

# ...your agent runs as normal; every LLM call is now tracked + attributed.
```

`set_source()` (or the `CLAWMETRY_SOURCE=support-agent` env var) tags each call with a **named source**, so every product you run shows up as its own first-class, cost-attributable line in the dashboard's **🔌 Out-loop sources** card on Overview — calls, providers, latency, error rate per agent. No source set? The calls are still tracked; the card just stays hidden.

```bash
CLAWMETRY_SOURCE=billing-agent python my_agent.py
```

This is the same data layer the runtime adapters feed (DuckDB → cloud snapshot), so out-loop sources sync to the cloud dashboard the same as everything else, E2E-encrypted.

## OpenTelemetry — vendor-neutral, send your traces anywhere

ClawMetry speaks **OpenTelemetry** in both directions, using the **GenAI semantic conventions**, so your agent traces are never locked into one tool.

**Export** every session — LLM calls, tools, sub-agents, tokens, cost — as OTLP/HTTP GenAI spans to any collector (Datadog, Grafana, Honeycomb, or your own OTel Collector):

```bash
clawmetry --otel-export http://localhost:4318/v1/traces
# equivalently:
CLAWMETRY_OTEL_EXPORT_ENDPOINT=http://localhost:4318/v1/traces clawmetry
```

Auth headers and poll interval are optional env vars:

```bash
CLAWMETRY_OTEL_EXPORT_HEADERS='{"X-API-Key":"…"}'   # extra HTTP headers
CLAWMETRY_OTEL_EXPORT_INTERVAL=60                    # seconds (default 60)
```

**Ingest** — the built-in OTLP receiver accepts traces, logs, and metrics from anything else at `/v1/traces`, `/v1/logs`, and `/v1/metrics`. Point any OpenTelemetry-instrumented app at it:

```bash
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:8900 OTEL_EXPORTER_OTLP_PROTOCOL=http/json your-app
```

OTLP/JSON traces and logs work on a plain `pip install clawmetry`, no extras. Protobuf ingest (and OTLP/JSON metrics) needs `pip install clawmetry[otel]`. An app that sets its own `service.name` shows up as its own agent in the runtime switcher, with its cost and tokens.

You get the zero-config, local-first ClawMetry dashboard **and** your data in whatever backend your team already runs — no lock-in, no second agent to install.

## Configuration

Most people don't need any config. ClawMetry auto-detects your workspace, logs, sessions, and crons.

If you do need to customize:

```bash
clawmetry --port 9000              # Custom port (default: 8900)
clawmetry --host 127.0.0.1         # Bind to localhost only
clawmetry --workspace ~/mybot      # Custom workspace path
clawmetry --name "Alice"           # Your name in Flow visualization
```

All options: `clawmetry --help`

## Supported Channels

ClawMetry shows live activity for every OpenClaw channel you have configured. Only channels that are actually set up in your `openclaw.json` appear in the Flow diagram — unconfigured ones are automatically hidden.

Click any channel node in the Flow to see a live chat bubble view with incoming/outgoing message counts.

| Channel | Status | Live Popup | Notes |
|---------|--------|------------|-------|
| 📱 **Telegram** | ✅ Full | ✅ | Messages, stats, 10s refresh |
| 💬 **iMessage** | ✅ Full | ✅ | Reads `~/Library/Messages/chat.db` directly |
| 💚 **WhatsApp** | ✅ Full | ✅ | Via WhatsApp Web (Baileys) |
| 🔵 **Signal** | ✅ Full | ✅ | Via signal-cli |
| 🟣 **Discord** | ✅ Full | ✅ | Guild + channel detection |
| 🟪 **Slack** | ✅ Full | ✅ | Workspace + channel detection |
| 🌐 **Webchat** | ✅ Full | ✅ | Built-in web UI sessions |
| 📡 **IRC** | ✅ Full | ✅ | Terminal-style bubble UI |
| 🍏 **BlueBubbles** | ✅ Full | ✅ | iMessage via BlueBubbles REST API |
| 🔵 **Google Chat** | ✅ Full | ✅ | Via Chat API webhooks |
| 🟣 **MS Teams** | ✅ Full | ✅ | Via Teams bot plugin |
| 🔷 **Mattermost** | ✅ Full | ✅ | Self-hosted team chat |
| 🟩 **Matrix** | ✅ Full | ✅ | Decentralized, E2EE support |
| 🟢 **LINE** | ✅ Full | ✅ | LINE Messaging API |
| ⚡ **Nostr** | ✅ Full | ✅ | Decentralized NIP-04 DMs |
| 🟣 **Twitch** | ✅ Full | ✅ | Chat via IRC connection |
| 🔷 **Feishu/Lark** | ✅ Full | ✅ | WebSocket event subscription |
| 🔵 **Zalo** | ✅ Full | ✅ | Zalo Bot API |

> **Auto-detection:** ClawMetry reads your `~/.openclaw/openclaw.json` and only renders the channels you've actually configured. No manual setup required.

## Docker Deployment

Want to run ClawMetry in a container? No problem! 🐳

**Quick start with Docker:**

```bash
# Build the image
docker build -t clawmetry .

# Run with default settings
docker run -p 8900:8900 clawmetry

# Or mount your agent's data dir (shown: OpenClaw's ~/.openclaw)
docker run -p 8900:8900 \
  -v ~/.openclaw:/root/.openclaw \
  -v /tmp/moltbot:/tmp/moltbot \
  clawmetry
```

**Docker Compose example:**

```yaml
version: '3.8'
services:
  clawmetry:
    build: .
    ports:
      - "8900:8900"
    volumes:
      - ~/.openclaw:/root/.openclaw:ro
      - /tmp/moltbot:/tmp/moltbot:ro
    restart: unless-stopped
```

> **Note:** When running in Docker, mount your agent's data + log directories (e.g. `~/.openclaw`, `~/.claude`, `~/.codex`) so ClawMetry can auto-detect your setup.

## Requirements

- Python 3.8+
- Flask (installed automatically via pip)
- An AI agent runtime on the same machine: OpenClaw, NVIDIA NemoClaw, Claude Code, Codex, Cursor, Goose, Hermes, opencode, Qwen Code, Aider, NanoClaw, PicoClaw, Pi, Deep Agents, n8n, Antigravity, GitHub Copilot, Grok, QM, DeepSeek Harness, or Exo (or mounted volumes for Docker)
- Linux or macOS

## NemoClaw / OpenShell Support

ClawMetry automatically detects [NemoClaw](https://github.com/NVIDIA/NemoClaw) — NVIDIA's enterprise security wrapper for OpenClaw that runs agents inside sandboxed OpenShell containers.

No extra configuration is needed in most cases. The sync daemon auto-discovers session files whether they live in `~/.openclaw/` on the host or inside an OpenShell container.

### How it works

ClawMetry detects NemoClaw in two ways:

1. **Binary detection** — checks for the `nemoclaw` CLI and runs `nemoclaw status` to get sandbox info
2. **Container detection** — scans running Docker containers for `openshell`, `nemoclaw`, or `ghcr.io/nvidia/` images, then reads sessions via volume mounts or `docker cp`

Session files synced from NemoClaw containers are tagged with `runtime=nemoclaw` and `container_id` metadata in the cloud dashboard, so you can tell them apart from standard OpenClaw sessions at a glance.

### Recommended setup: sync daemon on the HOST

For the best experience, run ClawMetry's sync daemon on the **host machine** (not inside the sandbox). This avoids NemoClaw network policy restrictions.

```bash
# On the host (outside the sandbox)
pip install clawmetry
clawmetry connect
clawmetry sync
```

The sync daemon will automatically find sessions inside any running OpenShell containers.

### Optional: explicit sandbox name

If auto-detection doesn't work, point ClawMetry at the right sandbox:

```bash
export NEMOCLAW_SANDBOX=my-sandbox-name
clawmetry sync
```

### Running inside the sandbox (advanced)

If you must run the sync daemon **inside** the OpenShell sandbox, add this egress rule to your NemoClaw network policy so it can reach the ClawMetry ingest API:

```yaml
# nemoclaw-policy.yaml
network:
  egress:
    - host: ingest.clawmetry.com
      port: 443
      protocol: https
```

Apply with:

```bash
nemoclaw policy apply --file nemoclaw-policy.yaml
```

### Ports and endpoints

| Endpoint | Port | Protocol | Required |
|---|---|---|---|
| `ingest.clawmetry.com` | 443 | HTTPS | Yes (sync daemon → cloud) |
| `localhost:8900` | 8900 | HTTP | Yes (local dashboard UI) |
| Docker socket (`/var/run/docker.sock`) | — | Unix socket | For container session discovery |

The sync daemon only makes outbound HTTPS calls to `ingest.clawmetry.com`. No inbound ports are required.

---

## Cloud Deployment

See the **[Cloud Testing Guide](https://github.com/vivekchand/clawmetry/blob/main/docs/CLOUD_TESTING.md)** for SSH tunnels, reverse proxy, and Docker.

## Testing

This project is tested with BrowserStack.

[![BrowserStack](https://img.shields.io/badge/tested%20with-BrowserStack-orange.svg)](https://browserstack.com)

## Telemetry

ClawMetry sends anonymous install-lifecycle pings to
`https://app.clawmetry.com/api/install`: one `install` ping the first
time you run the `clawmetry` CLI on a new machine, one `update` ping
the first run after upgrading to a new version, and one `onboarded`
ping when you complete the in-dashboard onboarding choice. We use this
to count real installs (raw PyPI download numbers are ~98% mirrors, CI,
and auto-update re-downloads) and to learn which agent frameworks and
versions are actually in the wild.

**At most one POST per lifecycle event per version**, containing:

| Field | Example | Why |
|---|---|---|
| `install_id` | random UUID stored at `~/.clawmetry/install_id` | dedup; anonymous until you explicitly connect Cloud sync (the authenticated daemon heartbeat then carries it, linking this install to your account) |
| `event` | `install` / `update` / `onboarded` | fresh install vs upgrade of an existing one |
| `version` | `0.12.167` | what versions are in the wild |
| `os` / `os_version` | `Darwin` / `25.3.0` | platform support priorities |
| `python` | `3.11.15` | Python version support matrix |
| `agent` | `openclaw` / `nemoclaw` / `hermes` / `none` | which agents we should integrate with next |
| `is_ci` / `ci_provider` | `true` / `github_actions` | separate human installs from CI noise |

**What we do NOT send**: IP (cloud derives the country code server-side
from the request, then discards the IP), hostname, username, workspace
path, file contents, your api_key, your email, anything PII or
workspace-specific. The wire payload is auditable in
[`clawmetry/telemetry.py`](clawmetry/telemetry.py).

**Opt out** (any one of these disables it permanently):

```bash
export CLAWMETRY_NO_TELEMETRY=1                # per-shell
export DO_NOT_TRACK=1                          # W3C cross-tool standard
touch ~/.clawmetry/notelemetry                 # persistent file marker
```

A network failure here never blocks `clawmetry` from running — the
ping is fire-and-forget on a daemon thread with a 3 s timeout.

## Star History

<a href="https://www.star-history.com/?repos=vivekchand%2Fclawmetry&type=date&legend=top-left">
 <picture>
 <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/image?repos=vivekchand/clawmetry&type=date&theme=dark&legend=top-left" />
 <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/image?repos=vivekchand/clawmetry&type=date&legend=top-left" />
 <img alt="Star History Chart" src="https://api.star-history.com/image?repos=vivekchand/clawmetry&type=date&legend=top-left" />
 </picture>
</a>

## License

MIT

---

<p align="center">
  <strong>🦞 See your agent think</strong><br>
  <sub>Built by <a href="https://github.com/vivekchand">@vivekchand</a> · <a href="https://clawmetry.com">clawmetry.com</a> · Part of the <a href="https://github.com/openclaw/openclaw">OpenClaw</a> ecosystem</sub>
</p>
