codecontext

---

Codebases drift. Docs rot. Agents waste half their turns re-discovering structure with grep and find. codecontext fixes that: it reads your repo with an LLM, writes agent-shaped documentation next to the code, and injects the relevant slice into Claude's context the moment it touches a file — then keeps all of it current automatically on every push.

Install it once. Never hand-write a directory README again.

What you get

Capability	What it produces	When it runs
docgen	One AUTO_DOCS.md per directory — a jump-table (concept → file · symbol), deep-first and semver-versioned. Agent-shaped, not human-shaped.	Bootstrap once; refreshed incrementally on every push.
systems-registry	Per-system manifests (docs/systems/<name>.md): front-matter + a mermaid loop diagram + anchors + invariants + failure modes, each scored 0–10 against the real source by an LLM judge. Plus a static HTML viewer.	cli.mjs run for a full sweep; incremental on every push.
context injection	The nearest AUTO_DOCS.md map + any matching system's mermaid, injected into Claude's context the instant it reads or edits a file.	Automatically, via a PreToolUse hook.
auto-docs-refresh	A detached hook that sees git push / PR creation, refreshes the docs that changed, and commits the diff back onto the branch — so the PR carries its own doc updates.	Automatically, via a PostToolUse hook.

See it

Every system gets a manifest with a real mermaid loop, anchors, invariants, and failure modes:

And when Claude opens a file, the relevant map is already in its context — no searching:

[docgen:context] You're about to access `systems-registry/pass2.mjs`. Injected below:
the FULL map (AUTO_DOCS.md) for the file's own directory + a one-line Purpose for each
ancestor directory's map. The map is a jump-table (concept → file · symbol).

### systems-registry/AUTO_DOCS.md  (docgen-generated v0.1.0)
- Detect cross-file systems → detect.mjs · detectSystems
- Pass 1 hypothesis (LLM) → pass1.mjs · synthesizeSystems
- Per-system body generation → pass2.mjs · generateBody
- LLM-as-judge scoring → validate.mjs · scoreManifest
…

Install

As a Claude Code plugin (one command)

/plugin marketplace add decider/codecontext
/plugin install codecontext@codecontext

Hooks auto-wire via ${CLAUDE_PLUGIN_ROOT}; /plugin update pulls the latest. Per-user, nothing committed to your repo.

As a vendored submodule (committed, CI-active, shared by the whole team)

git submodule add https://github.com/decider/codecontext.git tools/codecontext
tools/codecontext/scripts/install.sh

This symlinks the plugin at tools/codecontext/, merges the hook entries into your .claude/settings.json, and ensures docs/systems/ exists. Because the hooks live in the committed settings, they run for every contributor and in CI.

Plugin vs submodule: the plugin is the fastest way for an individual to try it. The submodule is what makes a repo self-documenting for a whole team — the hooks travel with the repo and run in CI. They coexist.

Bootstrap

# Per-directory maps (one-time; ~10–25s/dir, parallelisable)
node tools/codecontext/docgen/docgen --until-done --parallel 4

# Detect + document + score systems (one-time full sweep; incremental on push after)
node tools/codecontext/systems-registry/cli.mjs run

# Browse the registry locally (rendered mermaid in your browser)
node tools/codecontext/systems-registry/cli.mjs view

After that, do nothing. The push hook sees every git push / gh pr create, refreshes the docs that changed in the background, and commits the diff back onto the branch.

How it works

flowchart LR
  subgraph author["Author once"]
    DG[docgen<br/>per-dir maps]
    SR[systems-registry<br/>system manifests]
  end
  subgraph live["Every Claude turn"]
    INJ[PreToolUse inject<br/>nearest map + matching mermaid]
  end
  subgraph push["Every push / PR"]
    REF[PostToolUse refresh<br/>regenerate changed docs to commit back]
  end
  DG --> INJ
  SR --> INJ
  DG -.refresh.-> REF
  SR -.refresh.-> REF
  REF -.keeps fresh.-> DG
  REF -.keeps fresh.-> SR
  INJ ==>|map + diagram| CLAUDE([Claude<br/>next turn])