p# Plan Pilot
Turns long Claude Code plans into a focused, step-by-step view inside VS Code.
Discuss any step with Claude Code, then execute just that step in a Claude Code terminal.
What you get
- Focus view: one step at a time. You see its goal, why, files (click to open), task checklist, "done when" checks, risk and dependencies.
- Overview: phases shown as lanes, with a card for each step, coloured by status.
- Chat for each step: ask questions about the current step. Claude gets the step, the plan outline and the current contents of the step's files. Each step keeps its own discussion.
- Execute: runs only this step, plus the decisions from your discussion, in a Claude Code terminal.
- Open questions: a plan's open questions must be answered before it can be executed. Your answers update the affected steps.
- Automatic updates: when a step changes, later steps that depend on it are flagged as stale or updated for you.
- Live task progress: checkboxes follow Claude's task list while it works.
- Stats tab: time, tokens, cost and models for each step and the whole plan.
- Live sync: ticking a checkbox updates the
.md file. When the agent edits the plan, the view refreshes on its own.
- Status tracking: each step can be To do, In progress, Done, Blocked or Skipped, and a progress bar shows how far along you are.
- A fixed plan pattern: a short set of rules for
CLAUDE.md, so Claude always writes plans in the same structure.
- Plans in other formats still open: steps are guessed from the headings.
Requirements
VS Code 1.95+ and Claude Code installed and logged in (the claude CLI, or the Anthropic Claude Code VS Code extension). No API key needed.
Works on macOS, Linux and Windows.
Use
- Open your project and copy the rules from templates/plan.instructions.md into your
CLAUDE.md, so Claude writes plans in the format Plan Pilot reads.
- Ask Claude Code for a plan (for example "plan a user profile page"), or run Plan Pilot: New Plan…. The plan is saved as
plans/<name>.plan.md.
- Open the plan and click the ☑ icon in the editor title bar (or right-click the file → Open Plan Visualizer).
- Go through the steps: read one, ask questions, press ▶ Execute with Claude Code, review the changes, then move to the next step.
Keys: ←/→ (or j/k) move between steps, and / jumps to the chat box.
To try it without a project, run Plan Pilot: Open Sample Plan.
New plan
Run Plan Pilot: New Plan… from the Command Palette, or click + New plan in the panel.
Describe what you want to do. Claude Code reads the project and writes a plan with
numbered phases and steps, each with its own tasks and "done when" checks. The plan is saved to plans/<name>.plan.md and opens right away.
Claude Code
In the model dropdown, pick the default model, Sonnet or Opus.
- Chat runs
claude -p in your project folder. It uses your Claude Code login, can read your code, and is blocked from editing anything.
- ▶ Execute with Claude Code runs Claude in a single terminal named Plan Pilot · Step N (cyan, checklist icon), where you watch it work and approve edits as usual.
- Pressing Execute again on the same step sends the new instructions to the Claude that's already running.
- Starting a different step, or clicking Go to next step, ends the previous session first, so each step starts with a clean context.
After implementing a step, Claude reviews its changes. It doesn't fix the findings on its own. They appear in the step's chat as a review card, one row per finding, each with a severity, the file, why it matters, a suggestion, and Fix now / Later / Ignore.
Click Send decisions and "Fix now" findings become tasks on the step while "Later" findings go into a new Review follow-ups for step N step right after it.
Claude, in the same session, then fixes only the "Fix now" items. If there are no findings, it goes straight on.
Next, Claude proposes a commit message. It does not commit.
The proposal appears in that step's chat in Plan Pilot as a card showing the review summary, an editable message and the files.
Click Commit and Plan Pilot ticks "Committed" in the plan, then commits exactly those files plus the plan file.
Other changes, even ones already staged, are left alone. The hand-off goes through a .plan-pilot/ folder that git ignores.
Developers: how Plan Pilot drives Claude Code (CLI flags, hook, hand-off files) is in docs/claude-code-integration.md.
If you see "couldn't find claude", run which claude in Terminal and put that path in Settings → planPilot.claudePath.
# Plan: <name>
## Context
## Phase 1: <name>
### Step 1.1: <imperative title>
- **Goal:** …
- **Why:** …
- **Files:** `path/a.ts` (new), `path/b.ts`
- **Depends on:** none
- **Risk:** low | medium | high
- **Effort:** S | M | L
**Tasks**
- [ ] …
**Done when**
- [ ] …
## Open questions
See templates/plan.instructions.md for the full rules.
Building from source and contributing: see CONTRIBUTING.md.
