Agent modes for pi. Switch between focused operational modes with enforced tool restrictions and distinct behavioral prompts.
| Mode | Built-in 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, a short description shown on the status card, and mode-specific custom instructions that guide the agent's behavior.
The table above covers Pi's built-in tools. Extension tools and MCP tools remain visible, so information-gathering integrations continue to work inside restricted modes.
The active mode displays a status card in the UI:
CODE mode
Write, modify, or refactor code
bash:all | edit:all
The first line shows the mode name. The second line is a built-in description summarizing the mode's purpose. The third line shows the current tool restrictions. When model or thinking-level overrides are active, those appear as additional entries on the restrictions line.
pi install npm:@danchamorro/pi-agent-modesOr add to ~/.pi/agent/settings.json:
{
"packages": ["npm:@danchamorro/pi-agent-modes"]
}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 off Disable agent modes and restore default behavior
/agent-mode setup Assign models and thinking levels per mode
Keyboard shortcut:
Ctrl+Shift+M cycles through all modes, then off.
CLI flag:
pi --agent-mode architectEnforcement is layered, not just prompt guidance:
- Tool visibility:
setActiveTools()controls which built-in tools the model can see. In ask mode,editandwritedo not exist for the model.bashremains available, but only through the restricted allowlist. Extension and MCP tools remain visible. - Bash restrictions: For architect, ask, and review modes, bash commands are validated against an allowlist at the
tool_calllevel. Destructive commands (rm, git push, npm install, etc.) are blocked before execution. Piped and chained commands are also checked. - File restrictions: In architect mode, edit and write are restricted to markdown files (
.md,.mdx). Other file types are blocked at thetool_calllevel. - Prompt injection: Each mode appends a behavioral prompt to the system prompt via
before_agent_start, setting the agent's persona and custom instructions.
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.
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
{
"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"
}
}{
"architect": {
"editableExtensions": [".md", ".mdx", ".sh"]
}
}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" |
The active mode, including off, is persisted across session restarts via appendEntry. When you resume a session, the mode state you last used is automatically restored.