⚠️ Experimental. pi-code-planner is built for local coding models and, at runtime, is driven by one — a small local model (tested with Qwen3.6-35B-A3B-UD-Q4_K_XL.gguf) running through Pi. Cloud LLMs (such as Claude) take part in its development. It is maintained with AI assistance and may contain non-professional design choices, rough edges, broken behavior, or mistakes. Use it at your own risk.

pi-code-planner

An experimental Pi extension for local coding models. Adds a persisted state machine so long tasks survive context compaction, Git branching, and user approval steps without babysitting the session.

Not a guarantee of better output. In practice, a session implementing a nontrivial feature ran about 3 hours untouched. That is the goal.

---

Install

pi install npm:pi-code-planner

Or from source:

pi install git:github.com/m62624/pi-code-planner

Open Pi inside a Git project and run /planner-create.

If Shift+Enter doesn't insert a new line, add "tui.input.newLine": ["ctrl+j"] to ~/.pi/agent/keybindings.json and run /reload.

---

How it works

flowchart TD
    S([user runs /planner-create]) --> INIT

    INIT["**init** — bootstrap worktree and plan record"]
    INTAKE["**intake** — write and approve goal"]
    DISCOVERY["**discovery** — scan project, write verification protocol"]
    PLANNING["**planning** — write plan.md, split into tasks"]
    EXECUTION["**execution** — TDD → implement → contracts → refactor → merge"]
    FINALIZE["**finalize** — integration check, doubt review, summary"]
    DONE["**done** — present result, await user acceptance"]
    RECOVERY["**recovery** — diagnose and repair broken state"]
    OUT([output/<plan-id> branch])

    INIT --> INTAKE
    INTAKE --> DISCOVERY
    DISCOVERY --> PLANNING
    PLANNING --> EXECUTION
    EXECUTION -->|"next task"| EXECUTION
    EXECUTION -->|"all done"| FINALIZE
    FINALIZE --> DONE
    DONE -->|"/planner-finish"| OUT
    DONE -->|"change request"| PLANNING

    INIT & INTAKE & DISCOVERY & PLANNING & EXECUTION & FINALIZE -.->|"broken / stuck"| RECOVERY
    RECOVERY -.->|"resume"| INIT

Runs on its own through init, discovery, planning, execution, and finalize.

Stops and waits for you at two moments:

• intake — approves the goal before planning starts
• done — waits for /planner-finish or a correction

Stage	Who drives it
init	Automated
intake	You approve the goal
discovery	Automated
planning	Automated
execution	Automated (repeated per task)
finalize	Automated
done	You run /planner-finish
recovery	Automated, may ask before destructive repairs

---

Settings

See SETTINGS.md for the full reference.

Idle watchdog (idle.timeoutMinutes) — wakes the model when it goes silent mid-step.

The watchdog sends a wake-up message when the model has made no planner tool call for timeoutMinutes. This handles the common case where the model pauses mid-step — a long inference, a generation that produced prose instead of a tool call, or a context edge case. The wake message tells it to call planner_status and continue from the persisted state.

The right value depends on your model's inference speed. If the timeout is too short, the watchdog fires during normal generation and interrupts a step in progress. Too long, and a genuinely stuck model sits idle for a long time before recovery.

Speed	Recommended
< 5 tok/s	20
5–15 tok/s	15
15–30 tok/s	10
> 30 tok/s	6

timer.syncIntervalMinutes is separate — it only controls how often the TUI clock saves telemetry, it does not wake the model.

---

Commands

Command	Purpose
/planner-create	Create a new plan from a request
/planner-resume	Resume an existing plan
/planner-finish	Export result, clean up state
/planner-dashboard	Open the live stage dashboard
/planner-improve	Discovery-first self-improvement plan
/planner-skills	Search and manage planner-generated skills
/planner-exit	Return to the original session without finishing
/planner-delete	Delete a plan
/planner-rename	Rename a plan
/planner-helper	Show current effective settings

---

Git Branches

base → plan/<plan-id> → task/<plan-id>/<task-id> → output/<plan-id>

Raw git is blocked while a plan is active. Use planner Git wrappers. Run tests from the worktree path reported by planner_status.

---

Development

git clone https://github.com/m62624/pi-code-planner.git
cd pi-code-planner
npm install
npm run build
pi -e ./src/index.ts

---

License

MIT