codebase-scribe
A Claude Code plugin that generates, enriches, and maintains agentic development documentation for any codebase.
What It Does
Codebase Scribe produces structured documentation that helps AI agents (and humans) understand your codebase:
- AGENTS.md — A hub file at your repo root with project identity, quick reference, architecture overview, and conventions
- Topic files (
docs/agents/) — Deep-dive documents organized by area: architecture, patterns, testing, build/deploy, and more
- STATUS.md — A machine-generated health dashboard showing documentation freshness, human input, and completeness scores
The plugin adapts to any codebase — it discovers your repo's structure first, then proposes a documentation layout tailored to what it finds.
How It Works
The plugin operates in three modes, automatically selected based on documentation state:
| Mode | When | What happens |
|---|
| Seed | No docs exist | Scans repo structure, proposes topics, creates documentation stubs |
| Draft | Stubs or thin docs exist | Reads source code, fills stubs with content, extracts claims |
| Maintain | Docs are current | Detects drift between code and docs, auto-fixes broken references, flags changes for review |
After each Draft or Maintain run, a Review gate automatically verifies documentation accuracy using a separate review agent (see Documentation Review below).
Installation
From GitHub (recommended)
Add the marketplace to your ~/.claude/settings.json:
{
"extraKnownMarketplaces": {
"codebase-scribe": {
"source": {
"source": "github",
"repo": "TommasoBagassi/codebase-scribe"
}
}
},
"enabledPlugins": {
"codebase-scribe@codebase-scribe": true
}
}
Restart Claude Code. The plugin will be downloaded and available automatically.
From a local clone
Clone the repo somewhere on your machine:
git clone https://github.com/TommasoBagassi/codebase-scribe.git /path/to/codebase-scribe
The repo ships with its own .claude-plugin/marketplace.json, so you just need to point Claude Code at the cloned directory. Add to your ~/.claude/settings.json:
{
"extraKnownMarketplaces": {
"codebase-scribe-local": {
"source": {
"source": "directory",
"path": "/path/to/codebase-scribe"
}
}
},
"enabledPlugins": {
"codebase-scribe@codebase-scribe-local": true
}
}
Restart Claude Code.
Verify installation
Run /plugin in Claude Code to check the plugin is loaded. You should see codebase-scribe listed with no errors.
Quick Start
- Navigate to any git repository
- Run
/codebase-scribe — scans your repo and proposes documentation topics
- Approve the proposed topics — creates stub files and an AGENTS.md hub
- Run
/codebase-scribe again — reads source code and fills stubs with content
For large repos (5+ topics), drafting happens in batches of 3 topics per run to ensure quality. Just keep running /codebase-scribe until all topics are drafted — the plugin tracks progress and picks up where it left off.
Each subsequent run detects what's changed and updates accordingly. The plugin progresses through phases automatically: seed → draft → maintain.
Tribal Knowledge Capture
The plugin captures design decisions and architectural rationale alongside auto-generated documentation:
During regular drafting, the plugin identifies deliberate-but-unexplained patterns in your code and asks one question per topic — "Why this approach?" Answers are woven into the documentation and tracked as human-sourced knowledge.
During focus mode (/codebase-scribe focus:"area"), the plugin asks 3-5 deeper observation-driven questions about the specific area. This is where the most valuable tribal knowledge gets captured — design constraints, rejected alternatives, known fragilities.
Over time, the Human Input score in STATUS.md tracks how much of each topic has human knowledge behind it, increasing naturally as you engage with the documentation.
Design decisions are tracked in .claims.yml with provenance — the maintain mode detects when code changes might invalidate a recorded decision and flags it for your review on the next run.
Documentation Review
Every documentation change goes through a quality gate powered by a separate review agent:
Automatic review — After drafting or maintenance, a fresh-session review agent verifies documentation against source code. It checks file path existence, function name accuracy, behavioral claims, and coverage gaps.
Two-pass verification:
- Mechanical pass — High-confidence filesystem checks (does this path exist? does this function exist?)
- Semantic pass — Lower-confidence content verification (does the doc accurately describe what the code does?)
