Skip to main content

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 open side-by-side with Claude Code inside VS Code

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) or python -m pip install --user pipx (everywhere else). Or use plain pip install prefxplain inside 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 /prefxplain slash-command showing up inside Claude Code

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.py is 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 auth or database and it matches descriptions, not just filenames.
  • Flowcharts — double-click a file to see its real logic as a flowchart.

Clicking a block highlights its blast radius and shows the description on hover

Click any block: neighbors fade, dependency edges light up with labels, and a hover reveals the plain-English description.

Double-clicking a file opens its real logic as a flowchart

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)

Source distribution for prefxplain 0.3.0
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)

Table of built distributions (wheels) for prefxplain 0.3.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.3.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page