pi-agents-switch

OpenCode-style primary agent switching for Pi.

Press F9 to cycle agents — just like Tab in OpenCode.

Install

pi install ~/project/agents-switch

Then /reload in pi.

Requires Pi ≥ v0.x (tested with the version shipping before_agent_start + before_provider_request events). If Pi's system prompt format changes, agent identity will be prepended instead of replacing the default role line — check the Pi console for a [agents-switch] warning if this happens.

Usage

| Action | How | |--------|-----| | Cycle agents | Press F9 (configurable) | | Pick agent | /switch → select from list | | Configure | /switch-config → create/delete/set hotkey/init builder agent |

How it works

┌──────────────────────────────────────────────────────────┐
│ PI (default)  ←F9→  🔨 Builder  ←F9→  (your agents...) │
│                      │                                   │
│ Uses your standard    AGENTS.md in                       │
│ ~/.pi/agent/          ~/.pi/agents/                      │
│                       builder/ + your custom agents      │
└──────────────────────────────────────────────────────────┘

🔨 Builder Agent

The extension ships with a Builder agent. Initialize it with:

/switch-config → "🎨 Initialize default agent (builder)"

The Builder understands the AGENTS.md format inside and out. Switch to it and ask:

"Create a new agent for code review that only has read access"

The Builder will design the agent, write the AGENTS.md, and set everything up.

Anatomy

• PI — default. No changes to your existing config. Inherits ~/.pi/agent/AGENTS.md and everything.
• Custom agents — each is a single AGENTS.md with YAML frontmatter (metadata) + Markdown body (system prompt):

  ~/.pi/agents/<name>/
  ├── AGENTS.md       ← YAML frontmatter + system prompt (all-in-one)
  └── skills/         ← agent-specific skills (auto-loaded, optional)

When you switch to an agent, its AGENTS.md body is injected into the system prompt. You can also configure model, thinking level, and tools per agent via the frontmatter.

Agent Config (AGENTS.md frontmatter)

---
name: 🎯 My Agent
description: Analyze and plan without making changes
provider: anthropic
model: claude-sonnet-4-5
thinkingLevel: medium
temperature: 0.7
topP: 0.9

# Tools: inherit from PI, then remove excluded_tools, then add tools
tools:
  - read
  - grep
excluded_tools:
  - edit
  - write

# Skills (same inheritance pattern)
skills:
  - my-skill
excluded_skills:
  - noisy-skill
---

# 📋 Plan

You are the **📋 Plan** agent.
Your role and specific instructions go here.

Inheritance Rules

Each agent starts with PI's current config, then applies:

1. Remove items listed in excluded_tools / excluded_skills
2. Add items listed in tools / skills
3. If an item appears in both tools and excluded_tools, tools wins (explicit include beats exclude)

Agent-specific skills (skills/ directory) are auto-discovered and always included.

Fallback Chain

When resolving an agent's config:

1. Agent-level: ~/.pi/agents/<name>/AGENTS.md
2. Project-level: <cwd>/.pi/agents/<name>/AGENTS.md — overrides agent-level fields
3. PI defaults: tools/skills from your running PI config

Creating agents

/switch-config → "➕ Create a new agent"

Or create files directly:

mkdir -p ~/.pi/agents/debug

cat > ~/.pi/agents/debug/AGENTS.md << 'EOF'
---
name: 🐛 Debug
description: Debugging specialist
tools:
  - read
  - bash
  - grep
---

# 🐛 Debug

You are a debugging specialist. Focus on:
- Root cause analysis
- Reproducing bugs
- Minimal fixes
EOF

Agents are auto-discovered from the filesystem — no registration needed.

Config

~/.pi/agent/agents-switch.json (minimal — only tracks hotkey + active agent):

{
  "version": 1,
  "hotkey": "f9",
  "default": "PI"
}

Frontmatter Reference

| Field | Type | Description | |-------|------|-------------| | name | string | Display name (e.g. "🔨 Builder") | | description | string | Short description shown in picker | | provider | string | Model provider (e.g. "anthropic") | | model | string | Model ID (e.g. "claude-sonnet-4-5") | | thinkingLevel | string | off, minimal, low, medium, high, xhigh | | temperature | number | Sampling temperature (0-2). Lower = more deterministic | | topP | number | Nucleus sampling threshold (0-1) | | tools | string[] | Tools to ADD after inheritance | | excluded_tools | string[] | Tools to REMOVE from PI's inherited set | | skills | string[] | Skills to ADD | | excluded_skills | string[] | Skills to REMOVE |

The Markdown body (everything after the last ---) is the system prompt injected before each agent turn.

Inspired by

• OpenCode agents — Tab cycling + primary agents
• pi-profiles — Profile isolation pattern
• pi-cycle — Hotkey + model switching pattern