Pi Subagents Guide

OpenCode is the canonical control plane for this repo.

This guide describes the secondary Pi-native integration. It follows the same local workflow:

• no hosted Autolab backend
• no Gastown assets or terminology
• local promoted master in train_orig.py, research/live/master.json, and research/results.tsv
• managed benchmark runs through Hugging Face Jobs
• observability through Trackio

Checked-In Pi Assets

• .pi/settings.json Project Pi settings. It declares the pi-subagents package and keeps Pi session files under .runtime/.
• .pi/APPEND_SYSTEM.md Parent-session Autolab coordinator guidance appended to Pi's default prompt.
• .pi/agents/ Project agents: planner, reviewer, researcher, reporter, memory-keeper, and experiment-worker.
• .pi/prompts/autolab.md A reusable /autolab parent-session kickoff prompt.
• scripts/print_pi_kickoff.py Prints a standard parent-session prompt.
• scripts/pi_worker.py Creates isolated worktrees and launches experiment-worker through Pi.

Setup

Install Pi once if it is not already available:

npm install -g @mariozechner/pi-coding-agent

From the pre-training project root, start Pi:

pi

The project .pi/settings.json declares npm:pi-subagents@0.22.0. Pi should install missing project packages on startup. If you prefer to install the package explicitly, run:

pi install npm:pi-subagents@0.22.0 -l

Authenticate a provider with /login, or start Pi with the provider API key in the environment.

Parent Session

Refresh current benchmark truth before planning:

uv run scripts/refresh_master.py --fetch-dag

Print a kickoff prompt if you want a copy-paste skeleton:

uv run scripts/print_pi_kickoff.py --gpu-slots 1

Start Pi in the pre-training project root and run the project prompt template:

/autolab "recent-master: follow-ups" 1 3

The parent session should use:

• planner for fresh queues
• reviewer for rule and comparability checks
• researcher for paper-derived ideas
• reporter for HF Jobs and Trackio status
• memory-keeper for durable markdown updates in the main checkout
• experiment-worker only from reserved experiment worktrees

Useful Pi Commands

/run planner "Propose up to 3 fresh single-change experiments for the current campaign."
/run reviewer "Review this planned experiment for stale-master, duplicate, and multi-change risk."
/parallel reporter "Summarize active HF Jobs and Trackio anomalies." -> reviewer "Check whether the next launch is comparable."
/run memory-keeper "Record this completed worker summary in the durable notebook."

pi-subagents also scans legacy .agents/**/*.md files. In this repo that means the shared .agents/skills/*/SKILL.md files can appear in /agents. Treat the canonical Pi role agents as the files under .pi/agents/.

Pi supports background subagent runs with --bg, but do not exceed real GPU capacity for active experiment workers.

Experiment Worker Flow

Create one explicit worktree reservation per experiment:

uv run scripts/pi_worker.py create exp-warmdown-20 \
  --campaign "schedule: shorter cooldowns" \
  --hypothesis "Shorten warmdown to test whether the long cooldown tail is wasting the fixed budget."

Launch the worker:

uv run scripts/pi_worker.py run exp-warmdown-20

The launcher runs Pi from the reserved worktree, invokes the project experiment-worker agent, and exports:

• AUTOLAB_CAMPAIGN
• AUTOLAB_EXPERIMENT_ID
• AUTOLAB_WORKER_ID
• AUTOLAB_HYPOTHESIS
• AUTOLAB_LOG_PATH
• AUTOLAB_EXPERIMENT_NOTE

Use --dry-run to inspect the exact pi -p command and environment without starting the worker.

When the run is fully recorded by memory-keeper, remove the worktree:

uv run scripts/pi_worker.py cleanup exp-warmdown-20

Worktree Rules

The pi-subagents package has its own worktree option for generic parallel coding tasks. For paid Autolab experiments, prefer scripts/pi_worker.py instead because it reserves the experiment id, worktree, note path, and log path using the same repo-local state as the OpenCode and Hermes launchers.

The parent Pi session stays in the main checkout. Experiment workers run from