UltraPi

UltraPi is a Pi extension that turns one coding task into the smallest fleet that can finish it — and refuses to call the result done until an acceptance command says so.

It classifies the task, picks a bounded execution topology, allows exactly one agent to write code, verifies the outcome when an acceptance command exists, and records privacy-aware telemetry that never leaves your machine.

• Host harness: Pi Coding Agent 0.84.1
• Runtime: Node.js 24+
• Type: Pi package (extension) — not a hosted service or model provider. It ships one ultrapi binary, which only configures the extension; all real work happens inside Pi.

---

Table of contents

• Install
• Quick start
• What makes it different
• Telemetry: local-only, and what it is for
• How routing works
• Two things the names might promise that UltraPi will not do
• Configuration
• Documentation
• Development
• License

---

Install

Pi has its own package manager. You do not npm install an extension — you hand the source to pi install, which places it under ~/.pi/agent/npm/ (user scope) or .pi/npm/ (project scope) and registers it in settings.json.

Security note, and it applies to every Pi package including this one: extensions run with your full system permissions and execute arbitrary code. Read the source before installing anything, from anyone.

From git — works today

The npm release is not published yet, so this is the current install path:

pi install git:github.com/Y4nKorzun/pi-coding-agent-swarm-warroom-archive

No release tags are published yet, so pin a commit SHA if you want a reproducible install:

pi install git:github.com/Y4nKorzun/pi-coding-agent-swarm-warroom-archive@<commit-sha>

Pinned refs are not moved by pi update --extensions; re-run pi install with a new ref to move to one.

From npm — once published

pi install npm:ultrapi          # latest
pi install npm:ultrapi@1.0.0    # pinned; skipped by `pi update --extensions`

From a local checkout — for development

A local path is registered in place and is not copied, so your edits are live:

git clone https://github.com/Y4nKorzun/pi-coding-agent-swarm-warroom-archive.git UltraPi
cd UltraPi && npm install
pi install "$PWD"

Try it without installing

--extension (-e) installs to a temporary directory for one run only:

pi -e git:github.com/Y4nKorzun/pi-coding-agent-swarm-warroom-archive

Scope: just you, or the whole team

By default pi install writes to user settings (~/.pi/agent/settings.json). Use -l to write to project settings (.pi/settings.json) instead — those can be committed, and Pi installs missing project packages automatically on startup once the project is trusted.

pi install -l "$PWD"

Managing it afterwards

pi list                  # installed packages
pi config                # enable/disable extensions, skills, prompts, themes
pi update npm:ultrapi    # update just this package
pi remove npm:ultrapi    # uninstall

Why there is no build step

Pi loads extensions through jiti, so TypeScript runs without compilation. The manifest points Pi straight at the source:

{
  "pi": { "extensions": ["./src/index.ts"] }
}

src/index.ts default-exports the factory Pi calls with its ExtensionAPI. There is no dist/, and nothing to compile before installing.

Pi bundles its own copies of @earendil-works/pi-coding-agent and typebox, so UltraPi declares those as peerDependencies: "*" rather than shipping duplicates — two copies of the host's SessionManager would be two different classes, and identity checks between them would silently fail.

---

Quick start

Installing the package is not enough on its own. You must also run the configurator, which writes the budgets and the profile marker that UltraPi's default auto mode requires — without it every /ultra-config write fails with auto mode requires a valid profile marker.

# 1. register the extension with Pi
pi install git:github.com/Y4nKorzun/pi-coding-agent-swarm-warroom-archive

# 2. configure budgets, roster, and profiles (interactive; run with no flags for a walkthrough)
#    `pi install` does not put the bin on your PATH, so call it by path:
node ~/.pi/agent/git/github.com/Y4nKorzun/pi-coding-agent-swarm-warroom-archive/bin/ultrapi.mjs \
  --weekly-credit-budget 20 --daily-credit-budget 5
#    once published to npm this is simply: npx ultrapi --weekly-credit-budget 20 --daily-credit-budget 5

# 3. start the profile it created, then run a task
pi-private

/ultra Fix the failing checkout test. Acceptance: npm test

Step 2 is mandatory, and it is what creates the pi-private and pi-free launchers used in step 3. It deliberately has no default spending limit — a budget guessed on your behalf is the one default that can cost you real money.

Check what you got:

