My personal Pi setup for software development: research-first clarification, focused implementation, ticket-driven delivery, and independent review.
The repository contains skills, TypeScript extensions, prompt templates, themes, and saved workflows, installed into ~/.pi/agent/ with GNU Stow.
Custom extensions under pi/agent/extensions/ provide:
- Work tracking and automation: loops, TODOs, and scheduled tasks
- Delegation and orchestration: isolated subagents, saved workflows, and structured output
- External access: gateway-backed services, isolated JavaScript MCP composition, and web research
- Interaction and context: user prompts, context reporting, compact tool output, and TUI status information
See pi/README.md for the complete extension, skill, prompt, and saved-workflow catalog.
- Pi agent, installed separately, with a configured model provider
- Node.js 24+;
.tool-versionspins the version used by CI (currently 25.9.0) - Homebrew for the macOS dependency setup below
- macOS assumed; Linux requires equivalent system dependencies, including GNU Stow
Before running Stow, inspect any existing files in ~/.pi/agent/ and reconcile conflicts; do not overwrite an existing configuration blindly.
git clone git@github.com:averycrespi/agent-config.git
cd agent-config
brew bundle # install system dependencies on macOS
make install-dev # install Node dependencies and Husky git hooks
make stow-pi # symlink pi/agent/ into ~/.pi/agent/Personal pi/agent/settings.json is gitignored, so a fresh clone does not reproduce model/provider selections or local extension settings. Configure these for your environment, then start Pi (or run /reload in an existing session to load the installed extensions and skills).
- Browser automation and local web rendering: run
make install-playwright. This installs browser tooling and Chromium for the pinned web-access dependency; without it, web-access still supports static extraction and hosted fallbacks. See web-access. - Terminal and worktree integration: install Herdr, then run
herdr integration install piafter Stow. Restart Pi or run/reloadto load its lifecycle bridge. See Herdr integration, including macOS-to-Lima remote setup. - Authenticated external services: configure a separate MCP Gateway endpoint and supply
MCP_GATEWAY_AGENT_TOKENin Pi's process environment. Keep tokens out of settings and the repository. Missing gateway configuration leaves Pi usable, but MCP calls require it. See gateway configuration.
Use the activities that fit the request rather than treating every skill as a mandatory phase:
- Clarify material ambiguity with
clarify: research first, ask focused questions, and return a concise brief without creating artifacts. Skip the interview when the request is already clear. - Stress-test concrete approaches with
challengefor material risks or explicit-onlysimplifyfor unnecessary complexity. - Implement and verify directly for authorized local work, or use the ticket workflow for prepared delivery. Keep evidence and checks proportionate to the change.
- Review changes with
review, combining repository context, deterministic checks, and independent analysis while reporting failed checks and verification gaps.
For Plane-backed delivery, plane defines safe gateway access, shape-ticket prepares a verifiable contract, and work-ticket owns one selected ticket through the authorized delivery boundary. Ticket implementation includes in-scope local commits unless excluded; pushing and PR publication require explicit authorization. PR delivery includes independent review before publication and bounded, session-bound CI monitoring and repair afterward. See work-ticket for recovery, allowances, and settlement procedures.
| Primitive | Use it when | What it provides |
|---|---|---|
| Subagents | Parallelism, substantial context isolation, or independent judgment outweighs delegation overhead. | One-shot child sessions with self-contained prompts, explicit capabilities, and configured fast, balanced, or strong profiles. |
| Workflows | Research, review, or audit follows predictable, reusable control flow. | Deterministic JavaScript orchestration with bounded read-mostly subagents, structured output, verification gates, and budgets; no writable filesystem or shell capabilities. |
| Loops | A user, loaded skill, or established workflow explicitly requests bounded continuation of the current session. | A repeated message with continuation/time limits and yield/stop/resume controls—not a completion judgment or background watcher. |
The main session owns implementation and execution evidence; workflows own deterministic orchestration, and subagents handle isolated questions. Writable delegation requires an explicit user request and a bounded execution workflow with one writer, a structured handoff, and independent verification; parent and child writes must never overlap in one checkout. The calling user, skill, or extension defines completion policy for loops.
For explicitly requested worktree-based delegation, spin-out starts a fresh Pi agent in a Herdr-managed worktree with a durable local task brief.
Herdr provides the terminal and worktree control plane used by the herdr and spin-out skills. Herdr owns the local Pi lifecycle bridge; this repository's ask-user extension exposes ask_user and reports interactive questions through that bridge. See Herdr integration for installation, component ownership, and remote-client setup.
agent-tools provides external utilities that complement this configuration repo. Its MCP Gateway governs authenticated external access through Pi's mcp-gateway extension and the mcp_search, mcp_describe, and mcp_call tools.
Code mode composes gateway calls in isolated JavaScript for pagination, dependent lookups, and aggregation, returning only selected results to model context. Use direct MCP tools for simple calls; use code mode when intermediate data would otherwise inflate context.
The companion also includes a sandbox manager (sb) for isolated agent runs. Gateway permissions govern external service access; this Pi configuration's guidance toward gateway tools is advisory, not shell sandbox enforcement. Use an outer isolation layer when shell restrictions are needed.
Extensions are directory-based TypeScript modules with colocated tests and user-facing documentation. Non-trivial extensions also include design guidance, while shared helpers live under pi/agent/extensions/_shared/. See repository authoring guidance for safeguards and required checks.
The repo-local create-extension skill covers creating and modifying extensions, including rendering, configuration, state, documentation, and testing conventions. It stays under .pi/skills/ and is not installed globally by Stow. Pi discovers project-local skills when the project is trusted and skill discovery is enabled; AGENTS.md also provides a direct file path for agents to read without changing trust or reloading the session.
npm run lint # lint extensions and saved workflows
npm run format:check # check formatting
make typecheck # run TypeScript checks
make test # run unit testsGitHub Actions runs these checks for pull requests and pushes to main.
notes/ contains public essays and working notes about agent harness design, permissions, subagents, planning workflows, and related topics.
- Repository licensed under MIT
- Individual components may have their own licenses