ampi

AMP Code but in Pi Agent.

ampi is a faithful, self-contained AMP Code-style harness for Pi Agent. It brings the AMP-style coding workflow into Pi as a production-ready extension package for the implemented workflows: opinionated locked modes, curated tools, subagents, background workers, web/repository/session context, fallback behavior, and strong defaults that aim for AMP Code parity while still running on your Pi install, subscriptions, API keys, models, and settings.

ampi is not an official AMP Code package. It is an independent Pi extension that implements the listed AMP-style behavior in repo-owned code and tracks remaining parity gaps below.

Use ampi as-is for the intended experience. Advanced users can override models, subagent routes, optional gates, and custom Markdown subagents, but the package ships with a complete default posture so a fresh install already feels like AMP Code inside Pi.

What ampi already gives you

AMP-style harness modes

• smart — default balanced coding mode with broad tools, provider-neutral model preferences, managed thinking, and the full coding posture.
• fable — Claude Fable 5 preference for Claude Code subscription users, with the same balanced Smart posture and a low/medium/high thinking cycle.
• rush — fast, low-token mode for small or mechanical changes.
• deep — reasoning-heavy mode for hard debugging, design, reviews, migrations, and multi-step implementation.
• free — exit hatch back to stock Pi behavior with ampi-owned tools removed.

Each locked mode swaps the whole harness together: model preference order, thinking policy, context profile, active-tool allowlist, subagent defaults, and model-visible prompt posture. Mode resolution is deterministic and inspectable; there is no hidden prompt classifier or silent automatic model switching.

AMP Code-style parity features already implemented

• Whole-harness mode switching via --ampi-mode, /mode, hotkeys, and persisted session/settings state.
• Provider-neutral model preferences that prefer subscription/OAuth providers first, then API-key providers, then other registered providers.
• Your subscriptions and keys: Claude subscription, OpenAI/Codex, API-key providers, Brave Search, GitHub tokens, and SearXNG all stay under your control.
• Managed thinking and context policy per mode, including mode-local thinking toggles and context display/capping where the mode owns it.
• Prompt posture replacement that preserves Pi's own tool list, docs, project context, skills, date/cwd, and tail content while replacing the coding harness head.
• Exact active-tool allowlists with /ampi-status debug diagnostics for active, gated, disabled, deferred, and missing tools.
• Safe local patching through apply_patch, including path-safety checks across the workspace and sibling worktrees.
• Session-local planning through task_list, rendered as a pinned Pi widget.
• Subagents: finder, oracle, librarian, Task, reviewer, the internal history-reader, and custom Markdown sa__* subagents.
• Background work fleets: background: true, grouped launches, live TUI task board, automatic completion delivery, and task_poll / task_wait / task_cancel controls.
• Repository research with librarian plus read-only GitHub tools (read_github, list_directory_github, glob_github, search_github, commit_search, diff_github, list_repositories).
• Web research with web_search and read_web_page, including SearXNG, Brave Search, DuckDuckGo fallback, domain filters, recency filters where supported, SSRF protections, and readable-page extraction.
• Prior-session recall with find_session and read_session, opaque project refs instead of raw paths, opt-in content redaction, and a read-only history-reader worker.
• Subscription quota/capacity fallback for provider failures, with explicit retry messaging instead of silent route mutation.
• Custom subagent import/setup for Markdown agent definitions with safe tool mapping, per-mode scope, model/thinking config, and project/global enablement.
• Production guardrails: deterministic tests, no live API calls in the committed suite, fail-closed activation, exact-name tool ownership, source-owned Free-mode cleanup, and public-safe prompt provenance.

Quick start

Pi must already be installed and authenticated. @skippermissions/ampi is the npm package name; ampi is the product and runtime brand you see in commands, modes, and settings.

Install for your user (recommended):

pi install npm:@skippermissions/ampi

Install for one project only (writes to .pi/settings.json, shareable with your team):

pi install -l npm:@skippermissions/ampi

Try it for a single run without installing:

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

Keep it up to date:

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

Prefer installing from git, or want an unreleased commit? Use the git source as a fallback (pin a tag or commit with @<ref>):

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

Inside Pi:

/ampi-status
/ampi-status debug
/mode rush
/mode deep
/mode free

The control surface is canonical ampi: /ampi-* commands, --ampi-* flags, AMPI_* env vars, and ampi* settings. The legacy /mmr-*, --mmr-*, MMR_*, and mmr* identifiers remain accepted as aliases for existing setups.

First two minutes

1. Start in the default AMP-style mode:

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

