agent-plan-viewer
v1.0.7
Published
Interactive visual viewer and two-way editor for AI agent implementation plans
Maintainers
Readme
Agent Plan Viewer ⚡
An interactive visual viewer and two-way editor for AI agent implementation plans, supporting Google Antigravity (AGY), Claude Code, OpenAI Codex, GitHub Copilot, Hermes Agent, Cursor, Windsurf, OpenClaw, and Cline.
Instead of forcing developers to skim long, static markdown plans in terminal windows, Agent Plan Viewer renders plans as an interactive web environment with visual diagram manipulation, request flow stepping, explicit save controls, and bidirectional sync back to the waiting agent.
Demo
🎬 Watch full-resolution MP4 video (1600×900) — Interactive task checklists, visual diagram editing, request flow simulation, structured diffs, and surgical Mermaid source patching.
Key Features
Interactive Plan & Checklist Inspector:
- Turn markdown tasks and checklists into interactive toggles.
- Inline edit task descriptions, reorder milestones, and add new tasks.
- Filter and inspect impacted files (
[NEW],[MODIFY],[DELETE]). - Add inline feedback notes and instructions for the agent.
Visual Diagram Canvas (React Flow):
- Converts Mermaid syntax (
flowchart TD/LR,sequenceDiagram) into an interactive visual canvas. - Drag and drop components to rearrange architecture layout.
- Add new services, databases, queues, gateways, and actors via the toolbar.
- Connect and rewire components with handle dragging.
- Two-way synchronization: visual canvas edits automatically serialize back to clean Mermaid markdown upon save/approval.
- Converts Mermaid syntax (
Phase 2: Request Flow Simulator:
- Trace system execution and workflow sequences step-by-step.
- Play/pause/step controls with adjustable playback speeds (
0.5x,1x,2x). - Animated traveling packet pulses along active edges.
- Step inspector HUD showing mock request payloads, expected responses, and failure mode verifications.
Two-Tier History Engine (Depth 10):
- Tier 1 (Action Undo/Redo): In-memory history tracking up to 10 discrete keystrokes, node drags, and task toggles (
⌘Z/⌘⇧Z). - Tier 2 (Saved Baseline Checkpoints): Whenever the user explicitly clicks "Save Draft", a persistent baseline snapshot is captured (capped at 10 versions). A dedicated "Saved Baselines" drawer lets developers inspect and revert to any of the last 10 baselines.
- No Autosave on Movement: Plans on disk are never modified during editing until the user explicitly hits "Save Draft" or "Approve & Submit".
- Tier 1 (Action Undo/Redo): In-memory history tracking up to 10 discrete keystrokes, node drags, and task toggles (
Agent Skill & Blocking Review Protocol:
- Packaged as an Agent Skill (
skills/agent-plan-viewer/SKILL.md) compatible with Google Antigravity (AGY), Claude Code, OpenAI Codex, GitHub Copilot, Hermes Agent, Cursor, Windsurf, OpenClaw, and Cline. - Blocks agent execution until the human user resolves the review session in the browser, returning structured approval status, diffs, and instructions to
stdout.
- Packaged as an Agent Skill (
Quick Start
1. Install via npm (Recommended)
# Local (user-space) install — no root/sudo permission required:
# Installs/updates the CLI in user space (~/.local/bin/agent-plan-viewer) + workspace skills/rules
npx agent-plan-viewer@latest install-skill
# Global (system-wide) install — asks for root (sudo) permission if required by your system:
# Installs/updates the CLI system-wide (/usr/local/bin/agent-plan-viewer) + global skills/rules
npx agent-plan-viewer@latest install-skill --globalNote on Permissions:
- Local (user-space) install (
npx agent-plan-viewer@latest install-skill): Installs theagent-plan-viewerbinary into your user directory (~/.local/bin/agent-plan-viewer) and adds~/.local/binto your shellPATH. No root (sudo) permission is required.- Global install (
npx agent-plan-viewer@latest install-skill --global): Installsagent-plan-viewersystem-wide and will ask for root (sudo) permission in the terminal if your system's global npm directory requires administrator privileges.
2. Reviewing a Plan
# Review an existing plan (blocks until approved or revised)
agent-plan-viewer review ./examples/sample-plans/e-commerce-microservices.md
# Output JSON result upon completion (for supported agents)
agent-plan-viewer review ./examples/sample-plans/e-commerce-microservices.md --jsonAgent Integration (Skill)
Agent Plan Viewer supports Google Antigravity (AGY), Claude Code, OpenAI Codex, GitHub Copilot, Hermes Agent, Cursor, Windsurf, OpenClaw, and Cline:
# Local (user-space) install — no root/sudo permission required:
# Installs/updates ~/.local/bin/agent-plan-viewer + workspace skills (.agents/skills, .claude/skills, .codex/skills, .github/skills, .hermes/skills, .cursor/skills, .windsurf/skills, .cline/skills)
npx agent-plan-viewer@latest install-skill
# Global (system-wide) install — asks for root (sudo) permission when required:
# Installs/updates system-wide `agent-plan-viewer` CLI + machine-wide skills & rules (~/.gemini/, ~/.claude/, ~/.codex/, ~/.copilot/, ~/.hermes/, ~/.cursor/, ~/.codeium/windsurf/, ~/.openclaw/, ~/.cline/)
npx agent-plan-viewer@latest install-skill --globalOr via the one-liner shell installer:
# Local (user-space) install — no root/sudo permission required
curl -fsSL https://raw.githubusercontent.com/ppopli/agent-plan-viewer/main/scripts/install-skill.sh | bash
# Global (system-wide) install — asks for root (sudo) permission when required
curl -fsSL https://raw.githubusercontent.com/ppopli/agent-plan-viewer/main/scripts/install-skill.sh | bash -s -- --global👉 See the complete installation guide: skills/agent-plan-viewer/README.md
Desktop Apps (Claude Desktop, ChatGPT, Gemini) & Plugin Installation:
- Export Skill File &
.zipBundle for Claude Desktop, ChatGPT, and Gemini:npx agent-plan-viewer@latest export-skill- Claude Desktop / Claude.ai: Go to Settings → Capabilities → Skills → Upload Skill and upload
agent-plan-viewer-skill.zip(or addSKILL.mdto Project Knowledge). - ChatGPT: Upload
SKILL.mdinto your Project Files or Custom GPT Knowledge. - Gemini: Upload
SKILL.mdinto Gem Knowledge (or install as a Gemini extension below).
- Claude Desktop / Claude.ai: Go to Settings → Capabilities → Skills → Upload Skill and upload
- Install as a Native Plugin / Extension:
- Google Antigravity (AGY) Plugin: Installed automatically into
.agents/plugins/agent-plan-viewer/(local) or~/.gemini/config/plugins/agent-plan-viewer/(--global), or viaagy plugin install https://github.com/ppopli/agent-plan-viewer. - Claude Plugin: Installed automatically into
.claude/plugins/agent-plan-viewer/or~/.claude/plugins/agent-plan-viewer/, or via/plugin install ppopli/agent-plan-viewer. - Gemini Extension:
gemini extensions install https://github.com/ppopli/agent-plan-viewer
- Google Antigravity (AGY) Plugin: Installed automatically into
How It Works:
- Run
npx agent-plan-viewer@latest install-skill(user-space install in~/.local/bin/agent-plan-viewer, no root permission needed) ornpx agent-plan-viewer@latest install-skill --global(system-wide install, asks for rootsudopermission if needed) to install/update the CLI and configure the skill/rule files for Google Antigravity (AGY), Claude Code, OpenAI Codex, GitHub Copilot, Hermes Agent, Cursor, Windsurf, OpenClaw, and Cline. - When the agent finishes planning, it runs:
(oragent-plan-viewer review <path-to-plan.md> --jsonnpx agent-plan-viewer review <path-to-plan.md> --json) - The agent awaits user approval, parses the returned JSON diff and user instructions, and proceeds autonomously with the approved architecture!
Diagram Editing & Markdown Preservation
When you edit a Mermaid diagram in the viewer, only the lines you changed are rewritten in your original markdown (flowchart/graph, sequenceDiagram, and erDiagram). Everything else in the diagram — subgraph groups, alt / else / opt blocks, notes, comments, style / classDef lines, entity attribute blocks, indentation and line endings — is left byte-for-byte intact:
- Subgraph-aware placement: New flowchart nodes join the
subgraphof the node they connect to, with matching indentation (unconnected nodes are appended at the end). - Order preservation: Re-ordering edges, sequence messages, participants, or ER relationships is saved by permuting only the statement text across existing line slots without moving surrounding blocks.
- Multi-statement lines: Lines like
A --> B; B --> Care split only when an edit touches that line, leaving untouched lines intact. - Self-verified patching: After patching, the result is re-parsed and compared against your edited graph. Diagrams you didn't touch are never rewritten, and a save with no edits leaves the file byte-identical.
Known Limitations
- Unsupported diagram types are read-only. Mermaid types beyond flowcharts, sequence diagrams, and ER diagrams (
classDiagram,stateDiagram,gantt, ...) render for review and remain untouched on save, but cannot be edited in the canvas. - Creating new
alt/opt/loopblocks orsubgraphgroups must be done in markdown (existing blocks and messages inside them can be edited in the canvas). - ER entities with attribute blocks display a compact attribute summary in their node label, so renaming those entity headers must be done in markdown (plain entities without attribute blocks can be renamed in the canvas).
- Unconnected new nodes in a flowchart have no neighbor to infer a
subgraphfrom and are appended at the end of the diagram. - Fallback on unpatchable flowchart/sequence edits: If an edit cannot be patched and verified safely, that diagram falls back to regenerating from the graph model (for
erDiagram, the original source is kept instead so it never turns into a flowchart).
Testing
# Run Unit & Integration Tests (87 tests)
npm test
# Run End-to-End Lifecycle Tests
npm run test:e2eDocumentation
context/INDEX.md: Index for AI agents and developers.context/DESIGN.md: Architectural decisions and Two-Tier History Engine specs.context/SPEC.md: REST/WebSocket APIs, Graph schemas, and CLI protocols.

