pi harness configuration

Version-controlled configuration for the pi coding agent, tuned for personal OpenAI Codex use. This repo is ~/.pi/agent under version control so the setup can be reproduced across machines.

What lives here

Path	Purpose	Tracked
settings.json	Core pi settings: theme, packages, default model, and the vstack extension-manager block	yes
mcp.json	MCP servers: chrome-devtools	yes
hide-providers.json	Narrows the model picker to the personal provider set	yes
AGENTS.md	Global operating rules and code-style guidance	yes
APPEND_SYSTEM.md	System-prompt appendix maintained by the vstack extensions (e.g. pi-questions, pi-background-tasks)	yes
themes/catppuccin.json	Custom Catppuccin theme selected by settings.json	yes
prompts/pantheon.md	The /pantheon prompt template (orchestrator entry point)	yes
agents/*.md	The Pantheon specialist agents (see below)	yes
skills/	Installed skills	yes
extensions/	Custom extensions (source only)	yes
npm/package.json	pi package dependencies	yes
sessions/, vstack/	Session transcripts and per-extension session state	no (gitignored)
auth.json	Credentials	no (gitignored)
*-cache.json, .lcm/, *-stats.json, **/logs/	Machine-local caches, metrics, run artifacts, and runtime logs	no (gitignored)

Anything the harness regenerates or that contains conversation history or credentials is gitignored on purpose. See .gitignore for the full list.

Model stack

The active stack uses the openai-codex provider and the GPT-5.6 family:

• openai-codex/gpt-5.6-sol:high - default orchestrator and highest-stakes advisory model
• openai-codex/gpt-5.6-terra:high - implementation model, chosen for strong DeepSWE performance at lower average cost than Sol
• openai-codex/gpt-5.6-terra:medium - design and compaction tier, used where quality matters but Sol is not needed
• openai-codex/gpt-5.6-luna:medium - low-cost reconnaissance, research, and session naming tier

DeepSWE reports GPT-5.6 Sol at 73% / $8.39 average cost, GPT-5.6 Terra at 70% / $4.95, and GPT-5.6 Luna at 67% / $3.03. The stack keeps Sol for the orchestrator and oracle, shifts most implementation work to Terra, and uses Luna for high-volume utility tasks.

Provider API keys are read from the local auth configuration or environment; they are never stored in this repo.

Subagents: the Pantheon

A self-contained multi-agent workflow running on the @vanillagreen/pi-agents-tmux extension. Your root Pi session is the orchestrator: it plans and delegates via the /pantheon prompt template (prompts/pantheon.md), and five specialist agents execute in isolated background sessions.

The specialists live as flat .md files directly in agents/ (the loader is non-recursive and reads that directory only). They are user scope, so every subagent call passes agentScope: "both"; /pantheon does this for you.

Agent	Role	Model	Writes?
explorer	Fast read-only codebase recon	openai-codex/gpt-5.6-luna:medium	no
oracle	Strategy, review, hard debugging	openai-codex/gpt-5.6-sol:high	no
librarian	External docs/web research (no bash)	openai-codex/gpt-5.6-luna:medium	no
designer	UI/UX specs and structure	openai-codex/gpt-5.6-terra:medium	no
fixer	All implementation	openai-codex/gpt-5.6-terra:high	yes

Security is enforced by tool visibility plus prompts:

• Visibility - each agent's deny-tools: frontmatter is subtracted from the parent session's active tools (pi-agents-tmux inherits-minus-deny, not an allow-list). The four advisors deny write/edit (librarian also bash) so they are read-only; only the fixer writes. All five deny subagent and delegate_subagent, keeping the call graph flat (you -> specialist).
• Approval - Pi's built-in approval flow governs tool calls at runtime.

