Opium

Turn your Pi session into a small team.

The problem

One agent doing everything in one chat gets slow and blurry. It searches the codebase, reads docs, writes code and reviews it, all in the same context, while you wait. The context fills up with grep output, and a big decision rests on a single model's opinion.

What Opium does

Your Pi session becomes the lead. It hands work to specialists that run in the background while you keep talking, and their results come back to your session on their own. When a decision matters, it asks a council of different models and shows you where they agree.

One request, three agents at once, each in its own live pane (tmux here). The lead merges their reports and checks where they disagree.

Install

Paste this into your coding agent (Pi, Claude Code, Codex, ...):

Install and configure Opium for Pi by following https://raw.githubusercontent.com/akholod/pi-opium/main/docs/install.md

It asks which subscriptions you have and whether you want the full setup with the recommended extras, gives every agent a model that fits, and checks the result.

Or by hand:

pi install npm:pi-opium

Start Pi (or /reload a running session) and keep working as usual. Every agent starts on your session's model, so it works with whatever provider you have.

Your session's model is the lead: it decides what to hand off and to whom. Pick a strong one (/model). For web research, also install pi-web-access.

How it looks in practice

Just ask:

• "Find where auth tokens are refreshed" → scout searches, you keep going.
• "Fix the failing tests in api/" → fixer works in the background and reports back.
• "Get a second opinion on this migration plan" → the council answers.

While agents run, a list above the editor shows what each one is doing. Inside herdr or tmux, each one also gets a read-only pane that closes when it's done.

The team

Agent	Does
scout	finds files and code, fast
researcher	reads docs and the web, answers with sources
senior	architecture, hard bugs, code review
designer	UI and UX, built and polished
fixer	writes the code for a clear, bounded task
fast-generic	git, commits, tests, builds
vision	images for models that can't see them
council	three models answer, one sums up where they land

Handy commands

• /council <question>: ask the council directly.
• /opium-preset [name|off]: switch the models the team uses.
• /opium-doctor: check your setup; --live also pings every model.
• /reflect: review how the session went and suggest improvements.
• /deepwork <task>: a stricter workflow for big, risky changes.
• /orchestrator off: back to a plain Pi session.

Works better with

• pi-web-access: lets researcher search the web and read pages.
• npm i -g ctx7 (the Context7 CLI; or npx ctx7@latest, optional ctx7 login for higher limits): up-to-date library docs for researcher.
• pi mcp add gh_grep --url https://mcp.grep.app: GitHub code search for researcher.
• Any other MCP server added with pi mcp add: give it to an agent in opium.json, for example "scout": { "mcpServers": ["my-index"] }.

Config

One file: ~/.pi/agent/opium.json, created on first run. Out of the box every agent uses your session's model. Give an agent its own model, a backup model or a time limit:

{
  "agents": {
    "senior": { "model": "anthropic/claude-fable-5-1", "thinking": "high" },
    "fixer": {
      "model": "openai-codex/gpt-6-luna",
      "fallbackModels": ["anthropic/claude-sonnet-5-5"]
    }
  }
}

The council needs different models. Three seats on the same model is one opinion said three times. Give councillor-alpha, councillor-beta and councillor-gamma different models; Opium warns you until you do.

Ready-made presets for Claude, ChatGPT, Copilot, OpenCode Go, Gemini and a mix of them: docs/models.md.

Docs

• Install: step by step, written for an agent but fine by hand.
• Models: which model for which role, presets per subscription.
• Agents: who does what, what each may do, time limits.
• Configuration: every option in opium.json.
• Troubleshooting: what the doctor's warnings mean.

Under the hood

Agents run inside your Pi process through pi-agent-runner. They follow your permission rules, ask you in the usual dialog, and wrap up with a report when their time runs out.

Credits

Inspired by oh-my-opencode-slim.

MIT