Documenting your codebase
codex-keeper creates AI-focused documentation for your codebase, structured for navigation by subagents.
Quick start
Section titled “Quick start”codex-keeper is a sub-agent, so you run it from Claude Code rather than from either front door. It sits in the meta domain and belongs at global scope, where one install serves every repository you point it at — see Global-first setup. Click its row in the editor’s roster to pin it on, and the install command writes it to .claude/agents/codex-keeper.md. From the terminal, npx agents-inc edit adds it and recompiles in the same run. Then ask it to start:
@codex-keeper initialize documentation for this codebaseIt writes to .ai-docs/ and adds a ## Generated Documentation section to your CLAUDE.md, so your other subagents know where to look. The rest of this page is what it produces and how to keep it fresh.
What it produces
Section titled “What it produces”codex-keeper writes to .ai-docs/ and updates your project’s CLAUDE.md with a ## Generated Documentation section so other subagents know where to find the docs.
| Output | Purpose |
|---|---|
.ai-docs/DOCUMENTATION_MAP.md |
Coverage index with staleness tracking and priority queue |
.ai-docs/reference/*.md |
Architecture, type system, store maps, etc. |
For complex codebases it generates a features/ subfolder with docs by feature. Once they exist, you and your subagents can reference them by name:
@web-developer see X feature documentation to understand how X works, then implement YSetting up a documentation repository
Section titled “Setting up a documentation repository”The recommended setup keeps .ai-docs/ as a standalone repo symlinked into your project. This lets you version documentation independently, share it across team members, and separate doc history from code history.
Keeping docs fresh
Section titled “Keeping docs fresh”Docs drift quickly. Run codex-keeper weekly to catch areas that have changed. It runs on opus, which is what a pass over an unfamiliar codebase wants; Models and effort is how you change that for a smaller job.
New documentation: Creates docs for undocumented areas. Start here for a fresh codebase.
@codex-keeper initialize documentation for this codebaseUpdate: Refreshes all or specific docs
@codex-keeper update any docs that are stale@codex-keeper the batch processing feature changed significantly, update its docs