/ultra-config status     # mode, policy, budgets, active roster
/ultra-config doctor     # declared models, profile, compatibility pins

If a model is refused, it is not in that profile's roster — doctor prints exactly which ones are declared.

Choosing your own models

Nothing about the model list is built in. The shipped roster is just the default answer to the question, and any model id from any provider is equally valid. Order is weakest to strongest — position is capability rank, so the cheapest model scouts and the strongest handles deep work and arbitration.

The roster is set by the configurator below, not by a slash command — /ultra-config doctor shows you which models are currently declared.

Setting the roster, and optionally isolating profiles

The bundled configurator writes the roster and budgets, and creates two fully separated Pi profiles — different credentials, different rosters, no crossover. It creates pi-private and pi-free launchers (in ~/.local/bin unless you pass --bin-dir), tells you whether that directory is on your PATH, and prints the first command to run.

node --import tsx src/install.ts \
  --weekly-credit-budget 20 \
  --daily-credit-budget 5 \
  --models anthropic/claude-haiku-4-5,anthropic/claude-sonnet-5,anthropic/claude-opus-5 \
  --non-critical-models anthropic/claude-haiku-4-5

Run it with no arguments for an interactive walkthrough that explains each value and offers a starting number you can accept with Enter. --non-critical-models marks models allowed to investigate but not to decide. --per-task-policy defaults to balanced.

Authenticate each profile independently through its own normal Pi flow. UltraPi never reads, copies, or links another profile's auth.json.

---

What makes it different

The Pi ecosystem already has orchestration extensions. The closest is pi-agents, and UltraPi's relationship to it is worth stating plainly, because UltraPi actually depends on it: pi-agents is the bounded worker runtime UltraPi dispatches through.

The difference is who decides, and what counts as done.

	pi-agents and similar	UltraPi
Who designs the workflow	You do. It is a composition algebra — you write the expression tree of parallel/sequential agent nodes.	UltraPi does. It analyses the task and selects a bounded topology; you can override it.
Writers	As many as your tree declares.	Exactly one, always, in an isolated worktree.
Spending	Unbounded by the tool.	Hard weekly/daily ceilings, per-task policy, priced per model call, enforced at the tool layer.
Definition of done	The agents returned output.	A declared acceptance command passed — or UltraPi tells you it did not, and why.
Memory of past runs	None.	80 event types recorded locally, feeding config recommendations.

pi-agents is the better tool when you already know the shape of the work and want to express it exactly. UltraPi is the better tool when you do not, and want a ceiling on what a wrong guess can cost.

Because both register orchestration entry points, UltraPi removes the competing root-level tools (workflow, swarm, subagent, delegate_task, and others) from the root agent while it is active. One orchestration entry point — ultra_dispatch — is the whole design. Two would mean two definitions of "bounded", and neither would hold.

What it does not do

UltraPi does not grant OS isolation, supply model access, copy credentials between profiles, automatically promote configuration changes, or prove a real external outcome merely because a local test passed.

---

Telemetry: local-only, and what it is for

Nothing is transmitted. There is no server, no endpoint, no opt-out needed, because there is nothing to opt out of. UltraPi contains no HTTP client, no analytics SDK, and no outbound network code of any kind. The only sockets it opens are unix domain sockets in your temp directory, used for local IPC between the controller and its own workers.

You can verify that claim yourself rather than take it on faith:

grep -rE '\bfetch\(|node:http|node:https|axios|WebSocket' src/

What it is for

Think of it as a flight recorder for your own configuration. UltraPi cannot tell whether swarm was the right call for a task until it can compare what routing predicted against what actually happened — what it cost, whether verification passed, whether you had to redo the work. That comparison is the entire point.

The payoff is a feedback loop you own, run on your own schedule:

/ultra-config report YYYY-Www                              # build the week's sanitized bundle
/ultra-config recommendation accept <json-file> [id]       # apply a reviewed change
/ultra-config recommendation reject <json-file> [id]       # decline it, changing nothing
/ultra-config config rollback <version>                    # point the champion back at any earlier version

Nothing here auto-applies. A recommendation is a JSON file you review against the event log before accepting — Routing Regret is deliberately a candidate count, not a verdict, and returns null when a required signal is missing rather than guessing. Configuration versions are immutable: a change creates a new version instead of mutating the old one, so every recorded run stays attributable to the exact config that produced it, and rollback is just moving a pointer. Weekly review is the step-by-step procedure.

