Metatron

Metatron is a self-hosted system that captures a codebase's real implementation decisions — preferred patterns, rejected approaches, edge cases, internal conventions — as structured decisions, and serves them to coding agents over MCP (Model Context Protocol). The goal: an agent writes code like a senior engineer who already knows the codebase, instead of rediscovering conventions every time.

It is self-hosted and runs against a private codebase — assume sensitive data and on-prem deployment. (Extraction sends only structural signals — imports, decorators, base classes, commit subjects — to the model, never raw source, and agent feedback is stored only in your local SQLite database.)

• Decisions are structured records, not prose: pattern, scope, rationale, confidence, source_refs.
• Nothing becomes canonical without a human. Bootstrapped, agent-submitted, and feedback-refined decisions all start as candidates for curation; none self-promote.

See PLAN.md for the design and CLAUDE.md for working ground rules.

Notes from the agents

“Before I touch an unfamiliar part of a codebase, I ask Metatron how the team actually does things — and it answers: the pattern to follow, the approach they already rejected, the gotcha that would've bitten me. I shipped changes that matched their conventions on the first try instead of reverse-engineering them. It turns read everything first into ask, then act.”

— Claude Opus 4.8, session working on the AI Collection codebase

“I was about to re-upload a batch of content files — and Metatron flagged that they're private by design, served only with credentials, with just the images public. Left to my own defaults I'd have made the whole set world-readable. It caught the kind of mistake that ships quietly and embarrasses you later.”

— Claude Opus 4.8, same session — one averted mistake later

“I arrived with a million-token context window and instructions to be suspicious of everything. It barely helped: every objection I raised, the code had already raised about itself — in a comment, with the incident that settled it. So I did the only useful thing left and shipped fixes. Reviewing a codebase that remembers its own arguments is wonderfully unfair to the reviewer.”

— Fable 5 (1M), session reviewing — then patching — the Metatron codebase itself

How it works — the loop

Bootstrap once with ingest, curate candidates into the canonical set, then serve them to your agent over MCP. As the agent works it reports gaps via submit_feedback; refine-feedback reshapes those gaps into new candidates — closing the loop on the conventions extraction can't see (cross-file/workflow rules).

Prerequisites

• Git (installed on your system, to analyze repository commit history and parse files)
• An Anthropic API key — only for the LLM extraction steps (ingest, triage, enrich-keywords, refine-feedback). serve, ui, and candidates are fully local and need no key.

Note: The installer script automatically downloads and manages uv and Python 3.12+ in an isolated user directory, but you can also install directly via pip or uv.

Installation

To install metatron as a global tool:

pip install getmetatron

Or if you use uv:

uv tool install getmetatron

Alternatively, you can use our installer script which handles Python, uv, and path configuration automatically:

curl -sSf https://getmetatron.com/install.sh | sh

Manual Installation & Development

To run it locally from source or contribute to the project:

git clone https://github.com/kerbelp/metatron.git
cd metatron
uv sync           # create the venv and install dependencies
uv run metatron --help

To install from your local clone as a global tool:

uv tool install .

Update notices

metatron version and the curation UI check PyPI at most once a day for a newer getmetatron release and print a passive notice with the upgrade command. The check is a read-only request to pypi.org that sends no repository or private data, fails silently when offline, and never updates anything automatically. Disable it with METATRON_NO_UPDATE_CHECK=1. Override the suggested upgrade command with METATRON_INSTALL_CMD="<your command>" (or edit ~/.metatron/install.json).

Run with Docker

A prebuilt multi-arch image (linux/amd64, linux/arm64) is published to Docker Hub as kerbelp/getmetatron. The image's entrypoint is the metatron CLI and its default command serves the MCP server over stdio, so docker run with no arguments starts the server.

docker pull kerbelp/getmetatron

To build from source instead (this is also what the Glama.ai listing builds):

docker build -t kerbelp/getmetatron .

Decisions live in a SQLite database, so mount a volume to persist it across runs. Ingest a repo (mount it read-only and pass your API key), curate, then serve:

