Codebase Wizard is a Claude Code plugin that explains any codebase, spec, or markdown artifact through a wizard-style conversational Q&A interface. Every answer is anchored to actual code shown inline. Sessions are auto-captured and synthesizable as structured documentation.
- Describe mode — walks a repo owner through Q&A and produces
CODEBASE.md - Explore mode — gives a new developer a learning-order tour and produces
TOUR.md - File mode — walks through any markdown file section-by-section
- Auto-capture — every session is captured to JSON via Agent Rulez hooks
- Export — synthesize raw session logs into structured docs on demand
pip install ai-codebase-mentor
ai-codebase-mentor install --for claudeThis copies the Codebase Wizard plugin to ~/.claude/plugins/codebase-wizard/.
For a per-project install:
ai-codebase-mentor install --for claude --projectAfter installing, in any Claude Code session:
/codebase-wizard-setup # one-time setup: installs hooks and writes permissions
/codebase-wizard # start a wizard session
/codebase-wizard-export # synthesize captured sessions into docs
ai-codebase-mentor uninstall --for claudeai-codebase-mentor statusai-codebase-mentor install --for [claude|all] [--project]
ai-codebase-mentor uninstall --for [claude|all] [--project]
ai-codebase-mentor status
ai-codebase-mentor version
| Command | Description |
|---|---|
/codebase-wizard |
Start a wizard session (Describe, Explore, or Ask mode) |
/codebase-wizard-setup |
One-time onboarding: install Agent Rulez hooks, write scoped permissions |
/codebase-wizard-export |
Synthesize captured session JSON into CODEBASE.md, TOUR.md, or FILE-NOTES.md |
The plugin follows a 5-phase conversational flow:
| Phase | Trigger | What loads |
|---|---|---|
| 1 — Repo Scan | User shares repo | scan-patterns.md |
| 2 — Question Handling | "how does X work?" | (none extra) |
| 3 — Navigation | "rewind", "jump to" | navigation-commands.md |
| 4 — Tutorial Mode | README found, or "teach me" | tutorial-mode.md |
| 5 — Persistence | "save", "export" | persistence.md |
Every answer follows the same loop:
- Find the relevant code
- Show it as a code block with a full anchor (
src/auth/middleware.ts → validate() → L14-31) - Explain in plain English
- Show connections (calls / called-by)
- Predict 2–3 follow-up options
| Version | Runtime | Status |
|---|---|---|
| v1.0 | Claude Code | Complete |
| v1.2 | OpenCode + PyPI publish | Planned |
| v1.3 | Codex (subagent-aware) | Planned |
| v1.4 | Gemini CLI | Planned |
| v1.5 | LangChain DeepAgent standalone | Planned |
git clone https://github.com/SpillwaveSolutions/codebase-mentor
cd codebase-mentor
pip install -e .
pytest tests/MIT — Spillwave Solutions