ai-codebase-mentor

PyPI

Wizard-style codebase exploration and documentation. Install the Codebase Wizard plugin for Claude Code (and other runtimes in future releases).

Versions collected1

Direct dependencies3From release 1.3.0

Last observed21 Oct, 10:12 UTC

README

Version 1.3.0 documentation

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

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`

How It Works

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

Milestones

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

Development

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

License

MIT — Spillwave Solutions

Downloads & popularity

Awaiting observations

No metric observations yet

Download counts and popularity will appear here as the collector receives them.

Versions 1

Collected releases

Version	Published	Direct dependencies	Open version
1.3.0	31 Mar 2026	3

Package advisories

No matching advisories collected

This describes our collected data; it is not a security assessment.

Repository

PENDING

spillwavesolutions/codebase-mentor

Shared repository data · GitHub

License detected in repository: Not collected

Metadata history

Meaningful changes

Current collected state Current

Observed since 21 Oct, 10:12 UTC

No superseded metadata states collected. Unchanged observations do not create new revisions.

Record identity

package:2146d34d52ae860d26462ba4e6c45defa13189f6c1cbd763a341e7c3407cd88c