Skip to content

SETUP.md

Latest commit

 

History

History
140 lines (102 loc) · 4.74 KB

SETUP.md

File metadata and controls

140 lines (102 loc) · 4.74 KB
Raw

SETUP.md — the full one-shot install procedure

This is the authoritative runbook the fresh pi agent executes when the user says "set it up." A human can also follow it top to bottom. macOS-first; Linux notes inline.

0. Preflight

pi --version        # must exist. If not: npm install -g @earendil-works/pi-coding-agent
node --version      # need v20+
git --version

If pi is missing, install it and re-open pi inside this repo before continuing.

1. One command

From the repo root:

chmod +x install.sh scripts/*.sh doctor.sh
./install.sh

Flags:

  • ./install.sh --core-only — skip the ~/pi-orchestration/ swarm tier (config + skills only).
  • ./install.sh --with-patches — also apply the optional, version-fragile package patches (see scripts/apply-patches.sh; not recommended for a first run).

What install.sh does (all backed up, timestamped .bak-*)

Step Source → target
Extensions pi/extensions/ → ~/.pi/agent/extensions/ (+ npm install in tools/)
Prompts pi/agents/ → ~/.pi/agent/agents/
Themes pi/themes/ → ~/.pi/agent/themes/ (gruvbox active)
Config pi/*.json + pi/AGENTS.md → ~/.pi/agent/
Skills config-skills/ → ~/.config/agents/skills/ (17 skills)
Packages 11 pi packages via pi install (pi also auto-installs from settings.json on launch)
Orchestration orchestration/ → ~/pi-orchestration/; symlinks codex-run, lucifer-codex, lucifer-watch → ~/.local/bin

Ensure ~/.local/bin is on PATH (installer warns if not):

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

2. Log in (interactive — the user does this)

The agent CANNOT do OAuth. Instruct the user to open pi and run:

pi
/login anthropic            # Claude Max — opens a browser OAuth flow
/login openai-codex         # Codex Max — opens a browser OAuth flow
/model anthropic/claude-opus-4-8

Both providers bill the subscriptions (status bar shows (sub)), not metered API keys. No API key is required for the core stack.

Optional providers (only if the user has keys — otherwise ignore, they no-op): DEEPSEEK_API_KEY, NVIDIA_API_KEY, CROF_API_KEY; local models via /local start.

3. Verify

./doctor.sh

Green = installed. It checks: pi/node/git, all target dirs, extension count, skills count, settings validity, orchestration bin + PATH, and login status hints. Fix anything red that doesn't need credentials (re-run a copy, chmod +x, npm install). Login-dependent lines stay "pending" until step 2 is done — that's expected.

4. First-run smoke test

pi                                  # launch
# in pi:
/model anthropic/claude-opus-4-8
# type:  list the files in this directory

If it responds and tools work, the core stack is live. Try the power features:

  • @oracle, @finder, @codereview, @task — sub-agent mentions
  • Ctrl+Shift+P — command palette
  • /todos, /btw, /session-breakdown, /route status, /conserve status
  • 📊 footer — dual-subscription usage (Claude + Codex)

5. Orchestration (advanced tier — optional)

The Overstory swarm needs the ov CLI (a separate global install) — see ~/pi-orchestration/RUNBOOK.md. The solo stack (including codex-run / lucifer-codex for one-shot Codex work) is fully functional without it.

codex-run "print hello from codex"     # one-shot Codex Max (needs /login openai-codex done)
lucifer-codex                          # interactive session on Codex Max
lucifer-watch                          # swarm dashboard (once ov is set up)

To enable the optional intake router later:

cp ~/pi-orchestration/.secrets.env.example ~/pi-orchestration/.secrets.env
# add a classifier key, then edit ENDPOINT/model in ~/.pi/agent/extensions/lucifer-router.ts

Troubleshooting

Symptom Fix
pi: command not found npm install -g @earendil-works/pi-coding-agent
Startup warns "No models match …" that model's provider needs a key; safe to ignore or remove it from enabledModels in ~/.pi/agent/settings.json
tools don't load (cd ~/.pi/agent/extensions/tools && npm install) then restart pi
codex-run: command not found ~/.local/bin not on PATH — add it (step 1) and restart the shell
a package patch broke something restore the .bak-* file the patch left next to the target
want to undo everything restore the timestamped ~/.pi/agent*.bak-* backups the installer made

Rollback

install.sh never deletes without a backup. To revert, restore the newest .bak-* copies:

ls -d ~/.pi/agent*.bak-* ~/.config/agents/skills.bak-* ~/pi-orchestration.bak-* 2>/dev/null