plan2code

A spec-driven workflow for AI coding agents.

Plan2Code is a spec-driven workflow for AI coding agents that you work through on a page in your browser. The dashboard lists every step as a card, and each step’s questions, progress and sign-offs arrive on that same page while the agent does the work. Decisions still land in your repo as plain files: an approved plan becomes phase documents, and the agent builds to them one phase at a time, so the next session, the next agent and the next engineer all start from the same specs. The steps run from an optional Pathfinder through Plan, Document, Implement and Finalize, with cards such as Quick task, Review, Handoff, Codebase X-ray, Diagnose a bug, Get a PR ready, Write missing tests, Clear out dead code, Changelog and Git always available. The page also carries an Ask tab for quick questions, a private Notebook the agent reads only when you start a workflow from one of its tabs, and a session meter that suggests a fresh session as one grows long. An optional desktop app puts the dashboard and the agent’s terminal side by side in one window, and can build a whole spec unattended with the Implementation Loop. The plan2code command opens the dashboard directly in Claude Code, Devin and Codex, with starter templates for GitHub Copilot CLI, OpenCode, Gemini CLI, Pi and Cursor CLI, and any other agent CLI can be added as a custom agent. The workflow installs as Agent Skills through the skills CLI for every agent it supports, including Cursor, GitHub Copilot, Windsurf and Gemini CLI. Version 3.0.6 is MIT licensed.

Install and start

Before you start

  • Node.js 18 or newer. Check with node --version. No Node? Get it from nodejs.org (the LTS download), or run winget install OpenJS.NodeJS.LTS on Windows, brew install node on macOS, or use nvm on Linux. Then open a new terminal.
  • Git. Check with git --version. The installer is fetched from GitHub with Git, and without it npm stops with spawn git ENOENT. No Git? Get it from git-scm.com, or run winget install Git.Git on Windows, brew install git on macOS, or use your package manager on Linux. Then open a new terminal.
  • Start from your project. Open your terminal in the project you want to work on (cd into it) before you run anything. Plan2Code works on the folder you start it in.
  • Ways in. plan2code (Claude Code, Devin or Codex), or type /plan2code in your agent ($plan2code in Codex).
  • No agent yet? Install Claude Code, Codex or Devin first, or let the plan2code command’s setup page walk you through it.

Installation needs network access and runs through the skills CLI. To update, run plan2code update (or re-run the install command). To remove everything, run plan2code uninstall: it asks first, then asks whether your own data in ~/.plan2code/ (notebooks, handoffs, settings) goes too. --yes skips the questions and keeps your data; add --purge to delete it.

npx --allow-git=all git+https://github.com/jparkerweb/plan2code.git

This fetches the installer to a temp directory, builds the workflow as Agent Skills, delegates installation to skills add, and cleans up after itself. The installed skills work independently from then on.

Back at your prompt with no output at all? The installer always opens the menu below, so nothing means npm could not reach the repository and hid the reason. Run git ls-remote https://github.com/jparkerweb/plan2code.git to see it: usually the network, a proxy or the VPN.

The installer opens this menu (cloning and running node install.js, below, opens the same one):

╔═════════════════════════════════════════════════════════╗
║ INSTALL PLAN2CODE                                       ║
╠═════════════════════════════════════════════════════════╣
║  I.  INSTALL    Install skills + the plan2code command  ║
║  U.  UNINSTALL  Remove everything Plan2Code installed   ║
║  A.  ADVANCED   Project install, dev tools, and more    ║
║  Q.  QUIT       Exit                                    ║
╚═════════════════════════════════════════════════════════╝

Start

  1. cd into your project, then run plan2code. It starts Claude Code, Devin or Codex on the dashboard, and the dashboard opens in your browser.
  2. In a project without an AGENTS.md, pick Set up this project first: Plan and Quick task need it.
  3. Pick a card.

Already inside your agent? Type /plan2code instead ($plan2code in Codex).

About the plan2code command

Install (I) adds plan2code as a global command (Advanced A → D adds just the command). Run it from any project and the Plan2Code dashboard opens right there, in Claude Code, Devin or Codex. With more than one installed it asks which and remembers your pick; plan2code --cli claude, --cli devin or --cli codex skips the question, and --model <name> chooses the model. It works in cmd, PowerShell, Git Bash, macOS and Linux shells, and needs the Claude Code, Devin or Codex CLI on your PATH. After you pick the agent it asks whether to turn its permission prompts off (Yes by default; --permission-mode bypassPermissions in Claude Code, --permission-mode bypass in Devin, --dangerously-bypass-approvals-and-sandbox in Codex, a custom agent’s bypass arguments, and no question for a custom agent that has none; for Codex the question names its sandbox, which that flag turns off too). It asks on every launch and remembers no answer. plan2code --keep-permissions keeps the prompts without asking, and plan2code --bypass-permissions turns them off without asking. With no terminal to ask on (a script or a pipe) the prompts stay on unless --bypass-permissions is given. The installer then offers a desktop shortcut (answer y), which opens a folder picker first. Uninstalling (U, or plan2code uninstall from any terminal) removes both.

