Configuration

Files and directories#

Two categories, and the distinction is the whole read-only contract: ~/.clawmetry/ belongs to ClawMetry, and everything else belongs to your agents and is only ever read.

ClawMetry's own state#

~/.clawmetry/
  local_store.duckdb      the store — everything ClawMetry knows
  local_query.json        the daemon's query-server discovery file
  license.key             a self-hosted license, if any
  cloud_plan.json         cached cloud plan, for entitlement resolution
  hitl/
    pause_<session_id>    pause flag files, enforced by the proxy
  reports/                Markdown you drop in for the reports browser
  evals/                  eval suite YAML

Runtime directories — read only#

ClawMetry opens these read-only and never writes into them.

Each runtime's reference page has the exact discovery order and its environment overrides.

Hooks#

Where ClawMetry registers a pre-tool hook, it writes into that runtime's own configuration file — the one place it writes outside its own directory.

Entries it owns are marked, and it only ever removes its own. If you are editing hook configuration by hand, do the same: deleting an entry you did not create breaks somebody else's tooling silently.

Service files#

→ Run it as a service

What to back up#

The runtime directories are your agents' data, and their own backup problem.

What to exclude from backups and repositories#

• license.key and the encryption key — credentials.
• The store, if your backup target is somewhere you would not want transcripts.

It contains session content, including anything secret an agent read.

Ports#

→ Ports and networking