pi-agi

Long-horizon orchestrator mode for pi. The main session keeps the goal, plan, and memory; implementation is delegated to isolated workers and independently verified.

Install

pi-agi is a pi extension, not a standalone application. Install pi first:

# Requires Node.js 20 or newer.
npm install -g @earendil-works/pi-coding-agent

# Install the extension through pi.
pi install npm:pi-agi

# Start with AGI mode enabled.
pi --agi

This installs from the public npm registry. No GitHub account or token is required.

You can also start pi normally and enable the extension with /agi.

Do not use npm install -g pi-agi: pi packages must be installed with pi install so pi can register and load the extension. Configure a model provider in pi before using workers.

For local development:

pi -e /absolute/path/to/pi-agi

Use

Toggle with /agi or Ctrl+Alt+G, or start enabled:

pi --agi

Commands:

• /agi — toggle orchestrator mode
• /agi-status — show mode and state-file status
• /agi-goal, /agi-memory — open the goal and memory index
• /agi-workers — open the live worker inspector
• /agi-stop — stop this orchestrator's active workers after confirmation

Tools:

• agi_state — maintain .pi/agi/goal.md, plan.md, memory/journal.md, and named notes
• agi_note — emit one short user-facing progress note per turn (never enters model context)
• agi_control — direct-edit grant, interrupt, stop, stop-all, and same-session resume
• agi_delegate — spawn detached workers for implementation work; returns immediately
• agi_workers — list runs and their states
• agi_worker — inspect one run: status, events, or its final report
• agi_steer — send a durable mid-run instruction with exact acknowledgment
• agi_sleep — end the turn until a worker, tick, user message, or capped timer wakes it

Workers

agi_delegate spawns a detached pi --mode rpc process per task. It returns as soon as the children are launched, so the orchestrator keeps its turn; results are read later with agi_worker.

Each worker is configured by an agent profile — a Markdown file with YAML frontmatter, resolved from .pi/agi/agents/ (project, requires trust), then ~/.pi/agent/agi/agents/ (user), then the four built-ins:

| Profile | Tools | Purpose | | --- | --- | --- | | worker | full | Default implementer. The one that edits code. | | explore | read-only | Fast reconnaissance. Safe to run several in parallel. | | review | read-only | Critique of a diff or plan. | | verify | read-only | Runs tests and builds, reports actual output. |

The built-ins are written to the user directory on first activation and never overwritten, so they are examples you can edit.

Every worker must end with a fixed five-section report (## Outcome, ## Changes, ## Evidence, ## Learned, ## Remaining); a missing section fails the run. If a mutating worker claims work but its working tree has no diff, the run is flagged suspicious.

Concurrency defaults to one mutating worker at a time, because two processes editing the same working tree corrupt it silently — pi's own file-mutation queue is in-process and cannot coordinate across processes. Read-only profiles are exempt and bounded separately, so fanning out several explore workers alongside one implementer works at the default settings. Beyond the limit, delegations queue rather than fail.

Workers cannot delegate: PI_AGI_ROLE=worker means the orchestrator tools are never registered, so the depth cap is structural rather than a counter.

Known limitation on pi 0.83: a detached worker does not outlive its orchestrator. pi --mode rpc shuts down on stdin EOF, and stdin has to stay open so dialogs from inherited extensions can be answered — an unanswered dialog would block the worker forever. When an orchestrator exits, its in-flight runs are reported orphaned on the next start rather than silently lost. Adoption is implemented and takes over the moment pi can be told not to exit on EOF.

While AGI mode is active, the orchestrator retains all inspection capabilities. edit, write, and source-mutating bash commands are withheld by default so implementation work goes to workers. Inspection commands, builds, tests, and linters remain available.

The guard is advisory, not a sandbox: agi_control is model-callable, so the orchestrator can grant itself a direct edit. Every grant is journaled with its reason, and repeated grants surface a suggestion to turn AGI mode off.

Environment

| Variable | Effect | | --- | --- | | PI_AGI_DISABLE=1 | Disable the extension entirely | | PI_AGI_ROLE=worker | Mark the process a worker; no orchestrator tools are registered | | PI_AGI_ROLE=off | Inert, same as disabled | | PI_AGI_PI_BINARY | Path to the pi executable used to spawn workers, when auto-resolution picks the wrong one |

Workers additionally receive PI_AGI_RUN_ID, PI_AGI_TASK_ID, PI_AGI_RUN_DIR, PI_AGI_DEPTH and PI_AGI_MAX_DEPTH. Any other PI_AGI_* variable is stripped from a worker's environment, so a value in the parent shell cannot reach a child.

Development

npm install --ignore-scripts
npm run check
npm test

npm test runs every suite serially, including integration cases that spawn a real pi --mode rpc child against a localhost stub provider — no provider credentials and no paid tokens, but it takes a few minutes. Those cases need a pi checkout: they default to a sibling ../pi directory and honour PI_ROOT.

Design notes and the implementation spec are in docs/agi/.

Live End-to-End Test

The commands below use the pi development checkout and a temporary Git repository. The interactive prompts use your configured provider and may consume API tokens.

Start a clean TUI with only this extension loaded:

rm -rf /tmp/pi-agi-live
mkdir -p /tmp/pi-agi-live
git -C /tmp/pi-agi-live init -q

tmux new-session -s pi-agi-live \
  "/home/nightfury/thinkling/pi/pi-test.sh \
  -ne \
  -e /home/nightfury/thinkling/pi-agi \
  --agi"

Paste this prompt into pi:

Live-test AGI mode end to end.

Create an active goal and plan using agi_state. Delegate an ad-hoc task to the worker profile. The worker must create hello.txt containing exactly:

hello from pi-agi worker

After delegation, call agi_sleep until the worker completes. When woken, verify hello.txt directly from disk and report the result. Do not create the file yourself.

Open the worker inspector while the worker runs:

/agi-workers

Or press Ctrl+Alt+W.

Test exact-ack steering while a worker is running:

Steer the active worker with this exact instruction: also create steered.txt containing exactly "steering delivered". Wait for durable acknowledgment.

Verify the worker output from another terminal:

cat /tmp/pi-agi-live/hello.txt
cat /tmp/pi-agi-live/steered.txt

Test interrupt and same-session resume with a longer task:

Delegate an ad-hoc worker task that performs a short investigation, waits about 20 seconds with a non-interactive command, then creates resumed.txt. Interrupt it after it starts. When it reaches paused, resume it in the same session and ask it to finish.

Test terminal stop:

Stop the active worker because this is a live stop test. Then attempt to resume it and report the result.

Inspect durable run state from another terminal:

for file in /tmp/pi-agi-live/.pi/agi/.runtime/runs/*/status.json; do
  echo "=== $file ==="
  jq '{runId, taskId, state, pid, sessionId, previousRunId, runIndex, steering, error}' "$file"
done

Inspect worker events:

for file in /tmp/pi-agi-live/.pi/agi/.runtime/runs/*/events.jsonl; do
  echo "=== $file ==="
  jq -c . "$file"
done

Inspect durable steering acknowledgments:

find /tmp/pi-agi-live/.pi/agi/.runtime/runs \
  -path '*/control/steer-ack/*.json' \
  -print -exec jq . {} \;

Exit pi with /quit. If the tmux session remains:

tmux kill-session -t pi-agi-live

Requires pi 0.83.0 or newer.