{
  "markdown": "# Comprendo\n\n**Stop AI from writing code you don't understand.**\n\nComprendo 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.\n\nNo 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.\n\n## The problem\n\nAI 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:\n\n- What was the reasoning behind this approach?\n- Which components were affected and how do they connect?\n- Did it change something I didn't expect?\n- Do I actually understand what just happened to my codebase?\n\nMost 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.\n\n## What Comprendo does\n\nComprendo adds a gate between planning and execution. When you use `/comprendo` instead of asking Claude directly:\n\n1. **Claude reads your code** — explores the relevant files and understands the current state\n2. **Claude builds a plan** — structured JSON with a summary, explanation, before/after architecture diagrams, code snippets, and affected files\n3. **A browser UI opens** — you see everything laid out visually at `localhost:2345`\n4. **You decide** — click Approve to let Claude implement, or Reject to go back and adjust\n\nNo files are written until you explicitly approve.\n\n## The review UI\n\nThe browser shows a single-page dark-themed review with:\n\n- **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.\n- **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.\n- **Code snippets** — before/after toggle with syntax highlighting showing the key changes\n- **Files affected** — listed as pills so you know the blast radius\n- **Approve / Reject** — sends the decision back to Claude Code\n\n## Install\n\n### As a Claude Code plugin (recommended)\n\n```\n/plugin marketplace add nikhilenmudi/comprendo\n/plugin install comprendo\n/reload-plugins\n```\n\nThat's it. No npm install, no build step, no dependencies.\n\n### Manual install\n\n```bash\ngit clone https://github.com/nikhilenmudi/comprendo.git\ncd comprendo\nnpm link\n\nmkdir -p ~/.claude/commands\ncp skills/comprendo/SKILL.md ~/.claude/commands/comprendo.md\n```\n\n## Usage\n\n```\n/comprendo add retry logic to the API client\n/comprendo refactor the auth middleware into a service class\n/comprendo add a /health endpoint that checks MongoDB connection status\n```\n\n## How it works\n\n```\nDeveloper types /comprendo <task>\n        |\n        v\nClaude reads relevant files, builds structured JSON plan\n        |\n        v\nCLI starts local HTTP server, injects plan into review UI\n        |\n        v\nBrowser opens at localhost:2345\n        |\n        v\nDeveloper reviews diagrams, explanation, code, files\n        |\n   ┌────┴────┐\n   v         v\nApprove    Reject\n(exit 0)   (exit 1)\n   |         |\n   v         v\nClaude     Claude stops,\nimplements  asks what to\nas planned  change\n```\n\n**Under the hood:**\n- `skills/comprendo/SKILL.md` — instructs Claude to plan first, output structured JSON, then pipe it to the CLI\n- `cli.js` — starts a local HTTP server, injects the plan data into the UI, waits for the developer's decision via POST endpoint\n- `ui.html` — single-page review UI with custom SVG diagram renderer and highlight.js for code\n\n**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.\n\n## Design decisions\n\n- **Browser UI, not terminal** — architecture diagrams and code diffs need space. A terminal can't render side-by-side diagrams with color-coded nodes.\n- **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.\n- **5-minute timeout auto-rejects** — if you walk away, nothing gets written. The safe default is to do nothing.\n- **Port fallback** — tries 2345, then 2346-2349. Won't crash if another instance is running.\n\n## Roadmap\n\n- [ ] Quiz mode — test your understanding of the proposed change before approving\n- [ ] Audit trail — log all approved/rejected plans for team review\n- [ ] Significance classifier — auto-detect high-risk changes and require extra scrutiny\n\n## License\n\nMIT\n",
  "bytes": 4948,
  "sha": "8c560edf375c34d98c4222fbc27580d897ca66f53013edd87dc40c8f0ec3cfce",
  "repo_slug": "nikhilenmudi/comprendo",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_nikhilenmudi_comprendo_comprendo_fa8446b9/readme"
}