2. Inspect the resolved harness:

   /ampi-status
   /ampi-status debug
   

3. Switch modes by intent:

   /mode rush       # quick, low-token turns
   /mode deep       # hard reasoning, planning, review, migration work
   /mode fable      # Claude Fable 5 on a Claude Code subscription
   /mode free       # stock Pi behavior; ampi-owned tools removed
   

4. Delegate bounded work:

   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.
   

5. Enable optional reach only when needed:

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

Modes

Intent	Mode	What ampi controls
Balanced coding	smart	Default model preference order, medium/high thinking toggle, broad AMP-style tools, full coding posture
Claude Code subscription path	fable	Claude Fable 5 via claude-subscription, low/medium/high thinking toggle, Smart-style tools
Fast edits	rush	Fast model preferences, thinking off, lower-token posture, focused tools
Hard work	deep	Reasoning-first model preferences, deeper posture, patching/research/history/subagent tools
Native Pi	free	Releases ampi model/thinking/prompt/tool enforcement

Mode selection precedence: --ampi-mode flag → restored session state → ampiCore.defaultMode → smart.

Useful controls:

/mode              # show current mode
/mode deep         # switch mode
/ampi-status       # current harness status
/ampi-status debug # model/tool/source diagnostics
Ctrl+Shift+S       # mode picker  (Alt+M fallback)
Ctrl+Space         # cycle smart → rush → deep
Alt+R              # toggle the active mode's thinking preset where supported

Tools and subagents

Need	Use
Safe file patches	apply_patch
Session todo plan	task_list
Behavior-level codebase search	finder
Expert planning/review/debugging advice	oracle
Scoped implementation/investigation/repair	Task
Independent background work	background: true, task_poll, task_wait, task_cancel
Independent diff/code review	reviewer
Remote GitHub research	librarian
Direct read-only GitHub operations	read_github, list_directory_github, glob_github, search_github, commit_search, diff_github, list_repositories
Public web search/read	web_search, read_web_page
Prior Pi session recall	find_session, read_session
Custom workers	Markdown sa__* subagents imported through /ampi-config

Feature map

Extension family	Default	User value
ampi-core (mmr-core runtime id)	On	Locked modes, model resolution, request/thinking policy, active tools, prompt rewrite, diagnostics, config flow
ampi-patch	On	Safe apply_patch editing
ampi-tasks	On	Session-local task_list planning widget
ampi-workers	On	finder, oracle, Task, reviewer, gated librarian, background fleets, worker trails
ampi-custom-subagents	On	Markdown-defined sa__* workers with scoped tools/models/thinking
ampi-session-fallback	On	Explicit fallback on subscription quota, rate limits, overloads, and capacity stalls
ampi-web	Off	Opt-in web search/page reading through your chosen backend
ampi-github	Off	Opt-in read-only GitHub tools and librarian prerequisite
ampi-history	Off	Opt-in local Pi session search and reuse

The package also exposes ./extensions/ampi-* export aliases while keeping legacy ./extensions/mmr-* subpaths for existing consumers.

Configure your own defaults

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

{
  "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"

The AMPI_* env vars take precedence; the legacy MMR_* names (for example MMR_WEB_ENABLE) are still accepted.

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.

Production safety

• Locked modes are fail-closed: no usable model or zero active tools aborts activation before mutation.
• Free mode removes only ampi-owned tools; third-party tools keep working.
• Network and history features are opt-in and gated.
• GitHub tokens and web/search keys are read from env, not settings files.
• read_web_page rejects localhost/private/link-local targets.
• History always hides raw session file paths/project roots behind opaque refs; content redaction is opt-in with AMPI_HISTORY_REDACT=true.
• Worker runs are bounded, surfaced in the TUI, and report non-normal outcomes explicitly.

What is still missing

ampi is production-ready for the implemented AMP Code-style workflow, but parity work continues:

• Continued /mmr-*, --mmr-*, MMR_*, and mmr* legacy-alias compatibility alongside the canonical ampi surface.
• A richer /ampi-status debug history of deterministic mode/fallback events.
• More background-widget metadata and grouped completion polish.
• A TUI browser for prior sessions and stored web/research result IDs.
• A proxy-first MCP tool surface with the same gated/self-contained posture.
• Optional worktree isolation for child workers after safety semantics are pinned.

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
• Compatibility: docs/extension-compatibility.md
• Contributor map: INDEX.md, REPOMAP.md, ROADMAP.md

Development

Work on ampi from a local clone and load the working tree directly:

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

Checks:

npm test
npm run lint
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.