My personal configuration and extension toolkit for the Pi coding agent.
It combines reusable development skills with custom tools for delegation, automation, external services, and terminal UI improvements. Use it for direct coding work, research and independent review, or optional Plane-backed ticket delivery.
This is a configuration repository, not a standalone agent. Pi is installed separately; GNU Stow links the configuration into ~/.pi/agent/. Model settings and integration credentials remain local.
| Component | Purpose | Location |
|---|---|---|
| Agent instructions | Shared rules for task execution, verification, Git, and communication | AGENTS.md |
| Skills | On-demand guidance for clarification, debugging, review, ticket delivery, and other activities | skills/ |
| Extensions | TypeScript tools and UI enhancements for delegation, automation, external access, context visibility, and work tracking | extensions/ |
| Saved workflows | Reusable JavaScript orchestration for independent review and deep research | workflows/ |
| Prompt templates | Slash-invoked prompts, including secret scanning | prompts/ |
| Themes | Terminal appearance, including Catppuccin Mocha | themes/ |
See pi/README.md for the full catalog. These components are installed from pi/agent/; repository-local authoring guidance and development tooling stay in this checkout.
- Pi agent, installed separately, with a configured model provider
- Node.js 24+;
.tool-versionspins the version used by CI (currently 25.9.0). Use the pinned version for Code mode's required permission support. - 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 [email protected]: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, Herdr, and authenticated external services need additional setup; see Optional integrations.
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. 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 authorized work in the main session. Use
diagnosewhen a failure's cause is uncertain, and keep checks proportionate to the change. - Review changes with
review, combining repository context, deterministic checks, and independent analysis. Report failed checks and verification gaps rather than implying success.
For Plane-backed work, shape-ticket prepares a verifiable ticket contract, and work-ticket owns one selected ticket through the authorized delivery boundary. The plane skill supplies safe gateway access.
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 the full delivery and recovery procedures.
| Mechanism | Use it for |
|---|---|
| Subagents | Isolated questions where parallelism, context isolation, or independent judgment outweighs delegation overhead. Each child receives a self-contained prompt, explicit capabilities, and a configured profile. |
| Workflows | Repeatable research or review coordinated by deterministic JavaScript, with bounded subagents and verification gates. Saved definitions include review and deep-research; workflow subagents cannot receive writable filesystem or shell capabilities. |
| Spin-out | Explicitly requested delegation to a fresh Pi agent in a Herdr-managed worktree, with a durable local task brief. |
The main session owns implementation and execution evidence by default. Writable delegation requires an explicit user request and the bounded execution safeguards; parent and child writes must never overlap in one checkout.
| Mechanism | Use it for |
|---|---|
| Loop | Continuing the current agent session within turn and time limits when explicitly requested by the user, a loaded skill, or an established workflow. Ordinary multi-step work does not need a loop. |
| Monitor | Explicitly requested checks of gateway conditions without recurring model turns while waiting, followed by a notification when attention is needed. |
| Scheduled tasks | Recurring Markdown-defined tasks run through cron, or on demand, in fresh child Pi processes with retained run artifacts and optional cross-run handoffs. |
Loop continues reasoning; Monitor checks conditions; scheduled tasks start separate runs. Monitor is session-bound, not a durable background service: shutdown, reload, or session/branch navigation stops observations without automatic resumption. Neither Loop nor Monitor decides whether the overall task succeeded; the calling user, skill, or workflow defines completion.
Code mode runs one bounded JavaScript program to paginate, join, or aggregate MCP Gateway results before returning compact data to the model. It coordinates tool calls, not agents, and does not provide persistent polling.
Use direct mcp_search, mcp_describe, and mcp_call tools for straightforward discovery and calls. Use Code mode when intermediate results would otherwise inflate context. Gateway permissions do not replace user authorization for external mutations.
Run make install-playwright to install browser tooling and Chromium for the pinned web-access dependency. Without it, web-access still supports static extraction and hosted fallbacks. See web-access and the Playwright skill.
Install Herdr, then run herdr integration install pi after Stow. Restart Pi or run /reload to load its lifecycle bridge.
The herdr and spin-out skills use Herdr for terminal and worktree control. Herdr owns the local Pi lifecycle bridge; this repository's ask-user extension reports interactive questions through it. See Herdr integration for component ownership and remote-client setup, including macOS-to-Lima use.
The companion agent-tools repository provides the MCP Gateway used by this configuration's mcp-gateway extension.
Configure a separate gateway endpoint and supply MCP_GATEWAY_AGENT_TOKEN in 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.
The companion also includes a sandbox manager (sb) for isolated agent runs. Gateway permissions govern external service access; this 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; shared helpers live under pi/agent/extensions/_shared/.
See repository authoring guidance for safeguards and required checks, and the repo-local create-extension skill for extension conventions. That skill stays under .pi/skills/ and is not installed globally by Stow.
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