Installation & Setup¶

Requirements¶

pi installed and on your PATH
bash or zsh
git (for cloning and the pi-mono reference submodule)

Install¶

# Clone the repo (anywhere you like)
git clone git@github.com:PlebeiusGaragicus/dot-pi.git ~/dot-pi
cd ~/dot-pi

# Initialize the pi-mono reference submodule (optional, for reading upstream source)
git submodule update --init

The repo can live at any path -- bash_aliases auto-detects its own location at source time.

API Keys¶

Copy the example env file and fill in your keys:

cp example.env .env

Edit .env with your API key(s). The file is gitignored and sourced automatically by bash_aliases:

export PLEBCHAT_API_KEY=your-key-here

Shell setup¶

Add this line to your ~/.zshrc or ~/.bashrc, using the actual path to where you cloned the repo:

source ~/dot-pi/bash_aliases

Then reload your shell:

source ~/.zshrc  # or source ~/.bashrc

This gives you the p command for each team and standalone agent (p <name>).

DOT_PI_DIR is auto-detected from the script's location, so the repo can live anywhere. If you need to override it for some reason, set DOT_PI_DIR before sourcing:

export DOT_PI_DIR="/custom/path"
source /custom/path/bash_aliases

Verify¶

Check that your teams are set up and extensions are linked:

cd ~/dot-pi
./setup.sh list

You should see each team with its agent/prompt counts and extension link status, followed by any standalone agents.

Test a team:

cd /any/project
p recon "What does this project do?"

The Setup Script¶

setup.sh manages team and standalone agent directories. It handles scaffolding, listing, and auth sharing.

`./setup.sh create <team-name>`¶

Creates a new team directory at teams/<team-name>/ with the following structure:

teams/<team-name>/
├── extensions/
│   ├── subagent-teams -> ../../../shared/extensions/subagent-teams
│   ├── run-finish-notify -> ../../../shared/extensions/run-finish-notify
│   └── startup-branding -> ../../../shared/extensions/startup-branding
├── agents/              (empty -- add your agent .md files here)
├── prompts/             (empty -- add prompt templates here)
├── team-prompt.md       (orchestrator config + system prompt, see Architecture)
├── banner.txt           (startup branding -- generated by figlet, edit to customize)
├── skills/              (empty — add with ./setup.sh link-skill <team-name> <skill>)
├── themes/              (individual themes symlinked from shared)
│   └── synthwave.json -> ../../../shared/themes/synthwave.json
├── bin -> ../../shared/bin  (shared binaries -- fd, rg downloaded on first run)
├── sessions/            (runtime session storage, gitignored)
├── settings.json        (theme + quietStartup defaults, gitignored)
├── pi-args              (optional default CLI flags; keep trailing IMPORTANT comment line)
└── models.json -> ../../shared/models.json

The extensions/, models.json, and bin/ are symlinks to shared/. skills/ starts empty — use ./setup.sh link-skill to add shared skills. Themes are symlinked individually. The bin/ symlink means pi downloads fd and rg once into shared/bin/ and all teams share them. settings.json is scaffolded with default theme and quiet startup preferences. Agents and prompts are per-team. Subagents can further restrict skills via frontmatter (skills, no-skills).

Key files:

team-prompt.md -- The subagent-teams extension parses its YAML frontmatter for orchestrator configuration (name, description, tools, model) and appends the body to the orchestrator's system prompt. Use the tools field to restrict the orchestrator (e.g. tools: read,find,ls,grep to force subagent delegation).
workspace.conf -- If present, p launches in workspace mode: creates a dated directory, pre-creates subdirectories listed in the file, and runs pi inside it.

Example:

./setup.sh create docs-team

After creating a team, you need to:

Add agents -- create .md files in teams/<team-name>/agents/ with YAML frontmatter (name, description, optionally tools, skills, no-skills, model, team) and a system prompt body.
Add prompts (optional) -- create .md files in teams/<team-name>/prompts/ that define chain/parallel workflows using $@ as the user input placeholder.
Re-source -- re-source bash_aliases in your shell so p picks up the new team (e.g. p docs-team).

`./setup.sh create-agent <agent-name>`¶

Creates a standalone agent directory at agents/<agent-name>/ with a stub extension and shared symlinks:

agents/<agent-name>/
├── extensions/
│   ├── <agent-name>/
│   │   └── index.ts         (stub -- your custom extension)
│   ├── run-finish-notify -> ../../../shared/extensions/run-finish-notify
│   ├── startup-branding -> ../../../shared/extensions/startup-branding
│   └── say -> ../../../shared/extensions/say
├── skills/              (empty — add with ./setup.sh link-skill <agent-name> <skill>)
├── themes/              (individual themes symlinked from shared)
├── banner.txt           (startup branding -- generated by figlet, edit to customize)
├── bin -> ../../shared/bin
├── sessions/            (runtime, gitignored)
├── settings.json        (theme + quietStartup defaults, gitignored)
├── pi-args              (optional default CLI flags; keep trailing IMPORTANT comment line)
├── SYSTEM.md            (starter system prompt — edit to customize; no AGENT.md scaffold)
└── models.json -> ../../shared/models.json

Unlike teams, standalone agents do not get the subagent-teams extension or an agents/ subdirectory. The main pi process IS the agent. Default scaffolds include SYSTEM.md, symlink say.ts (TTS/say) plus run-finish and startup branding, and do not create AGENT.md (add it yourself and symlink agent-prompt.ts if you want YAML frontmatter; see Standalone Agents). bash_aliases wires each agent into p <name>.

Example:

./setup.sh create-agent my-agent
source ~/dot-pi/bash_aliases
p my-agent "hello"

See Standalone Agents for details on writing the extension.

`./setup.sh list`¶

Shows all teams and standalone agents with their counts and status:

./setup.sh list

If extensions linked shows no for any team, the symlinks are broken -- re-run create or manually fix them.

`./setup.sh link-skill <team-or-agent> <skill> [<skill> ...]`¶

Symlink one or more directories from shared/skills/ into a team or standalone agent's skills/ folder (created if missing). Example:

./setup.sh link-skill docs-team searxng
./setup.sh link-skill my-agent playwright tavily

`./setup.sh link-auth <source> <destination>`¶

Each team has its own PI_CODING_AGENT_DIR, which means separate auth.json files. After authenticating pi through one team, share that auth with others:

# Authenticate via recon (pi prompts for API key on first run)
p recon "hello"

# Share that auth.json with other teams
./setup.sh link-auth recon impl
./setup.sh link-auth recon blog

The <source> can be a team name, a standalone agent name, or a direct file path. The destination can be any team or agent name.

This creates a symlink so all linked teams use the same credentials, and re-authenticating in any one of them updates all of them.