pi-oc-style-agent-switcher

中文

Keyboard-driven primary-agent model switching for Pi, inspired by opencode's <a-left> / <a-right> agent switching.

Install

pi install npm:pi-oc-style-agent-switcher

Reload Pi: /reload

Agent Profiles

The agent section follows the same idea as OpenCode's primary-agent config. Use it for switchable profiles in ~/.pi/agent/settings.json. The extension reads only each profile's model field. mode is optional; when omitted, the profile is still switchable. An explicit mode: "subagent" is reserved for future features and is currently excluded from the switcher.

For OpenCode compatibility, agent.<name> may also use variant as a sibling field. Do not set both thinking and variant on the same agent entry.

Example: OpenCode-style agent

{
  "agent": {
    "opencodezen": {
      "model": "opencode/deepseek-v4-flash-free",
      "tools": {
        "write": true,
        "edit": true,
        "bash": true
      }
    },
    "build": {
      "mode": "primary",
      "model": "opencode/deepseek-v4-flash-free",
      "tools": {
        "write": true,
        "edit": true,
        "bash": true
      }
    },
    "orchestrator": {
      "model": "github-copilot/claude-sonnet-4.6",
      "variant": "high"
    }
  }
}

Project settings in <project>/.pi/settings.json override global settings field-by-field.

Example: project override

{
  "agent": {
    "orchestrator": {
      "mode": "primary",
      "model": "openai-codex/gpt-5.4"
    }
  }
}

If the global config contains opencodezen, build, and orchestrator, but this project overrides only orchestrator.model, then the switcher will still see the same primary profiles while using the project-specific orchestrator model.

The switcher reads agent.<name>.model when it is configured; otherwise a selected build or orchestrator profile inherits the current session model and keeps the current thinking level unchanged. When orchestrator is selected, the extension appends the first available prompt body in this order: project-local .pi/agents/orchestrator.md → global ~/.pi/agent/agents/orchestrator.md → packaged fallback templates/agents/orchestrator.md. The build profile stays in normal main-session mode and does not auto-inject a special prompt. It accepts OpenCode-style tools object syntax for compatibility, but does not apply those tools today. thinking and all /run <agent> child-session behavior remain owned by Pi and installed subagent packages. This extension never invokes a subagent.

Subagent-oriented mode: "subagent" behavior may be added in a future release; for now, child-agent execution is still configured by your subagent package.

Valid:

{
  "agent": {
    "A": { "thinking": "high" },
    "B": { "variant": "low" }
  }
}

Invalid:

{
  "agent": {
    "A": {
      "thinking": "high",
      "variant": "low"
    }
  }
}

Subagent configuration

Configure child-agent behavior according to the subagent package you use. For pi-subagents, use subagents.agentOverrides.

{
  "subagents": {
    "agentOverrides": {
      "orchestrator": {
        "model": "github-copilot/claude-sonnet-4.6",
        "thinking": "high",
        "tools": [
          "read",
          "grep",
          "find",
          "ls",
          "bash",
          "edit",
          "write",
          "subagent",
          "wait",
          "web_search",
          "fetch_content",
          "get_search_content"
        ]
      },
      "explorer": {
        "model": "github-copilot/gpt-5-mini",
        "thinking": "low",
        "tools": ["read", "grep", "find", "ls", "bash"]
      }
    }
  }
}

This is where you tune the child-session details for orchestrator. If you prefer, you may also place those details directly in the agent file frontmatter of ~/.pi/agent/agents/orchestrator.md instead of JSON. If the orchestrator prompt body names additional child helpers such as researcher, reviewer, scout, or worker, keep those names aligned with your Pi child-agent definitions too — either define them in subagents.agentOverrides or intentionally rely on builtin subagent defaults.

On first load, if neither ~/.pi/agent/agents/orchestrator.md nor <project>/.pi/agents/orchestrator.md exists, the package copies its bundled fallback template to ~/.pi/agent/agents/orchestrator.md so /run orchestrator works without extra setup.

