Guide · Agent skill
How to use the Plan Canvas Review agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
Plan Canvas is an agent skill from the ECC project that opens a plan or HTML document in a local browser page, where you can click elements, highlight text, leave comments, chat, and press Approve or Request changes. This guide explains what the skill does, how to install it, how to trigger it with plain requests, and what it needs and touches on your machine. After reading it you should be able to run a full review loop from start to finish.
Plan Canvas Reviewaffaan-m/ECC · MIT Download the skill Quick start
- 1Install the skill. Download the ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings, Capabilities, Skills in the Claude apps.
- 2Install the CLI. Make sure the ecc-universal package is installed globally or through the ECC plugin so ecc-plan-canvas is on your PATH, and that Node.js and a browser are available.
- 3Ask for a review. Make a natural request such as asking to open the plan in the browser so you can point at what to change.
- 4Open the artifact. The agent runs ecc-plan-canvas open on the file, which opens it in your browser and returns immediately.
- 5Give feedback in the canvas. Click or highlight elements, leave comments, chat, and press Approve plan or Request changes.
- 6Keep the loop running. The agent runs await in the background, replies in the canvas, and revises the file on request-changes.
- 7End the review. After approval, the agent runs ecc-plan-canvas end on the file and begins implementation.
What the plan-canvas skill makes the agent do
Normally a plan is reviewed by you typing long instructions into the terminal. With this skill, the agent writes the plan or document, opens it in a local browser canvas, and waits for your feedback. You can point at the exact element you mean, chat with the agent, and deliver a verdict.
The agent receives your feedback as structured JSON and revises the file. The canvas reloads the file when it is saved, so you see the changes without refreshing. The skill also renders Mermaid diagrams in plans.
- Works with Markdown plans and local .md or .html files
- Annotations are anchored to the element you clicked or the passage you highlighted
- Verdicts are Approve plan or Request changes
Install the plan-canvas skill
Download the ZIP from the skill's page on this directory. Unzip it into one of these locations: ~/.claude/skills/ to make it available everywhere, or a project's .claude/skills/ folder to limit it to that project.
If you use the Claude apps instead, upload the ZIP under Settings, then Capabilities, then Skills.
The skill's files are agents/openai.yaml and SKILL.md. SKILL.md is the instruction file the agent reads.
Requirements before you start
The skill needs Node.js and a local web browser. The CLI is a Node bin from the ecc-universal npm package, so that package must be installed globally or through the ECC plugin so that ecc-plan-canvas is on your PATH. You can also run the script directly with node scripts/plan-canvas.js.
Mermaid diagrams load from a pinned CDN by default. For offline use, you can point ECC_PLAN_CANVAS_MERMAID_URL at a local mirror.
- Node.js
- ECC plugin, or the ecc-universal package installed globally so ecc-plan-canvas is on PATH
- A local web browser
- Optional: ECC_PLAN_CANVAS_MERMAID_URL for a local Mermaid mirror
Trigger the skill with natural requests
You do not need special syntax. Ask in plain language, and the agent should choose the skill when the request fits. In Claude Code you can also type /plan-canvas, and in Codex you can type $plan-canvas. The skill is meant for presenting a plan for review, or for feedback like 'move this, change that'.
It is not for reviewing code diffs, pull requests, running web apps, or remote URLs. For those, use a code-review tool.
- Please open the plan in the browser so I can mark what to change
- Show this design doc in the canvas and let me approve or request changes
- Open the report in the browser, I want to point at the table I disagree with
- Use the plan canvas before you start implementing
Run the review loop: open, await, reply, end
The agent opens the artifact in your browser, then blocks on a single command that returns your feedback. It must keep listening while you review, otherwise your messages sit in a queue with no reply. The agent should reply to every message in the canvas, then keep listening until you approve or close the review.
When you approve, the agent stops, ends the session, and begins implementing. When you request changes, the agent revises the file and continues the loop.
- Annotation: feedback anchored to a selected element or highlighted passage
- Chat: a freeform message, answered in the canvas
- Verdict approve: the plan is confirmed and implementation starts
- Verdict request-changes: the agent revises the artifact and keeps listening
ecc-plan-canvas open .claude/plans/feature.plan.md
ecc-plan-canvas await .claude/plans/feature.plan.md
ecc-plan-canvas await .claude/plans/feature.plan.md --reply 'Split Phase 2 as requested. Take a look.'
ecc-plan-canvas end .claude/plans/feature.plan.mdUse Mermaid diagrams in plans
When a plan includes a flow, architecture, sequence, state machine, ER model, or dependency graph, the agent can write it as a fenced mermaid block. The canvas renders it as a themed diagram you can point at. Simple lists and tables do not need a diagram.
If Mermaid cannot load, for example when you are offline, the block shows its source instead, so the review is not blocked.
Safety notes: scripts, network and the local server
This skill runs scripts and uses the network. It starts a detached server bound to 127.0.0.1:4517, which is loopback only and shared across sessions. The server exits after 30 idle minutes, and ECC_PLAN_CANVAS_IDLE_MS controls that timeout. The stop command shuts it down immediately.
State is kept in ~/.claude/plan-canvas/, and ECC_PLAN_CANVAS_STATE_DIR can change that location. Mermaid is fetched from a CDN unless you set a local mirror. Because the skill depends on background commands and a local server, it may fail in sandboxed or restricted environments.
- Runs local scripts and a loopback server on 127.0.0.1:4517
- Uses the network to load Mermaid by default
- State stored in ~/.claude/plan-canvas/
- Serves only local artifact files, not remote URLs
What people use it for
- Reviewing a feature plan written by /plan before any code is changed
- Pointing at a specific section of a design doc and asking for it to be split or reworded
- Checking a report or comparison table and marking the rows you disagree with
- Reviewing a flow or architecture described as a Mermaid diagram inside a plan
Frequently asked questions
What does the plan-canvas skill do?
It opens a plan or local HTML or Markdown file in a browser page where you can annotate elements, chat, and press Approve or Request changes. The agent receives your feedback as structured data and revises the document in place.
How do I install the plan-canvas skill?
Download the ZIP from the skill's page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder. In the Claude apps, you can instead upload the ZIP under Settings, Capabilities, Skills.
What do I need to run plan-canvas?
You need Node.js, a local web browser, and the ecc-universal package or the ECC plugin so the ecc-plan-canvas command is on your PATH. Mermaid diagrams load from a CDN by default, and a local mirror can be set with ECC_PLAN_CANVAS_MERMAID_URL.
Is plan-canvas free to use?
The skill is released under the MIT licence. This source does not describe pricing, so check the licence and the project page for any other terms.
Why does the skill fail or do nothing in my sandbox?
The skill depends on background commands and a local server on 127.0.0.1:4517. In sandboxed or restricted environments these may not work, so the review loop can fail. Run it in an environment that allows a shell and a local server.
What should I use instead for code review?
Plan Canvas does not review diffs or pull requests, and it does not work with live web apps or remote URLs. Use a code-review tool for diffs and pull requests.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Plan Canvas suits developers and reviewers who want a visual approve-or-revise step for plans, designs, or reports, especially when pointing is easier than typing. It is a poor fit for code review, live web apps, or restricted environments where a local server and background commands cannot run.
Download the skill