---
title: Files and directories
description: Every path ClawMetry reads or writes — its own state directory, the runtime directories it only ever reads, and what to back up.
keywords: clawmetry file locations, agent data directories, clawmetry home, agent config paths
eyebrow: 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

```text
~/.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
```

| Variable | Moves |
|---|---|
| `CLAWMETRY_HOME` | The whole directory |
| `CLAWMETRY_LOCAL_STORE_PATH` | Just the store file |

## Runtime directories — read only

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

| Runtime | Location |
|---|---|
| OpenClaw / NemoClaw | `~/.openclaw/` |
| Claude Code | `~/.claude/projects/` |
| Codex | `~/.codex/sessions/` |
| Cursor | Cursor application support + `~/.cursor/projects/` |
| Cline | `~/.cline/data/` |
| Copilot | `~/.copilot/` |
| Gemini CLI / Antigravity | `~/.gemini/` |
| Qwen Code | `~/.qwen/projects/` |
| Goose | `${XDG_DATA_HOME:-~/.local/share}/goose/` |
| opencode | `${XDG_DATA_HOME:-~/.local/share}/opencode/` |
| Devin | `${XDG_DATA_HOME:-~/.local/share}/devin/cli/` |
| OpenHands | `~/.openhands/` |
| OpenWorker | `~/.config/coworker/` |
| Deep Agents | `~/.deepagents/.state/` |
| DeepSeek Harness | `~/.dsh/sessions/` |
| Kimi | `~/.kimi/` and `~/.kimi-code/` |
| Grok | `~/.grok/` |
| Hermes | `~/.hermes/` |
| PicoClaw | `~/.picoclaw/workspace/sessions/` |
| NanoClaw | `<checkout>/data/v2-sessions/` |
| Pi | `~/.pi/agent/sessions/` |
| n8n | `~/.n8n/database.sqlite` |
| Exo | `<workspace>/.exo/exoharness/` |
| Aider | `<project>/.aider.chat.history.md` |
| QM | PostgreSQL — no local files |

Each runtime's [reference page](/docs/runtimes/overview/) has the exact
discovery order and its environment overrides.

:::note Two exceptions to "home directory"
**Exo** anchors its state to the workspace, and **Aider** writes into each
project. Neither has a central store, which is why discovery for those two is a
bounded scan rather than a path resolution.
:::

## 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.

:::warning A hook marker that stops matching
If a marker cannot be matched — because a launcher path changed shape, for
instance — an install will append rather than replace, every time. A hook
configuration file that has grown to thousands of entries is that bug, and
`clawmetry uninstall` is the fix.
:::

## Service files

| Platform | Location |
|---|---|
| macOS | `~/Library/LaunchAgents/` |
| Linux | systemd user or system units |
| Windows | The registered service |

→ [Run it as a service](/docs/config/service/)

## What to back up

| Path | Why |
|---|---|
| `~/.clawmetry/local_store.duckdb` | Your history. Stop the daemon before copying. |
| `~/.clawmetry/license.key` | A self-hosted license |
| The cloud encryption key | **Without it, cloud ciphertext is unrecoverable** |
| `~/.clawmetry/evals/` | Your eval suites |
| `~/.clawmetry/reports/` | Your saved reports |

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

| Port | Service |
|---|---|
| `8900` | The dashboard |
| `4100` | The enforcement proxy |
| `18789` | The OpenClaw gateway (not ClawMetry's) |
| ephemeral | The daemon's localhost query server — see `local_query.json` |

→ [Ports and networking](/docs/config/networking/)