pi-mpc

MPC — Mental Preview & Correction for pi coding agent

A pi extension that forces the LLM to fully rehearse a task before touching a single file. It explores the codebase, dry-runs every change, hunts for type errors and broken imports, backtracks to fix them, and only then surfaces a structured Verified Plan for you to approve — or discard.

---

Why MPC?

Normal agents interleave thinking and writing. They guess, edit, re-guess, and leave a trail of partial fixes behind. MPC introduces a mandatory rehearse → verify loop:

explore → dryrun → issues → (backtrack →) verified → execute

All tool calls before execute are read-only. Nothing is written until the plan passes verification and you say go.

---

Phases

#	Phase	What happens	Tools
1	explore	Read files, grep patterns, identify everything that needs to change	read-only
2	dryrun	Narrate each edit step-by-step; predict the result of every change	read-only
3	issues	Actively check for type errors, broken imports, failing tests, wrong assumptions	read-only
4	backtrack	Fix identified issues, revise the plan (up to 2 rounds)	read-only
5	verified	Output a structured final plan with Assumptions, Steps, Risks, and Confidence	read-only
6	execute	User confirms → execute the verified plan with full tool access	full

Automatic phase transitions

Each phase ends when the LLM emits a phase marker; the extension detects it and advances automatically:

Marker	Transition
EXPLORATION COMPLETE: …	→ dryrun
DRY RUN COMPLETE: …	→ issues
NO ISSUES FOUND	→ verified (skips backtrack)
ISSUE N: …	→ backtrack (or force → verified after max retries)
REVISED PLAN: …	→ verified

---

Install

pi install npm:pi-mpc

Or add to your project settings (.pi/settings.json) so teammates get it automatically:

{
  "packages": ["npm:pi-mpc"]
}

---

Commands

Command	Description
/mpc	Toggle MPC mode on / off
/mpc-next	Manually advance to the next phase (fallback when the LLM misses a marker)
/mpc-resume	Resume the most recent in-progress plan from disk
/mpc-status	Show current phase and plan file path

Shortcut: Ctrl + Alt + M — toggle MPC mode

---

Typical workflow

1.  /mpc                      ← enable MPC
2.  Refactor UserService to support async interfaces
     │
     ├─ [explore]   reads files, maps dependencies
     ├─ [dryrun]    narrates every edit, traces types
     ├─ [issues]    finds a missing export in utils.ts → ISSUE 1
     ├─ [backtrack] revises plan to add the export
     └─ [verified]  outputs structured plan + confidence rating
     │
3.  ❯  Execute the plan   ← you pick one
       Refine further
       Abort

---

Safety — read-only phases

During phases 1–4, edit and write are unavailable. bash calls are intercepted and must match a safe-command allowlist (cat, grep, git status, ls, etc.). Destructive patterns are blocked:

• File writes (>, >>, tee, truncate)
• File mutations (rm, mv, cp, mkdir)
• Package installs (npm install, pip install, brew install, …)
• Git writes (commit, push, merge, rebase, …)
• System ops (sudo, kill, reboot, …)

Any blocked command returns an error explaining why, with a hint to use /mpc-next or /mpc to abort.

---

Plan persistence

Every MPC session is saved to disk automatically:

<project>/.pi/mpc/<timestamp>-<task-slug>.md

The file is human-readable Markdown (with phase outputs) plus a machine-readable JSON block at the bottom. Use /mpc-resume in any new session to pick up where you left off — the LLM skips completed phases and continues from the breakpoint.

---

Verified Plan format

When the LLM reaches phase 5 it outputs a structured plan:

## Verified Plan

### Summary
One paragraph: what this does and why.

### Assumptions Verified
- [assumption]: [how it was verified]

### Steps
1. **[File / Action]**: [what and why]
2. …

### Potential Risks
- [remaining unknowns or caveats]

### Confidence
HIGH / MEDIUM / LOW: [reason]

---

Mode comparison

Feature	Normal agent	Plan mode	MPC
Trigger	direct chat	/plan · Ctrl+Alt+P	/mpc · Ctrl+Alt+M
Workflow	think → act (interleaved)	explore → plan → execute	explore → dryrun → issues → (backtrack) → verified → execute
Phases	none	2	up to 6, auto-advancing
Tool lock	full always	read-only during explore	read-only until execute
Issue detection	✗	✗	✓ dedicated phase
Auto-backtrack	✗	✗	✓ up to 2 rounds
Plan format	none	numbered list	structured (Assumptions / Risks / Confidence)
Plan persisted	✗	session only	✓ .pi/mpc/*.md, cross-session resume
Confirm before execute	—	Execute / Stay / Refine	Execute / Refine / Abort
Best for	quick edits	medium complexity	high-risk · multi-file · unfamiliar codebases

---

File structure

mpc/
├── index.ts      # entry point: commands, events, state machine
├── phases.ts     # phase labels + per-phase LLM prompts
├── persist.ts    # plan persistence (.pi/mpc/*.md read/write)
└── utils.ts      # types, marker detection, text helpers

---

Package this for npm

To publish as an npm package so others can pi install npm:pi-mpc:

package.json

{
  "name": "pi-mpc",
  "version": "1.0.0",
  "description": "MPC (Mental Preview & Correction) extension for pi coding agent",
  "type": "module",
  "license": "MIT",
  "keywords": ["pi-package", "pi-extension", "mpc", "plan-mode", "coding-agent"],
  "pi": {
    "extensions": ["./index.ts"]
  },
  "files": [
    "index.ts",
    "phases.ts",
    "persist.ts",
    "utils.ts",
    "README.md"
  ],
  "peerDependencies": {
    "@mariozechner/pi-coding-agent": "*",
    "@mariozechner/pi-tui": "*"
  }
}

Then:

npm publish --access public

Consumers install with:

pi install npm:pi-mpc

---

Contributing

Issues and PRs welcome at github.com/ShawnRong/pi-mpc.

---

License

MIT