{"id":50644686,"url":"https://github.com/averycrespi/agent-config","last_synced_at":"2026-07-18T22:33:00.146Z","repository":{"id":305240093,"uuid":"1022342066","full_name":"averycrespi/agent-config","owner":"averycrespi","description":"My configuration for working with AI coding agents","archived":false,"fork":false,"pushed_at":"2026-07-09T17:01:31.000Z","size":3278,"stargazers_count":4,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-09T19:05:20.984Z","etag":null,"topics":["claude-code","pi-agent"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/averycrespi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-07-18T22:05:54.000Z","updated_at":"2026-07-09T17:01:51.000Z","dependencies_parsed_at":"2026-01-08T01:02:37.765Z","dependency_job_id":"7f22090a-1ea2-453f-9b90-b5613e87ea96","html_url":"https://github.com/averycrespi/agent-config","commit_stats":null,"previous_names":["averycrespi/claudefiles","averycrespi/agent-config"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/averycrespi/agent-config","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/averycrespi%2Fagent-config","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/averycrespi%2Fagent-config/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/averycrespi%2Fagent-config/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/averycrespi%2Fagent-config/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/averycrespi","download_url":"https://codeload.github.com/averycrespi/agent-config/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/averycrespi%2Fagent-config/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35633896,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-18T02:00:07.223Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude-code","pi-agent"],"created_at":"2026-06-07T11:30:37.598Z","updated_at":"2026-07-18T22:33:00.140Z","avatar_url":"https://github.com/averycrespi.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Agent Config\n\nA 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.\n\nThe active focus of this repository is [Pi](https://pi.dev/) under [`pi/agent/`](pi/README.md). The older [Claude Code](https://www.anthropic.com/claude-code) setup remains in [`claude/`](claude/README.md) as legacy/reference material.\n\nThis repo pairs well with my [agent-tools](https://github.com/averycrespi/agent-tools), especially the MCP broker for safe external tool access.\n\n## What This Repo Is\n\nThis is my personal agent operating system for software work. It combines:\n\n- **A Pi-native workflow layer** for planning, executing, independently reviewing, and completing engineering tasks\n- **Custom TypeScript extensions** that add durable goals, TODO tracking, subagents, prechecked scheduled tasks, brokered external tools, web access, and TUI polish\n- **Reusable skills** for planning, plan visualization, diagnosis, TDD, review, browser automation, frontend design, Jira ticket creation, memory workflows, and agent-harness engineering\n- **Subagent definitions** for isolated exploration, scouting, research, review, and analysis\n- **Extension development conventions** with shared helpers, colocated tests, and deterministic checks\n\nThe 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.\n\n## Pi Agent Harness\n\n[`pi/agent/`](pi/README.md) is the main artifact in this repository. Running `make stow-pi` symlinks it into `~/.pi/agent/`.\n\n### Core Workflow\n\nThe Pi setup is built around a durable development loop:\n\n- **Clarify scope** with `clarify` when requirements, edge cases, acceptance criteria, or design intent are fuzzy\n- **Plan the work** with `plan`, then stress-test substantial plans with `challenge-plan` before execution\n- **Execute deliberately** with session-scoped goals via `goal`, optional fail-closed independent completion review, and in-session task tracking via `todo`\n- **Delegate read-only research** to focused subagents for exploration, scouting, deeper research, review, and analysis\n- **Review independently** with `review` for diffs, branches, plans, documents, and other coherent units of work\n\nSupporting rails keep the loop safer and more inspectable:\n\n- **Route authenticated external access** through `mcp-broker` instead of exposing credentials directly to the agent\n- **Use direct web access** through `web-access` for public search and page fetching\n- **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\n\nThis turns Pi from a chat interface with tools into a more structured development harness.\n\n### Extensions\n\nThe Pi extensions are directory-based TypeScript modules under [`pi/agent/extensions/`](pi/agent/extensions/). They are grouped around the capabilities I want the agent to have:\n\n- **Workflow state:** `goal`, `todo`, `scheduled-tasks`\n- **Delegation and orchestration:** `subagents`, `workflows`, `structured-output`\n- **External access:** `mcp-broker`, `web-access`\n- **Agent/user interaction:** `ask-user`\n- **Context and TUI polish:** `context-usage`, `extra-context`, `compact-tools`, `startup-header`, `statusline`\n- **Shared infrastructure:** `_shared` helpers for rendering, config, logging, and common extension behavior\n\nSee the [Pi README](pi/README.md#extensions) for the full extension table.\n\n### Skills and Subagents\n\nThe Pi skill set lives in [`pi/agent/skills/`](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.\n\nSubagents live in [`pi/agent/agents/`](pi/agent/agents/) and are loaded dynamically by the `subagents` extension. They provide isolated read-only workers for:\n\n- focused repository exploration\n- lightweight scouting\n- deeper multi-source research\n- holistic review of diffs, plans, and branches\n- signal analysis for logs, traces, metrics, and large outputs\n\nThe [`workflows`](pi/agent/extensions/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.\n\n### Extension Development\n\nPi extension work is treated like real software, not just config:\n\n- TypeScript source lives beside extension docs and tests\n- shared helpers live under [`pi/agent/extensions/_shared/`](pi/agent/extensions/_shared/)\n- meaningful logic has colocated `*.test.ts` coverage\n- `README.md` documents user-facing behavior\n- `DESIGN.md` documents architecture and maintenance invariants for non-trivial extensions\n- `API.md` / `api.ts` define reusable public surfaces when an extension exposes code to other extensions\n\nUseful development commands:\n\n```sh\nmake install-dev      # install Node dependencies and Husky git hooks\nnpm run lint          # lint Pi extension TypeScript files\nnpm run format:check  # check formatting for TS/JS/JSON/Markdown/YAML files\nmake typecheck        # type-check Pi extension TypeScript files\nmake test             # run Pi extension unit tests\n```\n\n## Companion: agent-tools\n\n[`agent-tools`](https://github.com/averycrespi/agent-tools) provides external utilities that complement this configuration repo.\n\nThe 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`](pi/agent/extensions/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.\n\n`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.\n\n## Legacy Claude Code Configuration\n\n[`claude/`](claude/README.md) contains my earlier Claude Code setup. It is retained for reference and compatibility, but new harness development in this repo is focused on Pi.\n\nThe Claude setup includes:\n\n- structured workflow skills adapted from earlier agent workflow experiments\n- security and quality hooks, including secret scanning and format-on-write behavior\n- sandbox-mode overrides for headless or remote environments\n- a custom status line\n\nSome 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.\n\n## Notes\n\n[`notes/`](notes/) contains public essays and working notes about agent harness design, permissions, subagents, planning workflows, and related topics.\n\n## Quick Start\n\n### Requirements\n\n- [Pi agent](https://pi.dev/)\n- [Homebrew](https://brew.sh/)\n- [Node.js](https://nodejs.org/) 24+\n- macOS assumed, adaptable for Linux\n\nClaude Code is only required if you want to use the legacy `claude/` configuration.\n\n### Pi Setup\n\n```sh\ngit clone git@github.com:averycrespi/agent-config.git\ncd agent-config\nbrew bundle             # install system dependencies on macOS\nmake install-dev        # install Node dependencies and Husky git hooks\nmake install-playwright # for the playwright skill\nmake stow-pi            # symlink pi/agent/ into ~/.pi/agent/\n```\n\n### Legacy Claude Setup\n\n```sh\nmake stow-claude         # symlink claude/ into ~/.claude/\nmake stow-claude-sandbox # stow claude/ and apply sandbox overrides\n```\n\n## License\n\n- Repository licensed under [MIT](./LICENSE)\n- Individual components may have their own licenses\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faverycrespi%2Fagent-config","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faverycrespi%2Fagent-config","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faverycrespi%2Fagent-config/lists"}