Agent Config

A Pi-first coding-agent harness: configuration, TypeScript extensions, skills, subagents, and workflow conventions for turning a general-purpose coding agent into a reliable software engineering partner.

The active focus of this repository is Pi under pi/agent/. The older Claude Code setup remains in claude/ as legacy/reference material.

This repo pairs well with my agent-tools, especially the MCP broker for safe external tool access.

What This Repo Is

This is my personal agent operating system for software work. It combines:

• A Pi-native workflow layer for planning, executing, independently reviewing, and completing engineering tasks
• Custom TypeScript extensions that add durable goals, TODO tracking, subagents, prechecked scheduled tasks, brokered external tools, web access, and TUI polish
• Reusable skills for planning, plan visualization, diagnosis, TDD, review, browser automation, frontend design, Jira ticket creation, memory workflows, and agent-harness engineering
• Subagent definitions for isolated exploration, scouting, research, review, and analysis
• Extension development conventions with shared helpers, colocated tests, and deterministic checks

The goal is not just to store settings. The goal is to make the agent more stateful, safer, more inspectable, and better at real development workflows.

Pi Agent Harness

pi/agent/ is the main artifact in this repository. Running make stow-pi symlinks it into ~/.pi/agent/.

Core Workflow

The Pi setup is built around a durable development loop:

• Clarify scope with clarify when requirements, edge cases, acceptance criteria, or design intent are fuzzy
• Plan the work with plan, then stress-test substantial plans with challenge-plan before execution
• Execute deliberately with session-scoped goals via goal, optional fail-closed independent completion review, and in-session task tracking via todo
• Delegate read-only research to focused subagents for exploration, scouting, deeper research, review, and analysis
• Review independently with review for diffs, branches, plans, documents, and other coherent units of work

Supporting rails keep the loop safer and more inspectable:

• Route authenticated external access through mcp-broker instead of exposing credentials directly to the agent
• Use direct web access through web-access for public search and page fetching
• Orchestrate multi-agent checks with inline or reusable named user-scoped workflow definitions that support discovery and validation, then fan out read-mostly subagents under host-enforced concurrency and run budgets, structured verification/report gates, and fixed model-tier routing

This turns Pi from a chat interface with tools into a more structured development harness.

Extensions

The Pi extensions are directory-based TypeScript modules under pi/agent/extensions/. They are grouped around the capabilities I want the agent to have:

• Workflow state: goal, todo, scheduled-tasks
• Delegation and orchestration: subagents, workflows, structured-output
• External access: mcp-broker, web-access
• Agent/user interaction: ask-user
• Context and TUI polish: context-usage, extra-context, compact-tools, startup-header, statusline
• Shared infrastructure: _shared helpers for rendering, config, logging, and common extension behavior

See the Pi README for the full extension table.

Skills and Subagents

The Pi skill set lives in pi/agent/skills/ and is written for Pi's tool surface and GPT-5.x-style instruction following. It includes workflow skills for clarifying requirements, planning, visualizing plans as HTML artifacts, reviewing, diagnosing failures, building frontend UI, using Playwright, creating skills, and working with retained memory.

Subagents live in pi/agent/agents/ and are loaded dynamically by the subagents extension. They provide isolated read-only workers for:

• focused repository exploration
• lightweight scouting
• deeper multi-source research
• holistic review of diffs, plans, and branches
• signal analysis for logs, traces, metrics, and large outputs

The workflows extension adds compound listing, validation, and foreground JavaScript execution for inline or reusable named user-scoped definitions, including bounded host-enforced concurrency and run budgets, structured verification/report gates, fixed host-resolved model tiers, and compact progress.

Extension Development

Pi extension work is treated like real software, not just config:

• TypeScript source lives beside extension docs and tests
• shared helpers live under pi/agent/extensions/_shared/
• meaningful logic has colocated *.test.ts coverage
• README.md documents user-facing behavior
• DESIGN.md documents architecture and maintenance invariants for non-trivial extensions
• API.md / api.ts define reusable public surfaces when an extension exposes code to other extensions

Useful development commands:

make install-dev      # install Node dependencies and Husky git hooks
npm run lint          # lint Pi extension TypeScript files
npm run format:check  # check formatting for TS/JS/JSON/Markdown/YAML files
make typecheck        # type-check Pi extension TypeScript files
make test             # run Pi extension unit tests

Companion: agent-tools

agent-tools provides external utilities that complement this configuration repo.

The main integration point is the MCP broker: a credentials-holding proxy that lets sandboxed agents use authenticated external services without holding secrets directly. In Pi, the mcp-broker extension exposes broker-backed tools through mcp_search, mcp_describe, and mcp_call, and guards direct gh or remote-git usage when broker tools are preferred.

agent-tools also includes a sandbox manager (sb) for isolated agent runs. It is relevant to Pi as an outer isolation layer: this Pi config adds workflow guidance and broker preferences, but it does not implement shell command restrictions itself.

Legacy Claude Code Configuration

claude/ contains my earlier Claude Code setup. It is retained for reference and compatibility, but new harness development in this repo is focused on Pi.

The Claude setup includes:

• structured workflow skills adapted from earlier agent workflow experiments
• security and quality hooks, including secret scanning and format-on-write behavior
• sandbox-mode overrides for headless or remote environments
• a custom status line

Some skills and workflow ideas originated there and were later adapted into Pi-specific versions with Pi tool names, Pi extension conventions, and GPT-5.x-friendly prose.

Notes

notes/ contains public essays and working notes about agent harness design, permissions, subagents, planning workflows, and related topics.

Quick Start

Requirements

• Pi agent
• Homebrew
• Node.js 24+
• macOS assumed, adaptable for Linux

Claude Code is only required if you want to use the legacy claude/ configuration.

Pi Setup

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 install-playwright # for the playwright skill
make stow-pi            # symlink pi/agent/ into ~/.pi/agent/

Legacy Claude Setup

make stow-claude         # symlink claude/ into ~/.claude/
make stow-claude-sandbox # stow claude/ and apply sandbox overrides

License

• Repository licensed under MIT
• Individual components may have their own licenses