npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

agent-plan-viewer

v1.0.7

Published

Interactive visual viewer and two-way editor for AI agent implementation plans

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

Agent Plan Viewer 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

  1. 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.
  2. 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.
  3. 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.
  4. 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".
  5. 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.

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 --global

Note on Permissions:

  • Local (user-space) install (npx agent-plan-viewer@latest install-skill): Installs the agent-plan-viewer binary into your user directory (~/.local/bin/agent-plan-viewer) and adds ~/.local/bin to your shell PATH. No root (sudo) permission is required.
  • Global install (npx agent-plan-viewer@latest install-skill --global): Installs agent-plan-viewer system-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 --json

Agent 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 --global

Or 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 & .zip Bundle 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 add SKILL.md to Project Knowledge).
    • ChatGPT: Upload SKILL.md into your Project Files or Custom GPT Knowledge.
    • Gemini: Upload SKILL.md into Gem Knowledge (or install as a Gemini extension below).
  • 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 via agy 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

How It Works:

  1. Run npx agent-plan-viewer@latest install-skill (user-space install in ~/.local/bin/agent-plan-viewer, no root permission needed) or npx agent-plan-viewer@latest install-skill --global (system-wide install, asks for root sudo permission 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.
  2. When the agent finishes planning, it runs:
    agent-plan-viewer review <path-to-plan.md> --json
    (or npx agent-plan-viewer review <path-to-plan.md> --json)
  3. 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 subgraph of 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 --> C are 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 / loop blocks or subgraph groups 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 subgraph from 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:e2e

Documentation