CClawMetryDocs

CLI reference

clawmetry sync#

Start the sync daemon. This is the process that does the actual work: it reads every runtime, writes the store, runs the detectors, evaluates Guard policies and — if connected — pushes the encrypted snapshot.

bash
clawmetry sync
FlagEffect
--foregroundRun in the foreground instead of detaching
--restartRestart the running daemon — bounces launchd/systemd cleanly, no SIGKILL

Why it matters more than the dashboard#

The dashboard reads through the daemon. If the daemon is not running, every page is empty — not stale, empty. When something looks wrong, this is the first process to check.

bash
clawmetry status

What a cycle does#

  1. Walk each detected runtime and read what is new since the last high-water

mark.

  1. Normalise into the unified event schema and write to DuckDB. Deterministic

event ids make a replay a no-op rather than a duplicate.

  1. Update the rollups the dashboard reads — per session, per runtime per day,

per model per day.

  1. Run the detectors over recent sessions.
  2. Evaluate Guard policies, and act if all three locks

are open.

  1. If cloud sync is on, build, encrypt and push the snapshot.
  2. Serve the localhost query server the whole time, so readers never block.

Restarting#

bash
clawmetry sync --restart

This is the safe form. It bounces the supervised service rather than sending a kill signal, so the daemon closes its DuckDB handle cleanly. An abrupt kill mid-write is how a store ends up needing recovery.

Foreground#

bash
clawmetry sync --foreground

Use it when debugging (DEBUG=1 clawmetry sync --foreground is the pairing you want), or when a supervisor expects to own the process.

Tuning#

VariableDefaultEffect
CLAWMETRY_FAMILY_SESSION_LIMIT50Recent sessions ingested per runtime per pass. Raise for deeper backfill.
CLAWMETRY_FAMILY_EVENT_CAP—Events pulled per session, so one huge session cannot starve a cycle
CLAWMETRY_LOCAL_FLUSH_SECS—How often buffered events are flushed to DuckDB
CLAWMETRY_LOCAL_FLUSH_BATCH—Batch size for that flush
CLAWMETRY_LOCAL_MAX_GB—Soft cap on store size
CLAWMETRY_DUCKDB_MEMORY_LIMIT—DuckDB memory limit
CLAWMETRY_DUCKDB_THREADS—DuckDB thread count
CLAWMETRY_DETECTORS1Run trajectory detectors
CLAWMETRY_GUARD_POLICIES1Evaluate Guard policies at all
CLAWMETRY_POLICY_ENFORCE0Let a policy actually signal a process

Backfilling deeper history

Raising CLAWMETRY_FAMILY_SESSION_LIMIT picks up older sessions on the next cycle, but the daemon tracks a high-water mark per source. If a backfill does not appear, restart the daemon after raising the limit — a cycle that already decided it was caught up will not revisit ground it marked done.

Running it yourself#

The daemon is also python -m clawmetry.sync, which is the form to put in a supervisord program or systemd unit. See Run it as a service.

On a memory-constrained machine#

DuckDB's performance is sensitive to memory pressure from other processes, not just its own. A machine that is swapping will make the store look slow when the store is fine. Check actual memory pressure before tuning DuckDB.

Edit this page View as Markdown Report an issue
Cookie preferences