pi-pilot

A Copilot Autopilot-inspired workflow: research, subagent exploration, questions, plan and execute.

Why

Agents work better when they plan before acting. pi-pilot adds:

• Read-only plan mode — agent explores and drafts a plan without touching code
• Subagent exploration — parallel read-only research spawns
• Questions — agent asks the user when it needs clarification
• Execute — planning agent hands off to execution agent. Plan becomes the execution context, tasks tracked via todo checklist
• Autopilot — optional auto mode. Agent plan and implement with you hands-free

Installation

pi install npm:pi-pilot

Usage

Three typical execution flows:

1. In-context execution

Plan and execute in the same session:

/pilot-plan        # enter planning mode
<describe your task>
<agent writes plan>
<iterate on plan>
/pilot-execute     # transition to execution — uses the plan just written

Plan mode restricts writes and edits to .agents/plans/, and best-effort limits bash to read-only commands. Use /pilot-plan again to disable.

2. Compact / new session execution

/pilot-plan
<describe your task>
<agent writes plan>
<iterate on plan>
/compact or /new
/pilot-execute @.agents/plans/yyyy-mm-dd-plan-file.md

This allows you to easily retain plan file across compaction or between sessions.

3. Auto mode

/pilot-plan-auto
<describe your task>

Agent will create the plan. No question asked. Once a plan file is written, execute mode is automatically entered.

Commands

| Command | Description | |---|---| | /pilot-plan | Toggle planning mode | | /pilot-plan-auto | Plan mode + auto-execute (transitions when plan is written) | | /pilot-execute [@path] | Start execution (optional plan path) | | /pilot-settings | Configure startup mode, subagent limits, cycle shortcut |

Shortcuts

Cycle Shortcut

Press the configured shortcut (default Ctrl+Shift+M) to cycle through modes:

idle → planning → planning-auto → idle

Customize the shortcut binding via /pilot-settings or by editing the config file directly.

Tools (agent)

• pilot_ask — Queue a question for the user (blocked in auto mode)
• pilot_subagent — Spawn a read-only exploration subagent
• pilot_todo — Manage the execution checklist (add, toggle, list, clear)
• pilot_done — Signal completion; exit execute mode

Configuration

~/.pi/agent/pi-pilot.json:

{
  "startupMode": "plan",
  "cycleShortcut": "ctrl+shift+m",
  "subagent": {
    "model": null,
    "maxParallel": 1
  }
}

• startupMode: null (default), "plan", or "plan-auto"
• cycleShortcut: keybinding to cycle modes (default "ctrl+shift+m")
• subagent.maxParallel: 0 disables, 1-3 allowed
• subagent.model: optional { provider, id } override