GitHub - 5omeOtherGuy/pi-mmr: Modular multi-model routing extensions for the Pi coding agent.

Switch your entire Pi coding harness — model, thinking, tools, and prompt — with one command. Fully reversible.

pi-mmr turns Pi into a coding harness you control. Instead of one fixed model-and-prompt configuration, you pick a mode — smart, smartGPT, rush, large, or deep — and pi-mmr swaps the whole profile in a single switch: that mode's provider-neutral model preferences, thinking policy, context profile, active-tool allowlist, worker profile, and prompt behavior. Every knob is exposed instead of hidden, and free releases every lock to return you to stock Pi at any time.

It is a modular Pi extension package, not a fork or a separate IDE — it builds on Pi's native behavior instead of replacing it. Each mode's prompt is assembled from its own fragments and surgically swapped into Pi's auto-rendered prompt head, preserving Pi's own tool list, guidelines, documentation, and tail. Tool resolution is exact-name based, runtime state is session-scoped, and everything runs on your own provider subscriptions and API keys.

Beyond modes, pi-mmr adds Pi-native tools for codebase search, expert review, GitHub repository research, web lookup, prior-session recall, safe patching, todos, and subscription quota fallback — each behind explicit feature gates. Bounded work can be delegated to workers (finder, oracle, librarian, Task) and to your own Markdown subagents, each running in its own context and returning just the result. Independent work can run in the background as a worker fleet (start_task/task_poll/task_wait/task_cancel) that renders in the Pi TUI with live status, output previews, an expandable trail, usage counters, and a grouped task board — so you can watch what runs instead of guessing. Locked modes are fail-closed, everything is reversible, and the deterministic test suite never makes live provider calls.

Why pi-mmr

• One command changes the whole harness. /mode deep is not just a model switch; it locks mode, model-preference order, thinking, tools, and prompt behavior together — and per-mode postures genuinely differ (fast and frugal vs. broad-context vs. careful-reasoning).
• A framework, not a black box. Model routing, thinking policy, tool allowlists, and prompt assembly are all explicit, inspectable via /mmr-status, and configurable in settings.
• Provider-neutral by design. Modes use explicit preference order: subscription/OAuth provider entries first, then API-key entries, then other registered providers — so the same mode follows you across providers.
• Right-sized delegation. Use finder, oracle, Task, and librarian, run independent jobs as a background fleet, or ship your own Markdown subagents — without hand-picking child models and tools.
• Fail-closed and reversible. A locked mode refuses to activate without a usable model and active tools; free releases every MMR-owned lock and tool registration.
• Optional reach, off by default. Web, GitHub, and local session-history tools stay gated until you explicitly enable them.
• Runs on your stack. Open source (MIT), self-hosted as a Pi package, driven by the providers you already authenticate.

Quick start

Pi must already be installed and authenticated.

pi -e git:github.com/5omeOtherGuy/pi-mmr --mmr-mode smart

Install globally or per project:

pi install git:github.com/5omeOtherGuy/pi-mmr
pi install -l git:github.com/5omeOtherGuy/pi-mmr

Verify the active locked mode inside Pi:

/mmr-status
/mode rush
/mode free

Pi (@earendil-works/pi-coding-agent) and @earendil-works/pi-agent-core are peer dependencies and are not bundled.

First two minutes

1. Start a session in the default locked mode:

   pi -e git:github.com/5omeOtherGuy/pi-mmr --mmr-mode smart

2. Inspect the active locked mode and gates:

   /mmr-status
   /mmr-status debug
   

3. Switch modes by intent:

   /mode rush       # fast, low-token turns
   /mode deep       # hard reasoning, planning, review
   /mode free       # stock Pi behavior; MMR-owned tools removed
   

4. Ask Pi to use a worker when the job is bounded:

   Use finder to locate where provider model preferences are resolved.
   Ask oracle to review the mode activation design.
   Use Task to update the focused docs file and run the narrow check.
   