Keys

| Key | Action | |---|---| | Alt+Shift+← Alt+Shift+→ | Select and apply previous/next primary model | | /agents | Show switchable profiles and bindings |

Use Alt+←/→ instead

The package reads its own shortcut config from ~/.pi/agent/agent-switcher.json. Changing only ~/.pi/agent/keybindings.json is not enough.

~/.pi/agent/agent-switcher.json:

{ "cyclePrev": "alt+left", "cycleNext": "alt+right" }

Free Pi's conflicting built-ins in ~/.pi/agent/keybindings.json:

{
  "tui.editor.cursorWordLeft": [],
  "tui.editor.cursorWordRight": [],
  "app.tree.foldOrUp": [],
  "app.tree.unfoldOrDown": [],
  "app.model.cycleBackward": ["alt+shift+left"],
  "app.model.cycleForward": ["alt+shift+right"]
}

Migration from oh-my-opencode-slim

This package includes two complementary skills:

/skill:omo-slim-conf-mig [all|global|local]
/skill:omo-slim-mig      [all|global|local]

omo-slim-conf-mig reads the user's local/global OpenCode JSONC and migrates explicit values. omo-slim-mig reads the upstream raw GitHub README and agent prompts, then fills only missing values. If an orchestrator.md already exists, omo-slim-mig compares it with the upstream-based Pi version and asks before syncing. Both support all, global, and local; both ensure the global orchestrator prompt exists and create agent.orchestrator even if the relevant source lacks it.

Use oh-my-opencode-slim as a reference for converting agent prompts and JSON configuration. Configure switchable primary models under agent; configure child-agent model, thinking, tools, and prompts under subagents.agentOverrides.

Required Global Orchestrator Prompt

Every migration creates this global file by default:

~/.pi/agent/agents/orchestrator.md

It contains the orchestrator role prompt. Use YAML frontmatter for identity and Pi behavior, followed by the converted system prompt body:

---
name: orchestrator
description: Master delegator and strategic coordinator
systemPromptMode: replace
inheritProjectContext: true
inheritSkills: false
---

<Role>
Converted orchestrator instructions from oh-my-opencode-slim.
</Role>

Do not create a project-local orchestrator.md unless the project genuinely needs a different role prompt. Model, thinking, and tools may remain in this file, in subagents.agentOverrides, or fall back to Pi defaults; do not repeat a field in frontmatter if you expect agentOverrides to control it. When you create or sync this prompt, preserve an explicit Pi child-agent roster: keep explorer, librarian, oracle, designer, fixer, observer, and council as primary specialists, and add researcher, reviewer, scout, and worker as workflow helpers when those child-agent names are available. Do not list main-session profiles such as build or opencodezen as child specialists.

Migration Method

Copy one prompt to your LLM agent (Claude Code, Cursor, etc.) when you prefer the direct HTTP-based migration rather than /skill:omo-slim-mig. The LLM should use the linked guide as reference; it must not install or modify oh-my-opencode-slim itself.

global: migrate global configuration

Use oh-my-opencode-slim as a migration reference:
https://raw.githubusercontent.com/alvinunreal/oh-my-opencode-slim/refs/heads/master/README.md