The model is pinned per agent in each file's model: frontmatter, and reasoning effort is encoded as a :effort suffix on the model id (e.g. gpt-5.6-terra:high) - that suffix is the only thing that reaches the child process, so a separate effort: key would be dead. pi-agents-tmux reads the frontmatter model by default (subagentModelSource: frontmatter, subagentThinkingSource: frontmatter). There are no fallback model chains under this extension.

Only agents with pane: true require running Pi inside tmux; no pantheon agent sets it, so the workflow runs identically in and out of tmux.

Extensions

• extensions/goal/ - a generic "Ralph loop": /goal <task> runs a task, checks a structured goal_verdict, and if the goal is not met feeds the failure reasons back and re-runs - up to a configurable attempt cap (goal block in settings.json, default 5). Each attempt is a real, visible turn, so smart-rate-limit and other turn hooks still apply. The task string is opaque, so /goal /pantheon <task> loops the Pantheon with feedback. Supports /goal status, /goal pause, /goal resume, and /goal clear plus matching goal-* alias commands. Interrupted running loops restore as paused on session start and can be resumed explicitly. Retry and missing-verdict prompts include completion-audit guidance, and skills/goal-writer/ helps draft high-quality /goal objectives. Has unit + adapter tests (bun run test in that directory). See extensions/goal/README.md.
• extensions/smart-rate-limit/ - holds requests when a provider reports an HTTP 429 window, so pi's built-in short-backoff retries do not hammer a limit that will not clear for ~60s. Has unit tests (bun test in that directory).
• extensions/statusline-bridge/ - surfaces status text from other extensions in a compact row beneath pi-qol's statusline, which otherwise hides pi's built-in footer once replaceFooter is enabled. See extensions/statusline-bridge/README.md.
• extensions/cache-stats/ - tracks prompt-cache effectiveness across the session (cached vs total input tokens, and the token hit rate) from each turn's usage block, and publishes a compact cache 90k/120k tok (75%) segment into the statusline-bridge row (right-aligned). On startup/reload/resume it recomputes the totals from the session transcript (ctx.sessionManager.getEntries()) in a single linear pass, so the numbers survive a /reload or restart without a separate store. Adds /cache-stats. Has unit tests (bun test in that directory). See extensions/cache-stats/README.md.

Packages

Installed via npm/package.json and enabled in settings.json packages:

• pi-hide-providers, pi-mcp-adapter - provider narrowing and the MCP adapter.
• @upstash/context7-pi - Context7 documentation lookups.
• The vstack suite (@vanillagreen/*): pi-extension-manager, pi-tool-renderer, pi-session-manager, pi-skills-manager, pi-questions, pi-qol, pi-background-tasks, pi-caveman, pi-task-panel, pi-prompt-stash, pi-codex-minimal-tools, pi-web-tools, and pi-agents-tmux. These provide the extension manager, richer tool/mutation rendering, session and skill management, the structured question tool, quality-of-life UI (compact statusline/footer, session auto-rename, compact prompt), background task control, the caveman-lite response style, the persistent task panel (tasks_write), reusable prompt stashing, the Codex minimal-tools and web-tools sets, and the agent/subagent runtime (the Pantheon). Their shared configuration lives in the vstack block of settings.json.

The theme is a custom Catppuccin (themes/catppuccin.json), selected by "theme": "catppuccin" in settings.json.

Setting up on a new machine

1. Clone into ~/.pi/agent.
2. Install packages: cd npm && npm install.
3. Create auth.json if needed (gitignored) or use pi's login flow for the openai-codex provider.
4. Start pi.

Verifying the setup

These run inside a pi session (they are provided by pi-agents-tmux, not the pi CLI):

/agents both                      # browse the pantheon agents and their traces
/agents show explorer both        # inspect one agent's resolved config and prompt
/pantheon                         # expand the orchestration prompt template

Delegate a task from your root session with the subagent tool (always pass agentScope: "both" for the user-scope pantheon agents), e.g. subagent({ agentScope: "both", agent: "explorer", task: "..." }).