# Usage

## Prerequisites

Use Node.js 24+, Pi Coding Agent `0.84.1`, and the dependency versions locked in this repository.

If you installed UltraPi as a Pi package (`pi install npm:ultrapi` or `git:`), skip this section — the published package contains no test or script directory, so the commands below do not exist there. Go straight to [Install profiles](#install-profiles).

From a git checkout, install dependencies and verify before wiring it into a profile:

```sh
npm install
npm run verify
```

UltraPi is a Pi extension. It must be loaded by Pi; running `npm test` alone does not install or launch it.

## Install profiles

Run the installer from the repository root:

```sh
node --import tsx src/install.ts
```

For scripts or CI-like setup, provide every required option:

```sh
node --import tsx src/install.ts \
  --weekly-credit-budget 20 \
  --daily-credit-budget 5 \
  --per-task-policy balanced
```

The installer creates two isolated Pi directories and launchers:

| Launcher | Profile | Intended use |
| --- | --- | --- |
| `~/.local/bin/pi-private` | `private` | Default profile, restricted to the private model roster. |
| `~/.local/bin/pi-free` | `free` | Explicit free-model profile; it refuses to start if a compatible roster is not configured. |

They intentionally do not share authentication state. Complete any login through each profile's normal Pi workflow. Do not copy, commit, or inspect auth/OAuth files to make a profile work.

## Start a task

Launch Pi with the profile you intend to use, open the target repository, then submit one bounded task:

```text
/ultra Add coverage for the parser regression and fix the proven root cause. Acceptance: npm test
```

The task text can include paths and an acceptance command. For change/fix requests UltraPi also tries to infer a safe repository check when the project is trusted. An explicit command is better because it gives the controller a concrete completion condition.

Good requests name the desired outcome, scope, and verification:

```text
/ultra Investigate src/router.ts, fix the null route regression, and verify with npm test
/ultra Review the retry logic in src/provider/ for duplicate writes; do not edit files
/ultra Compare the two cache implementations and recommend the safer one
```

Avoid using UltraPi for an unbounded request such as “rewrite the app” or “make everything faster.” Split it into a bounded objective with a measurable acceptance check.

## Task modes

The normal interface is `/ultra <task>`. Its configured mode is `auto` by default, but the root must propose an explicit topology for the controller to validate. You can force a mode for the next runs:

```text
/ultra-config mode direct
/ultra Fix the narrow formatter bug. Acceptance: npm test
/ultra-config mode auto
```

The controller may override a forced lower topology when a hard-risk or repeated-failure gate requires `deep`. It may also downgrade a broad swarm when context pressure is too high.

Choose a mode only when you understand the trade-off:

| Mode | Use when | Cost/latency |
| --- | --- | --- |
| `direct` | The scope and solution path are already known. | Lowest. |
| `scout` | You need read-only evidence before deciding. | Small evidence-gathering cost. |
| `swarm` | Work has independent analysis dimensions and one bounded write phase. | More cost, parallel research. |
| `deep` | The task is coupled, high risk, or has repeatedly failed. | Higher-capability writer. |
| `warroom` | A limited adversarial/multi-perspective review is worth the coordination. | Highest coordination cost. |

## Commands

`/ultra-config` is the operational interface. With no arguments it is equivalent to `status`.

| Command | Purpose |
| --- | --- |
| `/ultra-config status` | Show active runs, health, selected profile, and estimated spend. |
| `/ultra-config doctor` | Check profile marker, models, compatibility pins, MCP presence, storage, and budgets. |
| `/ultra-config mode <auto|direct|scout|swarm|deep|warroom>` | Save the requested routing mode as a new config version. |
| `/ultra-config policy <economy|balanced|quality|max>` | Save the per-task policy. |
| `/ultra-config budget [weekly [daily]]` | Show or save credit caps. |
| `/ultra-config budget acknowledge` | Explicitly acknowledge a one-task automatic run without setting caps. |
| `/ultra-config runs` | List active and recent controller runs. |
| `/ultra-config stop <run-id>` | Stop a run and its delegated work. |
| `/ultra-config steer <run-id> <message>` | Queue a bounded steering message for a live delegated worker. |
| `/ultra-config recover [run-id]` | List recoverable runs or recover one. |
| `/ultra-config trace <run-id> [raw|live|raw-live]` | Show stored local trace or enable a live trace. |
| `/ultra-config trace next raw-live` | Arm a raw live trace for the next run. |
| `/ultra-config trace off` | Disable live trace notifications. |
| `/ultra-config feedback <good|fixed|bad> [comment]` | Record outcome feedback for later review. |
| `/ultra-config export preview [YYYY-Www]` | Render the sanitized weekly export before writing it. |
| `/ultra-config export week [YYYY-Www]` | Create a confirmed sanitized weekly export. |
| `/ultra-config report [YYYY-Www]` | Create a confirmed sanitized analysis report. |
| `/ultra-config config show` | Display the active runtime configuration. |
| `/ultra-config config rollback <version>` | Point the champion at an existing immutable version. |
| `/ultra-config recommendation accept|reject <json-file> [id]` | Review a recommendation and optionally create a challenger. |
| `/ultra-config experiment list` | List experiments. |
| `/ultra-config experiment start <id> <challenger-version>` | Start one reviewed challenger experiment. |
| `/ultra-config experiment stop <id>` | Stop an experiment. |
| `/ultra-config experiment promote <id>` | Promote a running challenger and mark it complete. |

`raw` and `raw-live` trace modes can expose local task or tool details in the current UI. Use them only in a trusted local session; they are never appropriate for screenshots, bug reports, or commits.

## `ultra_dispatch` tool contract

`ultra_dispatch` is for the root Pi agent, not usually for a human to type. It requires a bounded request and one explicit topology:

| Field | Required | Meaning |
| --- | --- | --- |
| `objective` | Yes | Bounded task description, maximum 12,000 characters. |
| `mode` | Yes | `direct`, `scout`, `swarm`, `deep`, or `warroom`; `auto` is rejected. |
| `policy` | No | Per-run `economy`, `balanced`, `quality`, or `max` override. |
| `paths` | No | Up to 32 declared paths to focus the scope. |
| `acceptanceCommand` | No | Executable completion check. Unsupported or unsafe shell syntax is blocked. |
| `privacyClass` | No | `public`, `internal`, `restricted`, or `secret` telemetry treatment. |

The tool returns the run ID, final topology, status, reason codes, and accepted scout facts where available. A tool call does not bypass controller policy, budgets, profile checks, or verification.

## Verification

An acceptance command is authoritative only when it is safe to execute through the guarded argv executor. It intentionally rejects shell composition and potentially dangerous syntax. Typical accepted examples include:

```text
npm test
npm run typecheck
npm run verify
git diff
rg pattern src
node --test tests/unit/example.test.ts
```

If the command is blocked, simplify it into one allowlisted command rather than wrapping it in a shell pipeline. The controller records a blocked/failed outcome instead of retrying unsafe execution.

## A safe daily loop

1. Start `pi-private` or `pi-free` deliberately.
2. Run `/ultra-config doctor` after upgrades or profile changes.
3. Set an explicit budget and policy.
4. Submit one bounded `/ultra` task with an acceptance command.
5. Review `/ultra-config status`; stop or steer a run only with a concrete reason.
6. Use `export preview` before creating a weekly export.
7. Review recommendations and experiments manually; do not treat metrics as an automatic change request.

For operational failure modes, see [Troubleshooting](./TROUBLESHOOTING.md). For profile and export boundaries, see [Privacy](./PRIVACY.md).