PrefXplain
Claude Code ships a feature in 1 hour. Reviewing it takes me 5.
That gap is the real bottleneck of AI-assisted software engineering, and it's not going away. The more code your agent writes, the more your job shifts from writing to understanding — understanding the architecture, understanding what the agent just did, understanding what will break if you let it ship.
Reading 40 diffs across 20 files is slow, painful, and doesn't scale. But humans read pictures fast. Give me one good diagram and I'll grasp a codebase in five minutes that would take me five hours of file-by-file reading.
PrefXplain is that diagram. One slash-command inside Claude Code (or Codex, or Cursor, or Windsurf) turns your repo into an interactive architecture map — every file has a role, a plain-English description, and a place in the dependency flow. No API key, no setup, no upload. Just a single HTML file you can open, share, or drop into a deck.
The goal isn't to replace reading code. It's to know what to read.
I'm a founder shipping with Claude Code every day. I built PrefXplain
because I was drowning in review. Now I run /prefxplain before every
audit, every onboarding, every investor walkthrough. It takes 30 seconds
and it changes how I think about the codebase I'm steering.
Free. MIT. Fork it, improve it, make it yours.
Who this is for:
- Founders explaining their tech to non-technical stakeholders — investors, customers, new hires
- Devs steering a coding agent and tired of reviewing diffs blind
- Tech leads onboarding onto a repo they didn't write
Lives inside your IDE. /prefxplain opens the diagram in a preview tab right next to your agent — VS Code, Cursor, Windsurf, Antigravity, whatever. Architecture map on the left, Claude Code (or Codex) on the right. No window swapping, no context loss. (Prefer a browser? The HTML works standalone too.)
See it
PrefXplain on the left, Claude Code on the right. Architecture stays visible while your agent codes. No alt-tab, no context loss.
Every block is a file or an architectural group. Click to see the description, the blast radius, the imports, and the actual logic as a flowchart. Search matches descriptions, not just filenames. The whole thing is one HTML file — offline, shareable, safe to send.
Install — 30 seconds
Requirements: Python 3.10+, and one of:
pipx install prefxplain && prefxplain setup
That's it. One command, installed globally, works from every project
forever. pipx keeps it in its own isolated environment so it never
conflicts with your project venvs. prefxplain setup registers PrefXplain
for Claude Code, Codex, Cursor/Windsurf, Copilot CLI, and Gemini CLI —
whichever ones you have installed.
Don't have pipx?
brew install pipx(macOS) orpython -m pip install --user pipx(everywhere else). Or use plainpip install prefxplaininside a venv — you'll just have to repeat it per project.
Use it — 1 line
Open your AI coding CLI (Claude Code, Codex, Copilot, or Gemini) inside any repo and type:
/prefxplain
The agent reads your files, groups them into architectural blocks, writes a short description for each, and opens an interactive diagram in an IDE preview tab. First run on a medium repo: ~2 minutes. Re-runs: seconds (descriptions are cached).
No API key. The agent runs inside your existing Claude Code, Codex,
Copilot, or Gemini session, so you pay nothing extra — your subscription
already covers it.
If you'd rather call a model directly (CI, automation, headless), set
ANTHROPIC_API_KEY or OPENAI_API_KEY and use the prefxplain CLI.
What you get
- Executive summary — 3–5 sentences covering what the project does, its main layers, and its critical path. Paste it into a deck.
- Health score (1–10) with plain-English notes. "No circular deps.
graph.pyis a single point of failure (13 of 17 files depend on it). Test coverage is solid." - Layered architecture diagram — files grouped into logical blocks (CLI, Analysis, Rendering, …), laid out by dependency depth.
- Blast radius on click — select any file and see every file that breaks if you change it, highlighted in amber.
- Semantic search — type
authordatabaseand it matches descriptions, not just filenames. - Flowcharts — double-click a file to see its real logic as a flowchart.
Click any block: neighbors fade, dependency edges light up with labels, and a hover reveals the plain-English description.
Double-click to see the actual control flow of a file — start, decisions, steps, end. Not a generic diagram, the real shape of the code.
Everything is in a single self-contained HTML file. No server, no CDN, no JavaScript dependencies, no upload. Safe to share with anyone.
CLI (optional)
If you don't use a coding agent, the CLI works standalone — set an API key and run:
prefxplain create . # analyze + open
prefxplain update . # re-analyze, preserve descriptions
prefxplain create . --no-descriptions # offline, no LLM, still useful
prefxplain check . # CI: fail on circular deps
prefxplain mcp . # MCP server for AI agents
You can also force setup for a specific tool:
prefxplain setup copilot # installs a global Copilot CLI plugin
prefxplain setup gemini # installs an Agent Skill in ~/.gemini/skills/prefxplain/
prefxplain setup claude-code
prefxplain setup cursor
prefxplain setup codex
Each variant installs the same /prefxplain slash command — plus a
natural-language trigger ("map this codebase architecture") for agents
that use the Anthropic Agent Skill format (Copilot, Gemini, Claude Code).
Full flag reference
| Flag | Default | Description |
|---|---|---|
--output, -o |
./prefxplain.html |
Output path |
--format |
html |
html, matrix, mermaid, dot |
--no-descriptions |
false | Skip LLM step |
--api-key |
env | Override API key |
--model |
gpt-4o-mini |
LLM model |
--max-files |
500 | Analysis cap |
--force, -f |
false | Regenerate all descriptions |
--filter |
— | Glob filter (e.g. src/**/*.py) |
--focus / --depth |
— | Depth-limited view around a file |
Supported languages
| Language | Parser | Status |
|---|---|---|
| Python | ast (built-in) |
Stable |
| TypeScript / JavaScript | Regex + tsconfig path aliases |
Stable |
| Go, Rust, Java, Kotlin, C/C++ | Regex | Best-effort |
First-class tree-sitter support for the regex-parsed languages is on the roadmap.
Development
git clone https://github.com/PrefOptimize/PrefXplain.git
cd prefxplain
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
make test
License
MIT. Free forever. Go build something.
Metadata
Release files for prefxplain 0.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| prefxplain-0.3.0.tar.gz | 154.4 kB | Without provenance | Details for prefxplain-0.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| prefxplain-0.3.0-py3-none-any.whl | Python 3 | none | any | Details for prefxplain-0.3.0-py3-none-any.whl |
Total release size: 299.9 kB
Release files / prefxplain-0.3.0.tar.gz
| Download URL | prefxplain-0.3.0.tar.gz |
|---|---|
| Size | 154.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9254d1e40abfdb4279e95bfce92af6fbb0aa7c93c7f6f61461c57a713a7c20de
|
|
BLAKE2b-256 checksum How to use checksums |
c8043fec6591f9a31ad3710f6fc90cfe42222dea29c916729ef62ccc8066a2fa
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.3
|
Release files / prefxplain-0.3.0-py3-none-any.whl
| Download URL | prefxplain-0.3.0-py3-none-any.whl |
|---|---|
| Size | 145.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7c255fbf1626ff7497fe4b6c60188b43f15939ca588ff684ad706d8c1d1020be
|
|
BLAKE2b-256 checksum How to use checksums |
3907d106ceb77fa19054ed20982012742731d704c7d07f267d55a436b79e8c95
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.3
|
Security for prefxplain 0.3.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.