Codebase Mentor

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.

What It Does

• 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

Install

pip install ai-codebase-mentor
ai-codebase-mentor install --for claude

This copies the Codebase Wizard plugin to ~/.claude/plugins/codebase-wizard/.

For a per-project install:

ai-codebase-mentor install --for claude --project

Usage

After 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

Uninstall

ai-codebase-mentor uninstall --for claude

Status

ai-codebase-mentor status

CLI Reference

ai-codebase-mentor install   --for [claude|all] [--project]
ai-codebase-mentor uninstall --for [claude|all] [--project]
ai-codebase-mentor status
ai-codebase-mentor version

Commands

How It Works

The plugin follows a 5-phase conversational flow:

Every answer follows the same loop:

1. Find the relevant code
2. Show it as a code block with a full anchor (src/auth/middleware.ts → validate() → L14-31)
3. Explain in plain English
4. Show connections (calls / called-by)
5. Predict 2–3 follow-up options

Milestones

Development

git clone https://github.com/SpillwaveSolutions/codebase-mentor
cd codebase-mentor
pip install -e .
pytest tests/

License

MIT — Spillwave Solutions