@danchamorro/pi-agent-modes

Agent modes for pi -- switch between focused operational modes with enforced tool restrictions and distinct behavioral prompts.

Modes

| Mode | Tools | Bash | Edits | Purpose | |------|-------|------|-------|---------| | Code | All | Unrestricted | All files | Default. Write, modify, or refactor code. | | Architect | read, bash, edit, write, grep, find, ls | Read-only allowlist | .md, .mdx only | Plan, design, and strategize before implementation. | | Debug | All | Unrestricted | All files | Systematic problem diagnosis and resolution. | | Ask | read, bash, grep, find, ls | Read-only allowlist | None | Q&A -- explanations, research, and documentation. | | Review | read, bash, grep, find, ls | Review-safe allowlist | None | Code review with structured feedback. |

Each mode has a distinct PI persona and mode-specific custom instructions that guide the agent's behavior.

Install

pi install npm:@danchamorro/pi-agent-modes

Or add to ~/.pi/agent/settings.json:

{
  "packages": ["npm:@danchamorro/pi-agent-modes"]
}

Usage

Command:

/agent-mode              Show mode selector
/agent-mode code         Switch to code mode
/agent-mode architect    Switch to architect mode
/agent-mode debug        Switch to debug mode
/agent-mode ask          Switch to ask mode
/agent-mode review       Switch to review mode
/agent-mode setup        Assign models and thinking levels per mode

Keyboard shortcut:

Ctrl+Shift+M -- cycle through modes.

CLI flag:

pi --agent-mode architect

How enforcement works

Enforcement is three-layered, not just prompt guidance:

1. Tool visibility: setActiveTools() controls which tools the model can see. In ask mode, bash/edit/write don't exist for the model.
2. Bash restrictions: For architect and review modes, bash commands are validated against an allowlist at the tool_call level. Destructive commands (rm, git push, npm install, etc.) are blocked before execution. Piped and chained commands are also checked.
3. File restrictions: In architect mode, edit and write are restricted to markdown files (.md, .mdx). Other file types are blocked at the tool_call level.
4. Prompt injection: Each mode appends a behavioral prompt to the system prompt via before_agent_start, setting the agent's persona and custom instructions.

Model setup

By default, all modes use whatever model is active in your session. To assign specific models and thinking levels per mode, run:

/agent-mode setup

This walks through each mode, letting you pick a model and thinking level from your available models. Pressing Escape at any point cancels the setup. The configuration is saved to ~/.pi/agent/agent-modes.json.

You can re-run setup at any time to change assignments. Selecting "No override" for a mode clears any previous assignment.

Configuration

Override mode defaults with JSON config files. Project overrides take precedence over global, which take precedence over built-in defaults.

Global: ~/.pi/agent/agent-modes.json Project: .pi/agent-modes.json

Example: assign models to modes

{
  "architect": {
    "provider": "openai",
    "model": "o3",
    "thinkingLevel": "high"
  },
  "code": {
    "provider": "anthropic",
    "model": "claude-sonnet-4-5",
    "thinkingLevel": "medium"
  },
  "debug": {
    "provider": "anthropic",
    "model": "claude-sonnet-4-5",
    "thinkingLevel": "high"
  }
}

Example: customize architect to allow shell scripts

{
  "architect": {
    "editableExtensions": [".md", ".mdx", ".sh"]
  }
}

Override fields

Each mode supports these overrides:

| Field | Type | Description | |-------|------|-------------| | tools | string[] or "all" | Tools visible to the model | | bash | "all", "none", "restricted" | Bash access level | | editableExtensions | string[] | File extensions allowed for edit/write | | prompt | string | System prompt addition | | provider | string | Model provider name | | model | string | Model ID | | thinkingLevel | string | "off", "minimal", "low", "medium", "high", "xhigh" |

State persistence

The active mode is persisted across session restarts via appendEntry. When you resume a session, the mode you were in is automatically restored.