Do not install or modify oh-my-opencode-slim. Read its README and relevant
src/agents/*.ts files, then migrate my global configuration to Pi:

1. Put switchable primary model profiles in ~/.pi/agent/settings.json → agent.
   Keep only agents intended for model switching, with mode: "primary".
2. Put child-agent model, thinking, tools, and prompt overrides in
   ~/.pi/agent/settings.json → subagents.agentOverrides.
3. Always ensure ~/.pi/agent/agents/orchestrator.md exists using the required
   frontmatter/body format documented above.
4. If an orchestrator.md already exists, compare it to the upstream-based Pi
   version instead of overwriting it blindly. Summarize the differences and ask
   whether to keep it, sync only Pi/subagent integration parts, or fully sync.
5. When you create or sync orchestrator.md, preserve an explicit Pi child-agent
   roster. Keep `explorer`, `librarian`, `oracle`, `designer`, `fixer`,
   `observer`, and `council` as primary specialists, and add `researcher`,
   `reviewer`, `scout`, and `worker` as workflow helpers when available. Do not
   list main-session profiles like `build` or `opencodezen` as specialists.
6. Create other global agent markdown files only when their role prompts are
   needed.
7. Preserve existing unrelated Pi settings.

local: migrate one project

Use oh-my-opencode-slim as a migration reference:
https://raw.githubusercontent.com/alvinunreal/oh-my-opencode-slim/refs/heads/master/README.md

Do not install or modify oh-my-opencode-slim. Read its README and relevant
src/agents/*.ts files, then migrate configuration for this Pi project only:

1. Write project primary-model overrides to .pi/settings.json → agent.
2. Write project child-agent overrides to
   .pi/settings.json → subagents.agentOverrides.
3. Keep ~/.pi/agent/agents/orchestrator.md as the default orchestrator prompt.
4. If an orchestrator.md already exists, compare it against the upstream-based
   Pi version first. Summarize differences and ask whether to keep it, sync
   only Pi/subagent integration details, or fully sync.
5. When you create or sync orchestrator.md, preserve an explicit Pi child-agent
   roster. Keep `explorer`, `librarian`, `oracle`, `designer`, `fixer`,
   `observer`, and `council` as primary specialists, and add `researcher`,
   `reviewer`, `scout`, and `worker` as workflow helpers when available. Do not
   list main-session profiles like `build` or `opencodezen` as specialists.
6. Create .pi/agents/orchestrator.md only when this project needs a genuinely
   different orchestrator role prompt.
7. Create other .pi/agents/*.md only for project-specific prompt overrides.
8. Preserve global Pi configuration and unrelated project settings.

global+local: migrate shared config and project overrides

Use oh-my-opencode-slim as a migration reference:
https://raw.githubusercontent.com/alvinunreal/oh-my-opencode-slim/refs/heads/master/README.md

Do not install or modify oh-my-opencode-slim. Migrate shared configuration to
~/.pi/agent/settings.json, then add only differing project values to
.pi/settings.json:

1. Primary model switch profiles belong in agent.
2. Child subagent behavior belongs in subagents.agentOverrides.
3. Always ensure ~/.pi/agent/agents/orchestrator.md exists as the shared
   default prompt.
4. If an orchestrator.md already exists, do not overwrite it blindly. Compare
   the current file with the upstream-based Pi version, summarize the
   differences (especially Pi/subagent integration vs upstream workflow drift),
   and ask whether to keep it, sync only integration parts, or fully sync.
5. When you create or sync orchestrator.md, preserve an explicit Pi child-agent
   roster. Keep `explorer`, `librarian`, `oracle`, `designer`, `fixer`,
   `observer`, and `council` as primary specialists, and add `researcher`,
   `reviewer`, `scout`, and `worker` as workflow helpers when available. Do not
   list main-session profiles like `build` or `opencodezen` as specialists.
6. Create a project-local replacement only for a genuinely different role
   prompt.
7. Use project settings only to override model/thinking/tools/prompt fields
   that differ from global settings.
8. Preserve all unrelated existing JSON fields and agent files.

Concept Mapping

| oh-my-opencode-slim | Pi | |---|---| | OpenCode primary agent | settings.json → agent | | oh-my agent model/variant | subagents.agentOverrides.<name>.model/thinking | | @agentName | subagent({ agent: "name", ... }) | | task(background: true) | subagent({ async: true }) | | Agent prompt in src/agents/*.ts | ~/.pi/agent/agents/*.md or .pi/agents/*.md |

License

MIT