ampi

A locked, mode-based coding harness for Pi Agent with deterministic multi-model routing across your providers.

ampi is a Pi Agent extension package. It replaces Pi's default coding posture with a small set of locked modes — each a complete bundle of model preferences, thinking policy, tool allowlist, and prompt — and picks which provider and model actually serves each mode by walking an ordered preference list against the models your Pi install has registered. Routing is rule-based and inspectable: there is no prompt classifier and no silent model switching. It runs entirely on your own Pi install, subscriptions, API keys, and settings.

The npm package name is @skippermissions/ampi; ampi is the name you see in commands, modes, flags, and settings. (The project's internal id is mmr, the "multi-model router", which still appears as an accepted alias.)

Highlights

• Deterministic, mode-based routing. You pick an intent (a mode); ampi resolves a concrete provider/model route from that mode's ordered preference list. Mode selection and route resolution are pure rules — same inputs, same route — and every decision is visible in /ampi-status debug.
• Auth-probing route resolution. For each preferred model, ampi enumerates the provider routes that could serve it, probes each for registration and configured auth (hasConfiguredAuth / OAuth checks), and applies the first route that is registered, authenticated, and accepted by Pi. Skipped routes keep a recorded reason ("not registered", "registered but not authenticated", and so on).
• Subscription-first ordering. Routes are grouped subscription/OAuth providers first, then API-key providers, then everything else, and ordered within each group by a fixed provider priority — so a Claude or Codex subscription is preferred over a metered API key for the same model, without you wiring it up per mode.
• Quota-aware session fallback. When the active route fails at the end of a turn, ampi classifies the error per provider — usage limit, rate limit, overload, silent capacity stall, or hard quota — and distinguishes transient conditions (retryable, may self-heal) from hard ones. When it warrants, it surfaces an explicit fallback prompt instead of quietly changing your model.
• Subagents and background fleets. Built-in workers (finder, oracle, librarian, Task, reviewer) run as separate Pi subprocesses with their own resolved routes; work can be launched in the background with a live TUI task board and task_poll / task_wait / task_cancel controls. Custom Markdown subagents (sa__*) can be imported with scoped tools and models.
• Opt-in reach. Web search/page reading, read-only GitHub tools, and prior-session recall are separate extensions, off by default, and gated behind explicit environment flags.

Requirements

Pi must already be installed and authenticated with at least one provider. ampi is a Pi extension, not a standalone CLI; it declares Pi's packages as peer dependencies and needs Node.js 22.19+.

Install

pi install npm:@skippermissions/ampi          # install for your user (recommended)
pi install -l npm:@skippermissions/ampi       # install for one project (.pi/settings.json)
pi -e npm:@skippermissions/ampi --ampi-mode medium  # try once without installing

Keep it current:

pi update --extensions                # update all Pi packages
pi update npm:@skippermissions/ampi   # update just ampi

Prefer git, or want an unreleased commit? Use the git source (pin with @<ref>):

pi install git:github.com/5omeOtherGuy/ampi

First minutes

pi -e npm:@skippermissions/ampi --ampi-mode medium

Then, inside Pi:

/ampi-status         # the resolved harness: mode, model, active tools
/ampi-status debug   # per-route diagnostics — which routes were tried, chosen, or skipped and why
/mode low            # quick, focused turns
/mode high           # demanding implementation, debugging, and review
/mode ultra          # maximum supported reasoning effort
/mode free           # stock Pi behavior; ampi-owned tools removed

Delegate bounded work to subagents:

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.
Use reviewer to review all uncommitted changes.

Enable optional reach only when you want it:

export AMPI_WEB_ENABLE=true
export AMPI_GITHUB_ENABLE=true
export AMPI_HISTORY_ENABLE=true

Control surface: /ampi-* commands, --ampi-* flags, AMPI_* env vars, and ampi* settings. The legacy mmr spellings (/mmr-*, --mmr-*, MMR_*, mmr*) remain accepted as aliases.

Modes

Each mode is a complete, locked harness. Switching modes swaps the model preference order, thinking policy, context profile, tool allowlist, and prompt together.

Mode	Model preference order	Optimized for
low	gpt-5.6-terra → gpt-5.5	Quick, focused work with medium reasoning and the Smart prompt posture
medium	gpt-5.6-sol → claude-opus-4-8	Balanced default coding with medium reasoning and a 300k context safety profile
high	gpt-5.6-sol → claude-opus-4-8	Demanding work with extra-high reasoning and the Deep prompt posture
ultra	gpt-5.6-sol → gpt-5.5	Maximum effort with Pi's xhigh reasoning and the Deep prompt posture
free	native Pi controls	Releases ampi model/thinking/prompt/tool enforcement

Mode selection precedence: --ampi-mode flag → restored session state → ampiCore.defaultMode setting → medium. Legacy rush, smart, deep, and fable values are accepted and migrate to low, medium, high, and ultra, respectively.

Model IDs above are the shipped defaults; you can override the preference list per mode and per subagent in settings.

Interactive controls:

/mode                # show current mode
/mode high           # switch mode
Ctrl+Shift+S         # mode picker (Alt+M fallback)
Ctrl+Space           # cycle low → medium → high → ultra
Alt+R                # toggle the active mode's thinking preset where supported

Providers

ampi routes against whatever providers your Pi install registers. The built-in priority order recognizes ten, grouped so subscriptions win first:

• Subscription / OAuth: claude-subscription, openai-codex, github-copilot
• API key: anthropic, openai, azure-openai-responses
• Other registered providers: google, google-vertex, openrouter, vercel-ai-gateway

A registered provider outside this list still routes; it just sorts into the last group. Model-ID aliases (for example a bare ID and its date-suffixed publication ID) are resolved so a preference written either way still matches.

How routing and fallback work

Resolving a route. For the active mode, ampi reads the ordered model preference list. For each preferred model it builds the candidate provider routes (the model's default providers plus any registered provider that offers it), sorts them subscription-first then by provider priority, and probes each for registration and configured auth. The first route that is registered, authenticated, and accepted by Pi becomes the active model. If earlier routes were skipped, the reason is recorded and shown in /ampi-status debug; worker tools use the same resolver to pick a route without disturbing the session's active model.

Falling back mid-session. The ampi-session-fallback extension watches for provider errors at the end of a turn and classifies them by provider and message: hard usage/quota limits, rate limits, overloads, and Anthropic silent-capacity stalls, separating transient conditions (which may self-heal, so the prompt is deferred) from hard ones (which escalate immediately). When a condition warrants it, ampi offers an explicit fallback rather than mutating your route silently.

Extensions

The package ships as a set of Pi extensions; the network and history ones are off until you enable them.

Extension	Default	What it adds
ampi-core	On	Locked modes, route resolution, thinking/context policy, prompt rewrite, diagnostics, config flow
ampi-session-fallback	On	Quota/rate-limit/overload classification and explicit fallback
ampi-patch	On	Path-safe apply_patch editing
ampi-tasks	On	Session-local task_list planning widget
ampi-workers	On	finder, oracle, Task, reviewer, gated librarian, background fleets
ampi-custom-subagents	On	Markdown sa__* workers with scoped tools/models/thinking
ampi-web	Off	Opt-in web search/page reading (SearXNG, Brave, DuckDuckGo fallback) with SSRF protection
ampi-github	Off	Opt-in read-only GitHub tools and the librarian prerequisite
ampi-history	Off	Opt-in local Pi session search and reuse behind opaque refs

Configure your own defaults

Non-secret settings live in Pi settings files (~/.pi/agent/settings.json, <project>/.pi/settings.json); secrets go in environment variables. Restart Pi after changing settings or gating env vars.

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

export AMPI_WEB_ENABLE=true
export AMPI_GITHUB_ENABLE=true
export AMPI_HISTORY_ENABLE=true
export BRAVE_API_KEY="..."
export AMPI_GITHUB_TOKEN="ghp_xxx"

Some safety defaults worth knowing: locked modes are fail-closed (no usable model or an empty tool set aborts activation before any change); free mode removes only ampi-owned tools; GitHub and search keys are read from the environment, not settings files; read_web_page rejects localhost and private/link-local targets; and history hides raw session paths behind opaque refs, with content redaction available via AMPI_HISTORY_REDACT=true.

Status

Pre-1.0 and a work in progress. ampi is at 0.2.0, developed against specific Pi releases (see the peer-dependency ranges in package.json), and it moves fast. Expect rough edges and breaking changes between versions. The default model IDs track current releases and will change. In-progress and planned work is tracked in ROADMAP.md; recent items include richer fallback-event history in /ampi-status debug, more background-widget metadata, a TUI browser for prior sessions and stored research results, and an MCP tool surface with the same gated, self-contained posture. Tests are deterministic and make no live provider calls, so the committed suite does not exercise real network behavior.

Documentation

• Docs index: docs/README.md
• Quick lookup: docs/quick-reference.md
• Public API: docs/public-api.md, docs/ampi-core-api.md
• Architecture: docs/reference-architecture.md
• Subagents: docs/subagent-framework.md
• Contributor map: INDEX.md, REPOMAP.md, ROADMAP.md

Development

git clone https://github.com/5omeOtherGuy/ampi
cd ampi
npm install
pi -e "$PWD" --ampi-mode medium  # run the local checkout

Checks:

npm test          # deterministic; no live provider/API calls
npm run lint
npm run check
npm run pack:dry-run

License

MIT.