<img src="assets/banner.svg" alt="ultra" height="70">

# ultra

Ultra helps Pi split substantial work into focused sub-agent steps, then combine their results.
Use it for reviews, investigation, research, or a feature whose parts benefit from separate attention.

![ultra demo: one run_workflow call fans out three reviewers, a judge merges them, the overlay shows every agent](assets/demo.gif)

## Start here

Run `/ultra run review` to review current work, or add a target such as `/ultra run review src/`.
Run `/ultra run bug describe the failure` to investigate a bug.
Run `/ultra run feature describe the change` to take a feature from planning through implementation and review.
Run `/ultra run research your question` to gather and synthesize evidence.

Ultra opens a live progress view for saved workflows.
Use it to follow phases and individual agents while work is running.

Run `/ultra` when you want Pi to decide whether to use multi-agent work during later turns.
Run `/ultra exec <request>` to enable that option and send a request immediately.
Nothing runs from `/ultra` alone.
Ultra registers the [Ultra authoring skill](prompts/ultra-authoring/SKILL.md) for workflow design.
`/ultra exec` sends only the user's request; Pi loads workflow-authoring guidance from that skill.

## Workflows

Saved workflows are reusable recipes for coordinating sub-agents.
Ultra includes `review`, `bug`, `feature`, and `research`.
You can also save your own JSON workflow in `~/.pi/agent/workflows/` or, for a trusted project, `.pi/workflows/`.
Use `/ultra run <name> [args]` to run one.

Read [workflow format](prompts/references/spec-format.md) before authoring a workflow.
Project workflows are ignored until Pi trusts that project.
A workflow chooses agents and tools, so only run project workflows you are prepared to trust.

## Optional setup

By default, Ultra is enabled but waits for `/ultra` before offering workflow orchestration to Pi.
Set `ultra.autoEnable` to `true` in `~/.pi/agent/settings.json` if you want it available at every session start.

```json
{
  "ultra": { "autoEnable": true }
}
```

Use `ultra.enabled: false` to turn Ultra off.
`ultra.subagentExtensions` accepts `"all"` (default), `"none"`, or Pi extension sources such as `"~/extensions/research"` and `"npm:@example/pi-research"`.
Relative sources resolve from the session working directory, like Pi\'s `-e` option; bare extension nicknames are not registry lookups.
After rebuilding an update, restart Pi.

[Installation](../../README.md#install)

## Reference

<!-- config:start -->
### Commands

| Command | Purpose |
| --- | --- |
| `/ultra` | Enable ultra, execute workflow instructions, or run a saved workflow. |

### Setting names

| Setting |
| --- |
| `ultra` |

#### Object fields

Paths below describe fields inside their parent settings object, not literal top-level keys.
`[]` denotes an array element; see setup above for examples and defaults.

| Field |
| --- |
| `ultra.enabled` |
| `ultra.autoEnable` |
| `ultra.concurrency` |
| `ultra.maxRetries` |
| `ultra.subagentExtensions` |
| `ultra.fanoutToolAllowlist` |
| `ultra.subagentSkills` |
| `ultra.subagentSessionRetention` |
| `ultra.modelTiers` |
| `ultra.providerModelTiers` |
| `ultra.actionSummarizerModel` |
<!-- config:end -->

[Changelog](./CHANGELOG.md).