milanglacier/pi-multi-agent-skill / skills/multi-agent
multi-agent
VerifiedStart other pi agents and delegate work to them. Use it when a task benefits from a multi-agent workflow, such as splitting work across agents, running it in parallel or in the background, or keeping a side task out of your own context.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.3 KB |
| profiles/Explore.md | markdown | 1.8 KB |
| profiles/general-purpose.md | markdown | 134 B |
| references/commands.md | markdown | 9.1 KB |
| references/lifecycle.md | markdown | 4.6 KB |
| references/profiles.md | markdown | 3.1 KB |
| references/state.md | markdown | 2.6 KB |
| references/troubleshooting.md | markdown | 3.2 KB |
| references/usage.md | markdown | 1.7 KB |
| scripts/multi_agent.pyexecutable | script | 71.5 KB |
| scripts/usage.pyexecutable | script | 40.9 KB |
references/lifecycle.md
View on GitHub# Job lifecycle
A job is a named agent and its conversation. `run` creates the job and starts
its first run; each `resume` starts another run in the same conversation. A
job has at most one run at a time, and its status describes the latest run.
## Statuses
| Status | Meaning | Result text |
|---|---|---|
| `running` | The agent is working. | — |
| `done` | The agent finished its turn. | Its final message. |
| `failed` | The run could not finish; see below. | The agent's last message, if any, then an `error:` line. |
| `aborted` | `abort` stopped the agent, or something else aborted its turn. | Its last message. |
| `timeout` | The run reached its `--timeout`. | Its last message. |
| `killed` | `kill`, a signal to the job's runner, or the end of a foreground command stopped the run. | Its last message. |
| `died` | The job's runner ended without recording a result, for example after a SIGKILL. | None; the result reads `(no output)`. |
A run ends as `failed` when the model returns an error after pi's own retries,
pi rejects the prompt, pi cannot start, or pi exits during the run. In the
last case the result holds the end of pi's stderr. A model or tool name that
pi rejects is a common cause.
"Last message" is the text of the agent's latest message in this run. It is
empty when that message had only tool calls, or when the run stopped before
the agent wrote anything; the result then reads `(no output)`. A message cut
short by an abort keeps the text written before it.
A prompt that pi handles by itself without starting the agent, such as an
extension command, ends the run at once as `done` with no output.
## How a run stops
- **The agent finishes.** The status is `done`, or `failed` if its last
message was an error.
- **`abort`.** Steering messages that the agent has not read are discarded and
pi is asked to abort the current turn. The agent gets 30 seconds to wind
down; after that the run is stopped anyway. The status is `aborted`.
- **Timeout.** The limit counts from the start of the run. When it is
reached, the run is aborted as above and ends as `timeout`.
- **`kill`, a signal, or the end of a foreground command.** The run stops at
once without the 30-second wind-down. The status is `killed`.
In every case pi is shut down cleanly: it gets 10 seconds to exit, then
SIGTERM, then SIGKILL 5 seconds later. A run that hits its timeout can
therefore take up to 45 seconds to end. `steer` and `abort` fail with `job is
not running; use resume` as soon as the run has started to end.
## Foreground and background runs
Every run is driven by its own runner process, detached from the caller's
terminal and process group.
- A foreground run is tied to the command that started it. Whatever ends that
command, SIGKILL included, stops the agent and the commands it was running.
On SIGINT, SIGTERM or SIGHUP the command waits for the run to stop and
prints its result; a second signal ends it at once. A foreground run started
by another agent is tied to that agent's command in the same way, so a chain
of foreground runs stops together.
- A background run keeps going after its caller ends, until it finishes,
reaches its timeout, or is stopped with `kill`.
- If a runner is killed with SIGKILL, its job's status becomes `died` at once.
The agent's pi process usually exits within a second, but commands the agent
was running may keep running.
## Timeouts
A timeout applies to one run. `run` and `resume` default to 3600 seconds in
the background and to no limit in the foreground; `--timeout 0` removes the
limit, and fractional seconds are allowed. A timeout does not carry over to
the next run.
## Dialogs and approvals
No person watches an agent. When an extension inside the agent opens a dialog
(select, confirm, input or editor), it is cancelled at once and logged in the
progress log as `denied:`. Extensions that have a non-interactive mode run in
it (see `state.md`), so tool calls that need a person fail without opening a
dialog. The agent is told not to retry them and to report what it could not
do in its final message.
## Nesting
An agent can start agents of its own. `PI_MULTI_AGENT_DEPTH` counts the depth:
0 or unset for the user's agent, 1 for an agent it started, and so on. `run` and
`resume` refuse to start when the caller's depth is at least
`PI_MULTI_AGENT_MAX_DEPTH` (default 2), so by default the user's agent and its
agents can delegate, and their agents cannot. Agents inherit
`PI_MULTI_AGENT_MAX_DEPTH` from the environment of the user's agent.
`PI_MULTI_AGENT_JOB` holds the job directory of the agent that is running.
`status` and `list` use it to show the job that started each job.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |