comprendo
Comprendo gates AI implementation behind a visual developer approval step. When you type /comprendo <task>, Claude reads your codebase, buil
Open source Open in the app JSON README (API)
About
Comprendo gates AI implementation behind a visual developer approval step. When you type /comprendo <task>, Claude reads your codebase, builds a structured plan with before/after architecture diagrams and code previews, then opens a browser UI where you review everything before a single file is touched. No more coming back to a multi-file diff you have to reverse-engineer — you see exactly what's about to change, why, and how, then you decide.
Details
- Kind
- Plugins
- Topic
- Media, design & games
- Publisher
- nikhilenmudi
- Origin
- marketplace
- Category
- ferramentas
- Stars
- 2
- Last push
- 2026-04-11T03:35:45Z
- Repository state
- ativo
- Language
- HTML
- License
- MIT
- Added
- 2026-08-30 01:48:58
- Updated
- 2026-08-30 01:48:58
- Origin id
nikhilenmudi/comprendo/comprendo
README
# Comprendo
**Stop AI from writing code you don't understand.**
Comprendo is a Claude Code plugin that forces a review step between "plan" and "implement." When you type `/comprendo <task>`, Claude reads your codebase, builds a structured plan with architecture diagrams and code previews, then opens a browser UI where you review everything before a single file is touched.
No more coming back to a 12-file diff you have to reverse-engineer. You see exactly what's about to change, why, and how — then you decide.
## The problem
AI coding assistants are fast. Sometimes too fast. You describe a change, and 30 seconds later you're staring at a diff across 8 files wondering:
- What was the reasoning behind this approach?
- Which components were affected and how do they connect?
- Did it change something I didn't expect?
- Do I actually understand what just happened to my codebase?
Most developers approve changes they don't fully understand because the alternative — reading every diff line and mentally reconstructing the architecture — takes longer than the AI saved them.
## What Comprendo does
Comprendo adds a gate between planning and execution. When you use `/comprendo` instead of asking Claude directly:
1. **Claude reads your code** — explores the relevant files and understands the current state
2. **Claude builds a plan** — structured JSON with a summary, explanation, before/after architecture diagrams, code snippets, and affected files
3. **A browser UI opens** — you see everything laid out visually at `localhost:2345`
4. **You decide** — click Approve to let Claude implement, or Reject to go back and adjust
No files are written until you explicitly approve.
## The review UI
The browser shows a single-page dark-themed review with:
- **Side-by-side architecture diagrams** — current state vs proposed state. New components are highlighted in purple. Rendered as SVG directly from the plan data — no fragile text-based syntax.
- **Plain English explanation** — 2-3 paragraphs describing what exists now, what's changing, and why this approach was chosen. Written for a developer who hasn't looked at this code in 3 weeks.
- **Code snippets** — before/after toggle with syntax highlighting showing the key changes
- **Files affected** — listed as pills so you know the blast radius
- **Approve / Reject** — sends the decision back to Claude Code
## Install
### As a Claude Code plugin (recommended)
```
/plugin marketplace add nikhilenmudi/comprendo
/plugin install comprendo
/reload-plugins
```
That's it. No npm install, no build step, no dependencies.
### Manual install
```bash
git clone https://github.com/nikhilenmudi/comprendo.git
cd comprendo
npm link
mkdir -p ~/.claude/commands
cp skills/comprendo/SKILL.md ~/.claude/commands/comprendo.md
```
## Usage
```
/comprendo add retry logic to the API client
/comprendo refactor the auth middleware into a service class
/comprendo add a /health endpoint that checks MongoDB connection status
```
## How it works
```
Developer types /comprendo <task>
|
v
Claude reads relevant files, builds structured JSON plan
|
v
CLI starts local HTTP server, injects plan into review UI
|
v
Browser opens at localhost:2345
|
v
Developer reviews diagrams, explanation, code, files
|
┌────┴────┐
v v
Approve Reject
(exit 0) (exit 1)
| |
v v
Claude Claude stops,
implements asks what to
as planned change
```
**Under the hood:**
- `skills/comprendo/SKILL.md` — instructs Claude to plan first, output structured JSON, then pipe it to the CLI
- `cli.js` — starts a local HTTP server, injects the plan data into the UI, waits for the developer's decision via POST endpoint
- `ui.html` — single-page review UI with custom SVG diagram renderer and highlight.js for code
**Zero dependencies.** The CLI uses Node.js built-in `http` module. Diagrams are rendered as SVG directly from JSON — no Mermaid, no D3, no chart library. The only CDN dependency is highlight.js for syntax coloring.
## Design decisions
- **Browser UI, not terminal** — architecture diagrams and code diffs need space. A terminal can't render side-by-side diagrams with color-coded nodes.
- **Custom SVG renderer, not Mermaid** — Mermaid uses a text-based DSL that breaks on labels containing `()`, `/`, `{}`, and other common characters in code. Our renderer takes JSON directly. No syntax to break.
- **5-minute timeout auto-rejects** — if you walk away, nothing gets written. The safe default is to do nothing.
- **Port fallback** — tries 2345, then 2346-2349. Won't crash if another instance is running.
## Roadmap
- [ ] Quiz mode — test your understanding of the proposed change before approving
- [ ] Audit trail — log all approved/rejected plans for team review
- [ ] Significance classifier — auto-detect high-risk changes and require extra scrutiny
## License
MIT