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.

Setting up on a new machine

1. Clone into ~/.pi/agent.
2. Install mise, Node 22.23.1, and Bun 1.3.14. Pi uses the npmCommand in settings.json to run npm through that exact Node release. The root development lockfile uses npm 10.9.8.
3. Install Pi 0.80.7. On first startup, Pi reads the exact package sources from settings.json and installs missing packages into its managed, gitignored npm/ directory. Exact versioned sources are pinned and skipped by pi update --extensions; change their versions in settings.json and restart Pi when upgrading. Do not edit or commit files under npm/.
4. For extension and skill development, run npm ci --ignore-scripts at the repository root. This installs only the tracked development and validation tooling from the root package.json and package-lock.json.
5. Create auth.json if needed (gitignored) or use pi's login flow for the openai-codex provider.
6. Start pi.

extensions/mcp-cache-bootstrap/ is auto-discovered as a directory extension and creates an empty private mcp-cache.json only when the file is absent. This preserves lazy first-start behavior without overwriting cached metadata. See extensions/mcp-cache-bootstrap/README.md.

Pi 0.80.7 discovers project settings only as .pi/settings.json in the current project directory. Interactive startup asks before trusting protected project settings, resources, or project .agents/skills; after trust, Pi may install missing packages configured by project settings. --approve and --no-approve override project trust for one pi config or package command. pi update never prompts for project trust.

For the end-to-end project workflow - initializing a project wiki, priming the agent on a codebase, driving large tasks with /pantheon --plan / --goal, and the everyday keybindings - read the walkthrough.

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	Durable global operating rules and code-style guidance	yes
APPEND_SYSTEM.md	Generated runtime system-prompt rules maintained by vstack extensions (e.g. pi-questions, pi-background-tasks)	yes
themes/catppuccin.json	Custom Catppuccin theme selected by settings.json	yes
extensions/pantheon/pantheon-policy.md	The /pantheon orchestrator policy loaded by the pantheon extension	yes
agents/*.md	The Pantheon specialist agents (see below)	yes
prompts/*.md	Prompt templates invoked with /name (e.g. /onboard-project)	yes
skills/	Installed skills	yes
extensions/	Custom extensions (source only)	yes
package.json, package-lock.json	Development, test, typecheck, and lint tooling for tracked code	yes
scripts/	Repository-owned validation helpers	yes
npm/	Pi-managed package installation recreated from settings.json	no (gitignored)
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)
mcp-oauth/, mcp-onboarding.json	Machine-local MCP authorization and onboarding state	no (gitignored)

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

APPEND_SYSTEM.md owns generated runtime rules, AGENTS.md owns durable agent policy, and this README owns descriptive setup guidance. Do not move policy between these layers.

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 command (extensions/pantheon/pantheon-policy.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 file, shell, patch, process, MCP, persistence, and orchestration mutation tools; only the fixer keeps those capabilities. All five deny nested delegation, keeping the call graph flat (you -> specialist). Because future parent tools are inherited by default, new mutating tools must be added to the advisor deny-lists before activation.
• Trust boundary - Pi 0.80.7 project trust controls whether project settings, packages, and extensions load. It is not a universal per-tool approval sandbox. Advisor write restrictions come from the denied tool set; only an external OS sandbox can constrain arbitrary process access.

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

Pi auto-discovers extensions/*/index.ts without a parent extensions/package.json manifest. Individual extension directories may still keep their own package manifests for local scripts or standalone package metadata.

• extensions/pantheon/ - the /pantheon orchestration command. It loads the bundled policy (pantheon-policy.md) as a user turn so your root session acts as the Pantheon orchestrator. --plan writes PLAN.md and opens the plannotator browser review; denied feedback is incorporated before execution. If plannotator is absent at invocation, Pantheon warns and runs without the gate. --goal[=N] runs the orchestration as a supervised goal loop. The Pantheon prompt directs each attempt to obtain an oracle judgment and end with goal_verdict; failed reasons drive later attempts. Has smoke + prompt tests (bun test in that directory).
• extensions/goal/ - a generic "Ralph loop": /goal <task> runs a task, accepts a structured goal_verdict, and feeds failed reasons into later attempts up to a configurable 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. One missing-verdict reminder is followed by a pause if no verdict is emitted; default no-progress handling stops after two identical failure reasons. The task string is opaque, so /goal /pantheon <task> loops 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.
• extensions/copy-code/ - owned fork of penumbral-labs/pi-copy-code that copies fenced code blocks from assistant messages to the clipboard. Adds /copy-code (and /copy-code edit) plus alt+shift+c. Two differences from upstream: the message cap is unlimited by default so you can page back through the whole session (override with PI_COPY_CODE_MESSAGE_CAP), and the picker is a native titled overlay with a scrollable message-context pane, syntax-highlighted block previews (ctrl+u/ctrl+d to scroll a long block), and a key-hint footer. See extensions/copy-code/README.md.

Packages

Pi-managed packages are declared as exact sources in settings.json. Pi installs missing configured sources on startup. Exact versioned npm sources are intentionally skipped by pi update --extensions; package upgrades are deliberate settings.json changes followed by a Pi restart and validation. The ignored npm/ installation is generated state, and repository changes must never depend on hand-editing it.

The root package.json is separate and contains only development tooling for the code tracked in this repository. Its Pi type packages are pinned to 0.80.7 so tests and type checking match the host runtime.

• pi-hide-providers, pi-mcp-adapter - provider narrowing and the MCP adapter.
• chrome-devtools-mcp 1.6.0 - declared in settings.json as a dependency-only Pi-managed package. mcp.json runs it from ~/.pi/agent/npm/ with npm exec --offline, so it does not fetch a floating package at startup.
• pi-lens - background code intelligence: LSP diagnostics, structural search (ast-grep), and automatic formatting/lint-fixing (Biome, Ruff, ESLint) plus a test-on-write runner. Mostly invisible; toggle pieces with --no-lens, --no-lsp, --no-autoformat, --no-autofix, --no-tests.
• @plannotator/pi-extension - browser-based plan review, used by /pantheon --plan.
• @upstash/context7-pi - Context7 documentation lookups.
• @zosmaai/pi-llm-wiki - persistent LLM wiki and cross-session memory (see LLM Wiki).
• The vstack suite (@vanillagreen/*, all in the vstack monorepo): 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.

LLM Wiki

Persistent cross-session memory via @zosmaai/pi-llm-wiki: an always-on personal vault at ~/.llm-wiki/ plus optional per-project vaults at <project>/.llm-wiki/. Recall searches both, so decisions and findings compound instead of being re-derived each session. Chat notices are silenced with the top-level "llm-wiki": { "notices": false } block in settings.json.

See docs/llm-wiki.md for the full workflow: personal vs company mode, when to add a project wiki, what to commit versus gitignore in a multi-user repo, and maintenance guidance.

Verifying the setup

Repository validation runs from the repository root:

npm test
npm run typecheck
npm run lint
npm run validate

npm test runs all custom extension tests plus the Codemap helper tests with the required Bun 1.3.14 runtime. npm run typecheck uses the repository TypeScript and matching Bun types, while npm run lint uses the pinned Biome binary.

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 <task>                  # orchestrate the pantheon over a task (see docs/walkthrough.md)

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: "..." }).