pi-modes

Switchable agent modes for pi-coding-agent. Each mode controls which tools are available and injects a mode-specific system prompt.

Inspired by opencode modes.

Install

pi install npm:pi-modes

Or clone into your extensions directory:

git clone https://github.com/R-Dson/pi-modes ~/.pi/agent/extensions/pi-modes

Or load directly:

pi --extension /path/to/pi-modes

After installing, enter /reload or restart Pi.

Usage

| Action | How | |---|---| | Switch mode | /mode ask, /mode edit, /mode review | | Next mode | Ctrl+Shift+L | | Previous mode | Ctrl+Shift+H | | Check current mode | /mode (shows active mode and disabled tools) | | Start in a mode | pi --extension pi-modes --mode ask |

Shipped modes

| Mode | Tools disabled | Purpose | |---|---|---| | Edit | none | Full access (default) | | Plan | bash | Read-only exploration, writes only to PLAN.md | | Ask | write, edit, bash | Read-only exploration and questions | | Review | write, edit, bash | Code review without making changes |

Adding modes

Create a .md file in the modes/ directory. The filename becomes the mode id used with /mode and --mode.

---
name: Debug
color: warning
tools:
  write: false
  edit: false
---
You are in debug mode. Investigate issues by reading code and running
diagnostic commands. Do not make changes.

Supported frontmatter:

• name -- display name (defaults to filename)
• color -- theme color for the chat box label: accent, warning, muted, success, error, dim (defaults to accent)
• tools -- list of tools to disable, each set to false

The body after the second --- is injected into the system prompt when the mode is active. Leave it empty to skip injection.

Persistence

Mode selection survives /reload and session resume via session state. The --mode flag takes priority over persisted state.

Note: each mode switch appends a small entry to the session. This is the standard pattern used by other pi extensions (tools, presets). In very long sessions this adds negligible overhead.

Plan mode

Plan mode uses both tool restrictions and prompt enforcement. bash is disabled at the harness level; the agent is told via prompt to only write to PLAN.md.

The current PLAN.md content is injected into the system prompt on every provider request (not just at session start), so it survives compaction and reflects mid-session edits. This uses the before_provider_request hook rather than before_agent_start because compaction can happen mid-agentic-loop during multi-turn tool use.

Caveats

Running alongside other extensions that call setActiveTools() (e.g., tools.ts, preset.ts) may cause conflicts, as both can modify the active tool set independently.