pi-switch — generic subagent switcher for pi

A tiny pi extension that gives you a persistent indicator of the current subagent (header bar above chat) and lets you cycle / set / create agents. Generic — works with any agent in ~/.pi/agent/agents/.

Features

• Header bar above chat — shows current agent with emoji + description
• Ctrl+Shift+S to cycle to next agent (Shift+Tab is taken by pi's thinking-level cycler)
• /agent slash command to show current + available
• /agent <name> to set explicitly
• /agent create <name> to scaffold a new user agent
• /agent doctor to diagnose
• /agent recommend <task> to suggest the right agent for a task
• Task → agent heuristics baked into the system prompt so the LLM picks the right agent for the task
• Persists to .soly/agent (if soly project) or ~/.pi-switch/agent (standalone)
• Reads user agents from ~/.pi/agent/agents/*.md on every cycle — drop a file and Ctrl+Shift+S to see it

How agents work

Agents are markdown files with YAML frontmatter. pi-subagents (and pi-switch) discover them from these locations:

| Path | Type | Editable | |---|---|---| | ~/.pi/agent/npm/node_modules/pi-subagents/agents/*.md | built-in (worker, oracle, scout, ...) | ❌ | | ~/.pi/agent/agents/*.md | user-defined | ✅ | | ~/.pi/agent/extensions/soly/agents/*.md (auto-installed if useSolyWorkerSubagents: true in .soly/config.json) | soly-augmented (soly-worker, soly-debugger, ...) | ✅ source |

Frontmatter schema

---
name: my-reviewer              # required, unique, [a-zA-Z0-9_-]{1,64}
description: One-liner shown in picker
thinking: medium               # off | minimal | low | medium | high | xhigh
systemPromptMode: replace      # replace | append
inheritProjectContext: true
inheritSkills: false
tools: read, grep, find, ls, bash, edit, write
defaultContext: fork           # fresh | fork
---

You are `my-reviewer`. The system prompt goes here.

Create a new agent

Option A: manually

Drop a markdown file in ~/.pi/agent/agents/<name>.md (see schema above). Press Ctrl+Shift+S in pi — it joins the cycle.

Option B: via slash command

/agent create my-debugger

You'll be prompted for a one-liner description. Then edit the file to specialize the system prompt.

Test agents

| Action | How | |---|---| | See current + available | /agent | | Cycle | Ctrl+Shift+S | | Set explicitly | /agent soly-debugger | | Diagnose | /agent doctor | | Recommend for a task | /agent recommend investigate React Server Components |

The LLM can also auto-pick — see "Task → agent" below.

Task → agent heuristics

The LLM's system prompt includes a table mapping task keywords to agents. When the user request matches, the LLM should call /agent <name> first, then subagent({ agent: <name>, ... }).

| Keywords | Agent | Why | |---|---|---| | research, investigate, look up, find out, explore, compare libraries | 📚 researcher | external docs, ecosystem behavior | | scout, scan, map, where is, locate, skim | 🔍 scout | codebase recon | | plan, design, architect, outline, structure | 📋 planner | decompose into steps | | review, audit, check, adversarial, critique, qa | 👀 reviewer | adversarial review | | oracle, decision, tradeoff, which approach, drift | 🔮 oracle | decision consistency | | debug, bug, fix, crash, error, repro | 🐞 soly-debugger | bug investigation | | test, tests, coverage, spec, assert | 🧪 soly-tester | test-only work | | refactor, clean up, simplify, extract, rename | 🔄 soly-refactor | pure refactoring | | document, docs, readme, jsdoc | 📝 soly-documenter | doc updates | | implement, build, write code, add feature | ⚡ worker | implementation | | orchestrate, coordinate, dispatch, chain | 🤝 delegate | multi-agent |

Same keywords in Russian work (изучи, баг, тест, etc.).

Integration with other extensions

• soly reads globalThis.__PI_SWITCH_AGENT__ to know which subagent to launch for soly execute. Falls back to "worker" if pi-switch isn't loaded.
• Soly also auto-installs soly-augmented agents (soly-worker, soly-debugger, etc.) to ~/.pi/agent/agents/ when useSolyWorkerSubagents: true in .soly/config.json.

Files

• core.ts — agent metadata, discovery, cycling, persistence
• prompt.ts — system-prompt section + task→agent heuristics + recommendAgent
• index.ts — header bar, Ctrl+Shift+S, /agent slash command, /agent create//agent doctor//agent recommend
• tests/core.test.ts — 21 tests for core logic
• tests/prompt.test.ts — 20 tests for prompt + recommendAgent

Development

cd ~/.pi/agent/extensions/pi-switch
bun test          # 41 tests
bun run typecheck # tsc --noEmit