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