5. Enable optional reach only when needed:

   export MMR_WEB_ENABLE=true
   export MMR_GITHUB_ENABLE=true
   export MMR_HISTORY_ENABLE=true

Choose a mode

Mode selection precedence: --mmr-mode flag → persisted session → mmrCore.defaultMode → smart.

Useful controls:

/mode              # show current mode
/mode deep         # switch mode
/mmr-status        # locked-mode status (add `debug` for model/tool resolution)
Ctrl+Shift+S       # mode picker  (Alt+M fallback)
Ctrl+Space         # cycle smart → smartGPT → rush → large → deep
Alt+R              # toggle the active mode's thinking preset (where supported)

Choose a tool

For command-style lookup, see the quick reference.

Delegate work to workers

Workers run bounded jobs in their own context and return just the result, so the main session stays focused:

• finder — fast, parallel codebase search; returns relevant files and line ranges.
• oracle — expert review, planning, and hard-bug reasoning, zero-shot.
• librarian — read-only research over remote GitHub repositories (gated on mmr-github).
• Task — a general worker for a scoped implementation, investigation, repair, or review; optionally narrowed to read-only or read-write.
• Custom subagents — your own Markdown-defined workers (sa__*), with model, thinking, tools, and skills set in frontmatter.

Independent work can run as a background fleet: call finder, librarian, or Task with background: true (parallel calls can share one worker group via a group key), and task_poll/task_wait/task_cancel coordinate the running tasks. start_task remains as a deprecated compatibility alias for one release. Completed work is surfaced automatically or pulled on demand, and the Pi TUI shows a live, grouped task board. See docs/subagent-framework.md.

Feature map

Optional capabilities

Non-secret settings live in Pi settings files. Secrets belong in environment variables.

{
  "mmrCore": {
    "defaultMode": "rush",
    "modelPreferences": {
      "deep": [{ "model": "gpt-5.5", "thinkingLevel": "medium" }]
    },
    "subagentModelPreferences": {
      "finder": [{ "model": "gpt-5.4-mini", "thinkingLevel": "low" }]
    }
  },
  "mmrWeb": { "enabled": true }
}

export MMR_WEB_ENABLE=true            # register web_search/read_web_page
export MMR_GITHUB_ENABLE=true         # register read-only GitHub tools
export MMR_HISTORY_ENABLE=true        # register find_session/read_session
export BRAVE_API_KEY="..."            # optional; env only
export MMR_GITHUB_TOKEN="ghp_xxx"     # optional; env only

Settings are read from ~/.pi/agent/settings.json and <project>/.pi/settings.json. Restart Pi after changing settings or env vars that gate tool registration.

Safety and privacy

• Locked modes are fail-closed: no usable model or zero active tools aborts activation before mutating Pi state.
• Tool resolution is exact-name based and reported as active, gated, disabled, deferred, or missing in /mmr-status.
• mmr-web only runs after opt-in and rejects localhost/private/link-local reads for read_web_page.
• mmr-github exposes read-only GitHub requests only; tokens are read from env and never echoed.
• mmr-history redacts session packets and returns opaque projectRef values instead of raw session paths or project roots.
• free mode drops only pi-mmr-owned tool registrations; third-party tools keep working.

Troubleshooting

Run /mmr-status first; add debug for model/tool resolution details.

Full troubleshooting: docs/troubleshooting.md.

Documentation

• Start here: docs/README.md
• Quick lookup: docs/quick-reference.md
• Public API: docs/public-api.md, docs/mmr-core-api.md
• Architecture: docs/reference-architecture.md
• Subagents: docs/subagent-framework.md
• Compatibility: docs/extension-compatibility.md
• Contributor map: INDEX.md, REPOMAP.md, ROADMAP.md

Development

npm test
npm run check
npm run pack:dry-run
pi -e "$PWD" --list-models

Tests are deterministic and must not make live provider/API calls. Documentation conventions: docs/documentation-style-guide.md.

License

MIT.