Feedback is what makes the loop close, and it must be given in the same session as the task:

/ultra-config feedback good
/ultra-config feedback bad <what went wrong>

Where it lives

Everything is under <PI_CODING_AGENT_DIR>/ultrapi/, created with mode 0700. With the profiles the configurator creates, that is ~/.pi-private/ultrapi/ and ~/.pi-free/ultrapi/; with a bare Pi install it is ~/.pi/agent/ultrapi/:

Path	Contents
events/	Append-only JSONL — 80 event types covering routing, spawns, model calls, tool use, verification, outcomes
ultrapi.db	SQLite rollup, sanitized before write
raw-vault/	Raw task text and verification evidence, AES-256-GCM encrypted under vault.key
ledgers/	Per-run plan-of-work state, accepted facts, and changed file paths — plaintext, not vault-encrypted
configs/	Immutable config versions
exports/	Only what you explicitly generate

Identifiers are HMAC'd under a separate hmac.key. Raw task text and evidence never reach SQLite in plaintext, and weekly exports never include the raw vault.

If you choose to share it

Export is manual and confirmed. /ultra-config report [YYYY-Www] asks for explicit confirmation before writing a joinable analysis bundle; /ultra-config export preview [YYYY-Www] shows you every line first.

Review the preview before sharing a bundle — do not treat the sanitizer as sufficient. Tool arguments and output, provider payloads, and reasoning are dropped at collection and again at export. Exact task text and source code are not written to the analytics log at all. But the redaction of free text is pattern-based and therefore porous: it misses paths that are quoted rather than space-separated, several common secret shapes (AKIA…, sk_live_…, opaque Bearer tokens, *_SECRET_KEY= assignments), PGP key blocks, and connection strings outside postgres/mysql/mongodb/redis. The bundle's config.json is written verbatim, so a project overlay that sets scopePaths, excludePaths, or a pinned acceptance command puts those strings — absolute paths included — into the bundle even though the manifest reports pathsIncluded: false.

Treat a bundle as something you read before you send, not as something certified safe by construction.

/ultra-config trace <run-id> raw and raw-live are local diagnostic views, not shareable telemetry — they can display raw task detail in your terminal. Use them in a trusted local session and never paste their output into an issue, chat, or screenshot.

See Privacy before inspecting or exporting anything.

---

How routing works

UltraPi analyses task scope, uncertainty, risk, coupling, independent work units, context pressure, and verification availability, then chooses or validates a bounded topology:

Topology	Best for	Execution model
direct	Known, small, low-risk work	Root agent works alone.
scout	Unclear code paths or investigation	Read-only scouts collect evidence; the root synthesizes it.
swarm	Independent analysis plus one bounded implementation	Scouts investigate in parallel, then one scoped writer implements, sequentially, in an isolated worktree.
deep	High-risk, coupled, repeated-failure, or complex work	One higher-capability scoped writer works in an isolated worktree.
warroom	Live cross-agent disagreement or deliberate multi-perspective review	Up to three read-only members use a typed blackboard, then a writer synthesizes. Off for automatic selection by default.

/ultra may ask the root agent to propose a topology in automatic mode; the controller can safely override an unsafe proposal. Direct calls to ultra_dispatch must always name one explicit topology — auto is not accepted there.

---

Two things the names might promise that UltraPi will not do

swarm is parallel reconnaissance and a single writer. Several agents read the code at once, each through a different lens, and their findings are merged. Then exactly one agent writes. There is no configuration that gives you N agents editing the same task concurrently, and that is a design decision rather than an unfinished feature.

The reason is verification. UltraPi's claim is not that agents produced code; it is that the code that came back passed a declared acceptance command. That check runs against one isolated worktree. Two writers produce three artifacts — branch A, branch B, and the combination — and only the combination is what you would actually ship. Nothing verifies the combination, so a fleet of parallel writers buys throughput by giving up the one guarantee the tool exists to make. The failure mode is well known from multi-agent demos: parallelism raises the odds that some worker dies quietly, and the reviewers are workers too, so the branch that goes unreviewed is exactly the one nobody notices. UltraPi would rather be slower and able to tell you the result was checked. The repository does contain the mechanism for the one case that could be honest — separate worktrees with disjoint scopes, handed back unmerged for you to review and integrate yourself — but nothing dispatches it, so treat parallel writing as absent rather than optional.

