Caching

co-maintainer keeps config, generated guides, evidence caches, and (optional) server state on disk outside your git clones. Nothing in this layout is meant to be edited by hand.

On disk layout

Config directory

Override: CM_CONFIG_PATH points at a different config.json. Override guides root: CM_REPOS_DIR (must match on laptops and serve when using server-side init).

Cache directory

Override: CM_APP_DB, CM_CLONES_DIR, CM_TOOLS_DIR (see Overrides).

Tools directory

tools/ holds helper binaries downloaded by co-maintainer, each pinned by version so an upgrade never overwrites a working install:

tools/codegraph/1.6.0/node_modules/.bin/codegraph

Codegraph is the only tool for now. It is not on your PATH, and the CLI runs the binary by absolute path. On the first local review that needs it, co-maintainer asks before installing and names the version, source, approximate size and this directory. Non-interactive runs (closed stdin, piped output, or CI) skip the question and review without it. See Local review: Codegraph and Codegraph for the version-resolution order.

cache.db (CLI)

Used by init and sync:

sync reuses unchanged rows so a moving default branch costs less than a full init. Delete cache.db only if you want a cold rebuild (you still need repo config or flags for limits).

app.db (serve)

Lives beside cache.db under the cache directory unless CM_APP_DB is set. Holds dashboard data, job queue, webhook deduplication, remote review sessions, and review history. Forward-only migrations when upgrading co-maintainer.

Back up app.db and config.json before major upgrades. See Dashboard: Updating.

Generated guides

Under repos/<owner>/<repo>/ (the literal repository name, so repos/acme/widgets/):

• SKILL.md, CODEBASE.md
• PR_REVIEW_GUIDE.md and related review guides when PR sources were included

Evidence for all repos shares one cache.db at the cache root (see above).

Paths are always under the config/cache roots so the CLI can run from any working directory. Configuration: Per-repo memory.

Clearing

co-maintainer clear deletes what init produced:

co-maintainer clear owner/repo                  # guides and saved settings
co-maintainer clear owner/repo --include-cache  # plus the fetched evidence
co-maintainer clear all --yes                   # every repository on this machine

A cleared repository goes back to "never inited". Its guides, knowledge stamp, skill state and repos["owner/repo"] settings are gone, so the next build is init, not sync. The command asks before it clears everything, and --yes skips that question when there is no terminal.

--include-cache also drops the fetched evidence for the repository (pull request listings, AI job cache, costs, local review carry-over) plus its clones and worktrees. The next init is then a cold build that pays for everything again. Without the flag, only the knowledge is gone and the next build still reuses the files and pull requests it already collected.

The dashboard has the same action per repository under Knowledge and for every repository under Settings. See Dashboard.

co-maintainer uninstall goes further and deletes every data file on the machine: config.json, app.db, cache.db, repos/, clones/, wt/ and tools/. The npm package cannot remove itself while the CLI runs from it, so the command prints npm uninstall -g co-maintainer when it is done.

Overrides

Use the same CM_REPOS_DIR on a serve host and on developer machines when remote review should read guides the server built.

When to refresh vs delete