Agent Layout¶
Every directory under agents/<name>/ is a complete PI_CODING_AGENT_DIR root. Agent commands set that environment variable, read the selected root, and launch pi in the user's current working directory.
Top-Level Layout¶
agents/example/
├── README.md
├── USAGE.md
├── SYSTEM.md
├── APPEND_SYSTEM.md
├── pi-args
├── banner.txt
├── bootstrap.sh
├── auth.json -> ../../shared/auth.json
├── models.json -> ../../shared/models.json
├── settings.json -> ../../shared/settings.json
├── bin -> $DOT_PI_OVERLAY/<agent>/bin -> ~/.pi/agent/bin
├── extensions/
├── prompts/
├── skills/
├── themes/
└── agents/ # MAS only
Most agents use only a subset of these files.
Root Files¶
README.md is human-facing design prose. USAGE.md is launcher help printed by agent help, agent usage, -h, or --help.
SYSTEM.md replaces Pi's system prompt. APPEND_SYSTEM.md appends to Pi's default system prompt.
pi-args contains default CLI flags, one per line. Omit --model so pi uses settings.json (pi updates the default when the user changes the model). Add --model provider/id only when an agent must pin a model.
bootstrap.sh, when present, is an in-situ launch hook. It is sourced before pi starts and receives DOT_PI_DIR, DOT_PI_OVERLAY, AGENT_NAME, AGENT_DIR, DOTPI_BOOTSTRAP_PHASE, and BOOTSTRAP_LOG. Workspace mode has been removed; WORKSPACE_AGENT and WORKSPACE_DIR are not part of the supported runtime contract.
Shared Config Links¶
agents/<name>/auth.json -> ../../shared/auth.json -> $DOT_PI_OVERLAY/auth.json -> ~/.pi/agent/auth.json
agents/<name>/models.json -> ../../shared/models.json -> $DOT_PI_OVERLAY/models.json -> ~/.pi/agent/models.json
agents/<name>/settings.json -> ../../shared/settings.json -> $DOT_PI_OVERLAY/settings.json
auth.json and models.json intentionally resolve through the overlay to Pi-standard files so dot-pi agents and vanilla pi share credentials and provider catalogs. settings.json is shared among dot-pi agents through the overlay and must not inherit the vanilla ~/.pi/agent/settings.json package registration.
Install and relink scripts may create $DOT_PI_OVERLAY/settings.json if it is missing, but must never overwrite an existing one.
Resource Directories¶
extensions/, prompts/, skills/, and themes/ define what Pi discovers for this agent. Shipped resources are tracked in the package clone, often as symlinks into shared/.
User-owned additions live under:
$DOT_PI_OVERLAY/<agent>/extensions/
$DOT_PI_OVERLAY/<agent>/prompts/
$DOT_PI_OVERLAY/<agent>/skills/
$DOT_PI_OVERLAY/<agent>/themes/
postinstall and dotpi relink wire overlay entries into the clone with symlinks. They repair clone-local links after pi update without mutating overlay targets.
Sessions¶
Session files do not live in the package clone. Dispatch passes:
agent ls lists sessions for the current working directory.
MAS Subagents¶
MAS roots use top-level-agent-orchestrator: workers are separate top-level agents/<worker>/ configs, not a nested agents/<mas>/agents/ tree maintained by postinstall.
Repo-Level Files¶
core/bin/<agent> symlinks are repaired by package postinstall and dotpi relink.
Agent-root bin links are repaired to $DOT_PI_OVERLAY/<agent>/bin, and that overlay link points at vanilla Pi's ~/.pi/agent/bin. This lets dot-pi agents share downloaded binaries such as fd and rg with bare pi.
env.exa / env.tavily / env.ntfy API files, env.tts-wpm, and optional env.ssh live only under the overlay. Durable user state must not rely on the Pi-managed package tree.