Rendered preview

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.

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 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 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.

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

Reference

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

Changelog.

<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).