ClawMetry Documentation

ClawMetry uses adapters to translate data from various agent runtimes into a unified Session / Event schema. This allows the ClawMetry dashboard to provide consistent observability (brain feed, transcripts, cost analytics) regardless of the underlying framework.

Supported Adapters

• Pull Mode: The adapter scans persisted files or databases (e.g., filesystem or SQLite).
• Push Mode: The adapter receives events via a callback bus (e.g., NeMo).

The Accuracy Harness is a suite of synthetic ground-truth verifiers designed to ensure ClawMetry dashboard features (like Tokens, Approvals, and Alerts) are reporting data correctly. It prevents silent regressions caused by bugs in data pipelines, timezone bucketing, or cache TTLs by driving known synthetic traffic and asserting that the dashboard metrics match the expected ground truth.

The Harness Lifecycle

Every sub-harness follows a consistent six-step pattern:

1. baseline: Scrape feature endpoints to snapshot current totals.
2. ground: Drive $N$ synthetic events with known properties (the source of truth).
3. flush: Poll the sync daemon until the $N$ events have landed.
4. probe: Re-scrape feature endpoints across all exposed time windows (e.g., 1h, 24h, 7d, 30d).
5. assert: Verify that (after - before) == ground within a defined tolerance.
6. report: Output a PASS table or file a GitHub issue if drift is detected.

ClawMetry implements a fully automated, zero-build internationalization system designed to support 30+ languages without requiring an npm build step or human translators.

Core Principles:

• English as Source of Truth: All new or changed strings are written in English. A CI bot (Claude) automatically translates these into all supported languages during the PR process.
• No Build Step: To adhere to the project's constraint of having no build step and no npm, the system uses a flat JSON catalog (locales/<lang>.json) and vanilla JavaScript. It avoids heavy frameworks like react-intl or Flask-Babel.
• Hybrid Rendering:
  • The Landing Site uses locale subpaths (e.g., clawmetry.com/ja/) to ensure per-language SEO and crawlability.
  • The Dashboard uses client-side translation and persisted user preferences, as it is behind a tool and not indexed by search engines.
• Fallback Mechanism: The system is designed to never crash on a missing translation; it always falls back to English.
• Localization Scope: The system localizes the interface (chrome, buttons, labels). It does not translate user data (agent transcripts, logs, model outputs) or currency values (costs remain in USD, though number formatting is localized).

The MOAT (Minimum Operational Architecture Threshold) is a set of three non-negotiable architectural mandates for ClawMetry. If any of these principles are violated, the MOAT is considered broken:

1. DuckDB-First UI: Every UI element must query the local DuckDB. Dashboard panels, charts, and feeds must use _try_local_store_* methods to land on the user's local DuckDB via the daemon-proxy at localhost:4099/local_query/*. Using JSONL walkers, in-memory rings, or direct psutil historical samples is considered a bug.
2. DuckDB-First Events: Every event must write to DuckDB. OpenClaw v3 events are normalized in clawmetry/sync.py::_parse_v3_event. Synthetic test rows must use real v3 namespaced types (e.g., model.completed, prompt.submitted, session.started) to ensure production compatibility.
3. Cloud as a Display Layer: The Cloud component is strictly a display layer for E2E-encrypted aggregates. Cloud SQL stores metadata (user_id, plan_tier, last_seen) and opaque aggregates using AES-256-GCM. The cloud layer cannot decrypt event payloads or the pending_queries cache.

The sync daemon manages the transmission of agent data to the ClawMetry Cloud. Most streams are protected with End-to-End (E2E) encryption using AES-256-GCM.

When developing new features or integrations for ClawMetry, adhere to the following architectural constraints to ensure system stability, security, and performance:

• Data Ingestion: Follow a DuckDB-first approach. The daemon must ingest data into DuckDB, which is then used for snapshots. Never attempt to read ~/.openclaw, JSONL files, or process stats directly. Always use the daemon's own writer handle; do not use a read_only=True re-open to avoid brick-locking.
• Security & Encryption: Maintain E2E encryption. The cloud component must not compute anything on OpenClaw data. All new tabs must render client-side from the decrypted snapshot via window.__cmSnap. New routes should default to oss-passthrough.
• Performance: Adhere to a strict cost/perf budget. New diagnostic polls must share a single cadence and a single snapshot fetch. Avoid per-tab pollers or per-interceptor snapshot fetches. Heavy polls should be gated by the active tab, and new snapshot keys must be bounded and stripped of heavy fields to prevent snapshot bloat.
• Observability Model: ClawMetry is strictly read-only. It must observe but not change scheduling, approvals, or policy. Approval and policy tabs are intended to be views, not controls (unless a relay-backed write path is explicitly implemented via operator.approvals).
• Token Scoping: Use the operator.read token scope. All diagnostic RPCs (e.g., diagnostics.stability, tasks.list, tools.catalog, skills.status, usage.status, system-presence) must be read-scoped. Do not attempt to access operator.admin or approvals scopes for observation purposes.
• Verification: Always verify against live data rather than fixtures. Ensure ingest is smoke-tested against live DuckDB and that cloud snapshots are successfully decrypted.

ClawMetry allows you to inspect how the LLM context is assembled before a call. The context is composed of several distinct sections, which are visible in the Context tab:

• System Prompt: Includes Tooling (~3k tokens), Safety (~120 tokens), Skills headers (~1.5k tokens), Memory guidance, Workspace info, Heartbeats, and Sandbox info.
• Bootstrap Files: Injected markdown files like SOUL.md (identity), AGENTS.md (workspace config), TOOLS.md (custom tool instructions), USER.md, IDENTITY.md, MEMORY.md, and HEARTBEAT.md.
• Tool Schemas: JSON definitions for built-in and plugin tools (these consume tokens even if not visible as text).
• Conversation History: A mix of compacted summaries for older turns and intact recent messages, including tool call/result pairs.

Use the Context tab to see a breakdown of token usage per component (e.g., ## Tooling [========--------] 3.0K tokens) to debug why a context window might be filling up.

ClawMetry uses an automated, delta-only translation workflow to minimize maintenance and cost:

1. Development: A developer adds or edits an English string in en.json, README.md, or a doc file.
2. CI Gate: A CI process scans templates for data-i18n or t() calls. It fails the PR if user-facing text is found that is not marked for translation.
3. Automated Translation: Upon merging to main, a GitHub Action (using Claude) compares en.json against existing <lang>.json files. It translates only the deltas (new or changed keys).
4. Guardrails:
   • Glossary: Uses locales/_glossary.json to prevent translating product nouns (e.g., "ClawMetry", "OpenClaw").
   • Integrity Checks: Ensures placeholders like {n} or %s and Markdown links survive translation.
   • Orphan Pruning: Automatically removes keys from <lang>.json if they are removed from the English source.
5. Deployment: The updated locales are picked up in the next release and distributed via PyPI/Cloud.