Using another agent CLI, or none yet

Plan2Code runs inside an AI coding agent CLI. With no agent it can run (none of Claude Code, Devin or Codex, and no working custom agent), plan2code opens a setup page in your browser (the web console runs it, so no agent is needed). The page lists each agent as Found, Found outside PATH or Not found, with its install commands for your system, a Copy button per command and an Install page link. Install one and press Check again: no restart needed. An agent found outside PATH gets Use it from here, which saves where it was found so you never touch PATH yourself. Below the list sit five starter templates (GitHub Copilot CLI, OpenCode, Gemini CLI, Pi and Cursor CLI) for agents Plan2Code does not ship. Start with this agent carries the run straight on in the same tab, onto the new agent’s dashboard. Naming a built-in that is missing with --cli <name> opens the same page on that agent (a missing custom agent prints its own steps and exits 127). In the desktop app a Set up an agent button opens the same page in the window and returns to the launch card with the found agent picked. Where no page can open, such as over SSH or with no display, plan2code prints the install commands and install pages and exits with code 127.

Once an agent is running, to use a different agent CLI, open the web console’s User Preferences → Agents & models and add it: a name, the command, and (optionally) its arguments, the start prompt, arguments for skipping permission prompts, and how it takes a model. Custom agents are saved in ~/.plan2code/agents.json and used by both the plan2code command (listed after the built-ins; --cli <id> picks one) and the desktop app’s picker. The /plan2code start prompt only does something in an agent that loads the installed Plan2Code skills; for any other, leave the start prompt blank and start a skill yourself. Details in .readme/web-console.md.

About the desktop app

The installer also offers the Plan2Code desktop app: one window with the dashboard and your agent’s terminal side by side, docked right (or bottom) and collapsible. Every console page, not only the dashboard, opens inside it. A launch card asks which agent, model and effort to start on, with permission checks off as its own tick (on by default, matching the terminal flow; untick it to keep the agent’s approval prompts). A New Session button in the top bar replaces the agent with a fresh one on a brief built from the session, and the console’s own Session meter points at it when a session is getting long. Once it is installed, plan2code opens the app instead of running the agent in your terminal. plan2code --classic keeps the terminal flow, and so does a Linux machine with no display (over SSH, say) or any machine over an SSH session. plan2code update updates the skills, the command and the app together; run it in a terminal outside the app when the bar says Update available, then reopen the app. The bar also offers Update skills when the app and the installed skills disagree. plan2code uninstall removes all three.

The app can also build a whole spec unattended with the Implementation Loop; see docs/desktop-app.md.

The first release is unsigned, so macOS (Open Anyway in System Settings, Privacy & Security) or Windows (More info, then Run anyway) may ask you to allow it once. The app starts the agent with its normal approval prompts unless you tick the launch card’s permission-checks-off option (the plain plan2code command above, without the app, asks instead, with prompts off by default too). Details: docs/desktop-app.md.

Supported tools (the agents the skills CLI can install into): every agent it supports, including Claude Code · Cursor · GitHub Copilot · Windsurf · Codex · Continue · Codeium · Zed · Amp · OpenCode · Devin · Crush · Pi · Gemini CLI · Cline · Roo · Kilo · Goose · Trae · Qwen Code.

Launched by plan2code: the plan2code command and the desktop app open the dashboard directly in Claude Code, Devin and Codex (the built-ins in src/launcher/agents.json). GitHub Copilot CLI, OpenCode, Gemini CLI, Pi and Cursor CLI come as starter templates, and you can add any other agent CLI as a custom agent in User Preferences → Agents & models.

The installer keeps one canonical copy of each skill under ~/.agents/skills/ and links it into agents that maintain their own directory. To update, run plan2code update (or re-run the install command); to remove it all, run plan2code uninstall.

Use the installer rather than calling skills add against the repository root: recursive discovery would also find maintainer-only skills under .claude/skills/. The installer targets skills/ explicitly.

Prefer to clone?
git clone https://github.com/jparkerweb/plan2code.git
cd plan2code
node install.js

# Only if you plan to modify or contribute to Plan2Code itself
npm install && npx husky