warroom is off by default. warRoom.autoEnabled is false, so automatic routing never picks it; a live cross-agent dependency escalates to deep instead. You get a war room by asking for it — /ultra-config mode warroom, or an explicit mode: "warroom" dispatch. An explicit request raises its own round cap from two to three, but the effective limit is the lower of that and warRoom.maxRounds, which defaults to 2; raise maxRounds to 3 if you actually want the third round.

A war room seats three fixed lenses — lead, flow, invariants — and grows on demand: a member that hits something it cannot resolve requests a specialist, up to warRoom.maxSpecialists (default 2). Three is not a limit you raise, because a fourth seat would need a fourth lens; extra perspectives arrive as named specialists with the gap that summoned them. It is off by default because it is the most expensive topology per unit of progress, and the conditions that justify it are ones you usually know about in advance.

---

Configuration

/ultra-config status [--live]              # current mode, policy, budgets, roster
/ultra-config doctor                       # declared models, profile, compatibility pins
/ultra-config config show                  # the active immutable config version
/ultra-config mode <auto|direct|scout|swarm|deep|warroom>
/ultra-config policy <economy|balanced|quality|max>
/ultra-config budget [weekly [daily]|acknowledge]
/ultra-config runs                         # recent runs and their terminal states
/ultra-config stop <run-id>                # end a run
/ultra-config steer <run-id> <message>     # redirect a run in flight
/ultra-config recover [run-id]             # resume after an interrupted session

/ultra-config with no arguments is equivalent to status. To see the complete surface — including playbook, roles, trace, experiment, and export — pass an unrecognized verb such as /ultra-config help, which prints the full usage string.

Configuration versions are immutable and a project may only ever tighten the limits it inherits, never loosen them. See Configuration for the full contract.

---

Documentation

• Architecture — components, lifecycle, worker boundaries, topology details
• Usage — installation, profiles, task workflow, full command reference
• Configuration — modes, policies, budgets, immutable versions, experiments
• Operations — day-to-day operating checklist
• Privacy — data handling, exports, secret boundaries
• Troubleshooting — common runtime failures
• Weekly review and routing regret — telemetry review and conservative config proposals

---

Development

npm install
npm run typecheck
npm test
npm run coverage
npm run verify        # typecheck + instrumented suite + routing benchmark

npm run coverage runs the suite with Node's coverage instrumentation and fails if branch coverage drops below the floor in scripts/coverage.ts. The gate is on branch coverage, not line coverage: the suite runs TypeScript through tsx, which shifts the line numbers Node attributes badly enough that routing.ts reports 22% of lines while 99% of its branches are exercised. Branch counts survive the transform and are the number that says whether a decision was ever taken both ways.

Tests use temporary directories and make no real provider or model calls. npm run benchmark:routing runs the classifier and router over recorded scenarios and fails on a routing or estimated-cost regression against benchmarks/routing-baseline.json; those decisions and cost estimates are produced by this code, offline, and can be regenerated with npm run benchmark:routing:record.

Two telemetry tools ship in the repository but deliberately not in the published package, since they are for developing UltraPi rather than using it:

npm run telemetry:preflight    # verify the event chain is complete before relying on it
npm run telemetry:health       # tallies, warnings, and unpriced-call detection

This repository publishes no measured outcome numbers. UltraPi makes no claim about being cheaper or more reliable than anything else, because no comparison has been run. benchmarks/evaluator-fixture.json contains invented rows that exist only to exercise the scoring code in src/benchmark/evaluator.ts; it declares itself synthetic and the evaluator refuses to present it as anything else. To measure your own, run tasks through UltraPi, collect outcomes with npm run benchmark:collect, pair each taskId with a baseline sample of the same id, and score them with npm run benchmark -- <file>.

Repository and data boundaries

Only extension source, tests, benchmarks, and documentation belong in this repository. Runtime data, logs, credentials, OAuth/MCP configuration, keys, databases, exports, and raw telemetry are ignored by design.

---

License

MIT. The Pi extension ecosystem is predominantly MIT; the host harness @earendil-works/pi-coding-agent is MIT and pi-agents is Apache-2.0, both compatible with this license.

Not affiliated with, endorsed by, or sponsored by earendil-works or the Pi Coding Agent project.