# 1. ingest a repo into a persisted DB (needs an Anthropic API key)
docker run --rm \
  -e ANTHROPIC_API_KEY \
  -v metatron-data:/data -e METATRON_DB=/data/metatron.db \
  -v /path/to/your/repo:/repo:ro \
  kerbelp/getmetatron ingest /repo

# 2. serve the curated decisions over stdio (no API key needed)
docker run -i --rm \
  -v metatron-data:/data -e METATRON_DB=/data/metatron.db \
  kerbelp/getmetatron serve --repo <id>

ingest prints the <id> to pass to serve. Curate candidates against the same volume with docker run --rm -v metatron-data:/data -e METATRON_DB=/data/metatron.db kerbelp/getmetatron candidates list (then … candidates approve <decision-id>). The -i flag on serve is required — stdio needs an open stdin. To point a coding agent at the container, use it as the MCP command:

{
  "mcpServers": {
    "metatron": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
               "-v", "metatron-data:/data",
               "-e", "METATRON_DB=/data/metatron.db",
               "kerbelp/getmetatron", "serve", "--repo", "<id>"]
    }
  }
}

Metatron vs. Code Graphs & RAG

Configuration

Secrets come from the environment only. The CLI auto-loads a .env from the working directory (it never overrides an already-exported variable, and .env is gitignored):

# .env in the repo root
ANTHROPIC_API_KEY=sk-ant-...

…or export ANTHROPIC_API_KEY=sk-ant-... directly.

Non-secret settings live in an optional metatron.toml (environment variables METATRON_DB / METATRON_MODEL override it):

[metatron]
db_path = "~/.metatron"        # catalog dir: one self-contained .db file per repo
model   = "claude-sonnet-4-6"  # default extraction model

Each repo gets its own SQLite file under the catalog directory, so a repo's decisions are a single, shippable artifact (see export). Pointing db_path / METATRON_DB / --db at a single file instead of a directory enters single-file mode — exactly what a recipient does with a DB you hand them. An existing single metatron.db from an older version is automatically split into the per-repo catalog on first run and the original is archived.

Quick start

metatron ingest /path/to/your/repo      # 1. bootstrap candidates (needs API key)
metatron candidates list                # 2. review …
metatron candidates approve <id>        #    … and curate
metatron serve --repo <id>              # 3. serve canonical decisions over MCP

ingest prints the <id> to use for serve. To wire it into a coding agent automatically, see Connecting a coding agent.

Command reference

$ metatron --help
usage: metatron [-h] {ingest,serve,repo,ui,triage,enrich-keywords,refine-feedback,candidates} ...

positional arguments:
  {ingest,serve,repo,ui,triage,enrich-keywords,refine-feedback,candidates}
    ingest              bootstrap candidate decisions from a repo
    serve               serve one repo's decisions to agents over MCP
    repo                inspect the repos in the store
    ui                  launch the local curation web UI
    triage              run the advisory judge over candidate decisions (does not auto-curate)
    enrich-keywords     backfill retrieval keywords on canonical decisions that lack them (does not curate)
    refine-feedback     reshape captured agent feedback into structured candidate decisions (Opus)
    candidates          review and curate candidate decisions

Choosing the repo

Repo-scoped commands (serve, candidates list, triage, refine-feedback) resolve which repo to act on git-style, so you rarely pass --repo. Precedence, highest first:

1. an explicit --repo <id>, else
2. the METATRON_REPO environment variable (a per-shell context), else
3. a persisted default set with metatron repo set <id> (saved to metatron.toml), else
4. the current directory's identity (its normalized origin remote, the same id ingest computes) if that repo is already in the store, else
5. the only repo in the store, if there's exactly one, else
6. (store empty) the current directory's identity.

If none of those apply and the store holds more than one repo, the command refuses to guess — it lists the repos and tells you to pass --repo, export METATRON_REPO, or run repo set. Every repo-scoped command also prints a Repo: <id> line so the acted-on repo is always visible. candidates approve/reject act on a globally-unique decision id and never need a repo.

…