pi-agent-toolkit

My personal, versioned setup for the Pi coding agent, with extensions, skills, configs, safety guardrails, and tracked package installs. Package source lives in separate repositories. This is a public backup and reference for how I organize my own agent environment, not a universal starter kit intended to be cloned unchanged by everyone.

Includes 20 extensions, 61 skills, 1 prompt template, 1 theme, 8 tracked Pi packages, MCP server configurations, and safety guardrails. It also tracks 2 custom sub-agent roles for local use with the installed pi-subagents package.

Quick start

For users (copy mode)

Clone and run:

git clone https://github.com/danchamorro/pi-agent-toolkit.git
cd pi-agent-toolkit
node setup.mjs

This copies everything into the right Pi and Claude Code directories. Template configs (auth.json, mcp.json) are created only if they don't already exist.

For full functionality on a new machine, review the prerequisites in dotfiles/SETUP.md. Some helper tools, including opensrc for dependency source lookups, Tirith for local terminal security, and RTK for shell-output token savings, are documented there rather than installed by this repo.

Skip external skills or packages if you don't want them:

npm run setup -- --skip-external --skip-packages

For development (link mode)

Symlink files so edits in the repo are immediately visible to Pi:

npm run link

Re-run any time to pick up new files or clean dangling symlinks. Template configs with secrets are never symlinked.

Day to day personal skill workflow:

Create or edit a skill under dotfiles/personal-skills/<category>/<skill>/.
Run npm run dev:sync.
Reload Pi or Claude Code if the running agent does not pick up new skills automatically.

dev:sync uses link mode and skips external skills and Pi package refreshes.

Bringing outside work into the repo

Prefer repo-first development. Create toolkit resources under dotfiles/, then run npm run dev:sync so the live Pi copy is a symlink. Develop published packages in their standalone repositories under /Users/danielchamorro/Documents/Personal/Code/. If you prototype directly in Pi-owned directories, absorb the unmanaged files back into the repo:

node setup.mjs sync

sync scans live Pi directories and maps accepted files back to repo-owned paths:

Live path	Repo path after sync
`~/.pi/agent/extensions/`	`dotfiles/extensions/`
`~/.pi/agent/skills/`	`dotfiles/agent-skills/`
`~/.pi/agent/agents/`	`dotfiles/agents/`
`~/.pi/agent/prompts/`	`dotfiles/prompts/`
`~/.pi/agent/themes/`	`dotfiles/themes/`

It ignores existing symlinks and manifest-listed external skills, prompts for each unmanaged item, moves accepted files into dotfiles/, and replaces the live file with a symlink. Use --all to skip the interactive prompts.

sync does not scan ~/.agents/skills/ or ~/.claude/skills/. For cross-agent personal skills, manually move or copy the skill to dotfiles/personal-skills/<category>/<skill>/, then run npm run dev:sync.

For third-party work installed with npx skills add or pi install, track it in manifest.json instead of committing the generated installed files.

Full usage

npm run setup                     Copy mode (for users / new machines)
npm run link                      Symlink mode (for development)
npm run dev:sync                  Link repo files, skip external skills and packages
npm run update:third-party        Reinstall external skills and Pi packages
npm run update:skills             Reinstall external skills only
npm run update:packages           Reinstall Pi packages only

node setup.mjs                    Copy mode (for users / new machines)
node setup.mjs --link             Symlink mode (for development)
node setup.mjs sync               Absorb local Pi files into the repo
node setup.mjs sync --all         Absorb all without prompting
node setup.mjs --help             Show help

Flags (copy and link modes):
  --skip-external                 Skip installing external skills
  --skip-packages                 Skip installing Pi packages

Updating third-party skills and packages

Re-run the manifest-driven installers periodically to pull the latest third-party marketplace skills and Pi packages:

npm run update:third-party

Use the narrower commands when you only want one category:

npm run update:skills     # External skills from manifest.json
npm run update:packages   # Pi packages from manifest.json

What's in this repo

Tracked Pi packages

This repository contains no Pi package source. Setup installs eight packages from npm or Git repositories listed in manifest.json:

pi install npm:pi-subagents
pi install npm:@danchamorro/pi-agent-modes
pi install npm:@danchamorro/pi-prompt-enhancer
pi install npm:@juicesharp/rpiv-todo
pi install npm:@juicesharp/rpiv-ask-user-question
pi install npm:pi-web-access
pi install git:https://github.com/badlogic/pi-diff-review
pi install git:github.com/DietrichGebert/ponytail

Standalone packages maintained separately:

Package	Description	npm
subagents	Run focused Pi sub-agents in-process or through Herdr, plus explicit native Claude Code and Codex children, with bundled roles and main-session feedback handoff
agent-modes	Switch between code, architect, debug, ask, and review modes with enforced tool restrictions, bash allowlists, and per-mode model assignment
prompt-enhancer	Rewrite prompts to be clearer and more actionable before sending

@danchamorro/pi-subagents remains published for existing users but is no longer installed by this setup.

Other packages installed by setup:

Package	Description	Source
`pi-subagents`	Delegate work through single, parallel, chained, background, and forked-context Pi sub-agents. Bundles the `pi-subagents` orchestration skill.	nicobailon/pi-subagents
`@juicesharp/rpiv-todo`	Live todo panel for Pi with dependency tracking and task state that survives `/reload` and compaction.	juicesharp/rpiv-mono
`@juicesharp/rpiv-ask-user-question`	Structured questionnaire for clarifying decisions with typed options, previews, notes, and free-text answers.	juicesharp/rpiv-mono
`pi-web-access`	Web search, content extraction, GitHub repository access, PDF extraction, and video understanding.	nicobailon/pi-web-access
`pi-diff-review`	Native diff review window for Pi. Adds a `/diff-review` command that opens changed files in a Monaco diff editor and turns review notes into a prompt back in Pi.	badlogic/pi-diff-review
`ponytail`	Lazy senior developer mode for Pi. Adds `/ponytail` controls, prompt injection, and simplification-focused skills.	DietrichGebert/ponytail

Extensions (20)

All extensions live in dotfiles/extensions/.

Safety and workflow:

Extension	What it does
`damage-control/`	Safety guardrail engine: blocks destructive commands, enforces path access rules, prevents accidental deletes
`commit-approval.ts`	Intercepts git commits for interactive review before execution
`pr-approval.ts`	Intercepts PR creation for interactive review
`dirty-repo-guard.ts`	Warns when working in a repo with uncommitted changes
`require-session-name-on-exit.ts`	Prompts for a session name before `/quit`, `/q`, `/safe-quit`, or Ctrl+Shift+Q exits

Search, tools, and experimental providers:

Extension	What it does
`file-search/`	Registers `fd` and `rg` as first-class file-name and exact-text search tools
`tools.ts`	Custom tool registrations

UI and session management:

Extension	What it does
`btw.ts`	Overlay chat panel with scroll support
`control.ts`	Session control and summarization
`loop.ts`	Loop execution with breakout conditions
`context.ts`	TUI showing loaded extensions, skills, token usage
`coach.ts`	Recommends underused Pi workflows based on session habits
`review.ts`	Code review: PR review, branch diffs, uncommitted changes
`session-breakdown.ts`	Session cost/usage analytics with calendar heatmap
`find-session.ts`	Search past Pi sessions with LLM ranking and one-step resume
`term-notify.ts`	Desktop notifications on agent completion (cmux + OSC 777)
`question-mode.ts`	Read-only question mode (no file changes)
`clean-sessions.ts`	Prunes old, low-value session files
`uv.ts`	Intercepts pip/python calls and redirects to uv

Terminal integration:

Extension	What it does
`warp-split-fork.ts`	Forks the current Pi session into Warp via `/warp-tab-fork` (new tab) or `/warp-pane-fork` (new pane, macOS experimental)

Skills

This repo distinguishes several skill types so each one has one clear owner and install path:

Personal skills are user-authored skills committed to this repo under dotfiles/personal-skills/<category>/<skill>/. They install to ~/.agents/skills/<category>/<skill> for Pi and flat to ~/.claude/skills/<skill> for Claude Code, because Claude Code does not discover nested skill directories. Repo-managed personal skills are not linked into ~/.pi/agent/skills/.
Pi-only skills live under dotfiles/agent-skills/ and install to ~/.pi/agent/skills/. Use these for Pi-specific workflows that should not be shared with Claude Code.
Project-local skills belong in a project's own agent configuration, not in this personal setup repo.
Third-party skills are listed in manifest.json and installed by npx skills add. They are not committed here and may still be placed by third-party tooling under ~/.agents/skills/ or ~/.pi/agent/skills/.
Package-provided skills ship with installed Pi packages from manifest.json.

Setup refuses to delete non-symlink files or directories in skill install roots. Unmanaged and third-party directories are reported and left in place.

Personal skills (22, committed to this repo):

Category	Skill	Description
`security-environment`	`1password-developer`	1Password SSH agent, Environments, and op CLI workflows
`planning`	`brainstorm`	Interview-driven plan stress-testing
`engineering`	`api-contract-validator`	Validate API clients and integrations against contracts, schemas, SDK types, and documented request/response behavior
`developer-workflow`	`cli-detector`	Discover repo SaaS integrations and identify official provider CLIs for setup, debugging, and automation
`engineering`	`code-structure-cleanup`	Behavior-preserving cleanup after working features have duplicated mechanics or messy structure
`engineering`	`coderabbit-review`	Explicitly run a long-running CodeRabbit CLI review without replacing normal review workflows
`engineering`	`debug-mantra`	Four-step debugging discipline for reproducing, tracing, falsifying, and cross-checking bugs
`developer-workflow`	`gh-issue-creator`	Create GitHub issues via `gh` CLI
`docs-communication`	`google-chat-cards-v2`	Google Chat Cards v2 notifications
`docs-communication`	`management-talk`	Rewrite engineering updates for leadership, Slack, standups, email, and meeting notes
`engineering`	`post-mortem`	Produce engineering root-cause writeups after fixed and validated bugs
`planning`	`plan-reviewer`	Review implementation plans for evidence, trackability, dependencies, risks, and validation before execution
`engineering`	`scrutinize`	Outsider-perspective review of plans, PRs, diffs, and code changes
`engineering`	`subagents`	Route delegation through host-supported mechanisms; in Pi, defer orchestration to the installed `pi-subagents` package
`developer-workflow`	`sql-specialist`	Write, review, explain, and optimize SQL queries, schemas, DDL, ERDs, and execution plans
`docs-communication`	`technical-docs`	Technical documentation standards
`engineering`	`test-author`	Create or update targeted tests using project-native conventions and validation
`engineering`	`thermo-nuclear-code-quality-review`	Strict maintainability review for abstraction quality, giant files, spaghetti-condition growth, and code-judo restructuring
`engineering`	`thermo-nuclear-review`	Comprehensive security and correctness audit of branch changes
`engineering`	`thermos`	Launch both thermo-nuclear review subagents in parallel
`developer-workflow`	`whats-new`	Git changelog generation between branches
`media`	`youtube-video-context`	YouTube transcript, summary, and video context extraction via summarize CLI with Codex and local Whisper fallback

Package-provided skills (7, installed via Pi packages):

Installed automatically when these packages are present in manifest.json.

Skill	Source
`pi-subagents`	`npm:pi-subagents`
`ponytail`	`git:github.com/DietrichGebert/ponytail`
`ponytail-review`	`git:github.com/DietrichGebert/ponytail`
`ponytail-audit`	`git:github.com/DietrichGebert/ponytail`
`ponytail-debt`	`git:github.com/DietrichGebert/ponytail`
`ponytail-gain`	`git:github.com/DietrichGebert/ponytail`
`ponytail-help`	`git:github.com/DietrichGebert/ponytail`

External skills (32, installed from source repos):

Listed in manifest.json and installed automatically by setup.mjs. Not committed to this repo. Maintained by their original authors.

Skill	Source
`docx`, `pdf`, `pptx`, `xlsx`, `frontend-design`, `skill-creator`	anthropics/skills
`find-skills`	vercel-labs/skills
`vercel-composition-patterns`, `deploy-to-vercel`, `vercel-react-best-practices`, `vercel-react-native-skills`, `vercel-react-view-transitions`, `vercel-cli-with-tokens`, `vercel-optimize`, `web-design-guidelines`	vercel-labs/agent-skills
`learn-codebase`, `self-improve`	HazAT/pi-config
`vue-best-practices`	hyf0/vue-skills
`autofix`	coderabbitai/skills
`playwright-cli`	microsoft/playwright-cli
`firecrawl`	firecrawl/cli
`excalidraw-diagram`	coleam00/excalidraw-diagram-skill
`browser`	browser-use/browser-harness
`agent-browser`	vercel-labs/agent-browser
`commit-context`, `commit-history`, `forget`, `handoff`, `recall`, `recap`, `remember`, `session-history`	rohitg00/agentmemory

Custom sub-agent roles (2)

Custom sub-agent roles live in dotfiles/agents/ and are installed to ~/.pi/agent/agents/. These are user-managed role prompts consumed by pi-subagents; they are not bundled into the npm package.

Role	Description
`thermo-nuclear-review-subagent`	Thermo-nuclear branch audit for bugs, breaking changes, security, devex regressions, and feature-flag leaks
`thermo-nuclear-code-quality-review-subagent`	Thermo-nuclear code quality audit for maintainability, structure, 1k-line rule, spaghetti, and code-judo review

Prompt templates (1)

Prompt templates live in dotfiles/prompts/ and are installed to ~/.pi/agent/prompts/ by setup.mjs.

Prompt	Description
`implementation-plan`	Convert an existing plan into actionable, committable checklist phases and write the result to a new Markdown file.

Themes (1)

Themes live in dotfiles/themes/ and are installed to ~/.pi/agent/themes/ by setup.mjs. They are available but not active by default; pick one via /settings or set "theme" in your local ~/.pi/agent/settings.json (outside this repo, so it never affects other users).

Theme	Description
`vscode-dark-modern`	Pi port of VS Code's Dark Modern palette. Pure black base, near-black tool surfaces, VS Code Dark+ syntax colors, and diffs.com-inspired diff colors.

Config files

File	Purpose
`AGENTS.md`	Global agent rules: git safety, commit style, code style, path discipline
`APPEND_SYSTEM.md`	System prompt: reasoning quality, jCodeMunch policies, documentation lookup, writing style
`settings.json`	Pi settings: default provider/model, enabled models, compaction. Live-only at `~/.pi/agent/`; mutated by Pi at runtime and gitignored (not shipped in this repo).
`models.json`	Custom provider definitions, including local Ollama, vLLM, and llama.cpp models
`agent-modes.json`	Per-mode model/thinking overrides for debug, review, etc.
`damage-control-rules.yaml`	Safety rules: bash patterns, path access, delete protection
`auth.json.template`	Template for `auth.json` (provider API keys). Setup copies to live `~/.pi/agent/auth.json` on first run; never committed.
`mcp.json.template`	Template for `mcp.json` (MCP server configuration). Setup copies to live `~/.pi/agent/mcp.json` on first run; never committed.

Machine-specific Jira mappings live in ~/.pi/agent/JIRA_ROUTING.local.md, which is intentionally outside this repository and is not installed or synced by setup.mjs. The global AGENTS.md tells agents to read that file only when performing Jira operations.

MCP servers

Configured in mcp.json (created from template during setup):

Server	Purpose	Source
jCodeMunch	Code indexing, symbol search, context-aware edit prep	`uvx jcodemunch-mcp`
codebase-memory-mcp	Graph-backed architecture, call tracing, Cypher-style code queries	`codebase-memory-mcp`
Postgres MCP	Read-only PostgreSQL access via Docker	`crystaldba/postgres-mcp`
MariaDB MCP	Read-only MariaDB or MySQL access via `uvx`	`uvx --from iflow-mcp_mariadb-mariadb-server --with asyncmy==0.2.10 mariadb-server`
chrome-devtools	Browser automation via Chrome DevTools Protocol	`npx chrome-devtools-mcp@latest`
Tirith	Local security checks for commands, URLs, pasted content, files, directories, and MCP configs	`tirith mcp-server`

How to add new components

Extensions, agents, skills, prompts, and themes

Start in the repo whenever possible. Choose the owner path first, then link it into the live agent directories:

Component	Repo-owned source	Installed or linked to	Notes
Extension	`dotfiles/extensions/*.ts` or `dotfiles/extensions/<name>/`	`~/.pi/agent/extensions/`	Add the required top-level JSDoc block and update `dotfiles/extensions/CHANGELOG.md`.
Custom sub-agent role	`dotfiles/agents/<role>.md`	`~/.pi/agent/agents/<role>.md`	Use for user-managed role prompts discovered by `pi-subagents`.
Pi-only skill	`dotfiles/agent-skills/<skill>/`	`~/.pi/agent/skills/<skill>/`	Use for workflows that depend on Pi-only tools or UI.
Personal skill	`dotfiles/personal-skills/<category>/<skill>/`	`~/.agents/skills/<category>/<skill>/` and `~/.claude/skills/<skill>/`	Use for skills shared by Pi and Claude Code. These are not installed into `~/.pi/agent/skills/`.
Prompt template	`dotfiles/prompts/<prompt>.md`	`~/.pi/agent/prompts/`	Keep reusable prompts here instead of scattering local copies.
Theme	`dotfiles/themes/<theme>.json`	`~/.pi/agent/themes/`	Available after sync, but not automatically activated.

After adding the file:

Run npm run dev:sync during development, or npm run setup for copy mode.
Reload Pi if the running agent does not pick up the new file. Reload Claude Code only for personal skill changes.
Run the narrow validation for the changed area.
Commit and push the repo changes.

If you already built the component outside the repo:

In ~/.pi/agent/extensions, skills, agents, prompts, or themes, run node setup.mjs sync and accept the items you want to absorb. The script moves them into dotfiles/ and symlinks the live files back to the repo.
In ~/.agents/skills or ~/.claude/skills, move the skill manually into dotfiles/personal-skills/<category>/<skill>/, then run npm run dev:sync. setup.mjs sync intentionally does not scan those directories.
In a separate checkout or scratch directory, copy the source into the matching repo-owned path above, then run npm run dev:sync.
If the work is an installable first-party Pi package, develop it in its standalone repository under /Users/danielchamorro/Documents/Personal/Code/ and track the npm package name in manifest.json.

External skills

Install: npx skills add someone/repo -s skill-name -g -y
Add an entry to manifest.json.
Run npm run update:skills later to refresh all tracked external skills from the manifest.

Pi packages

Install: pi install npm:package-name
Add it to manifest.json under packages.
Update the README if it changes the documented setup.
Run npm run update:packages later to refresh all tracked Pi packages from the manifest.

Attribution

Some of these tools and extensions were adopted from other creators and modified to suit my needs:

License

MIT

Name		Name	Last commit message	Last commit date
.hooks		.hooks
.pi		.pi
archive		archive
dotfiles		dotfiles
scripts		scripts
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc		.prettierrc
LICENSE		LICENSE
README.md		README.md
manifest.json		manifest.json
package-lock.json		package-lock.json
package.json		package.json
setup.mjs		setup.mjs

Navigation Menu

Repository files navigation

pi-agent-toolkit

Quick start

For users (copy mode)

For development (link mode)

Bringing outside work into the repo

Full usage

Updating third-party skills and packages

What's in this repo

Tracked Pi packages

Extensions (20)

Skills

Custom sub-agent roles (2)

Prompt templates (1)

Themes (1)

Config files

MCP servers

How to add new components

Extensions, agents, skills, prompts, and themes

External skills

Pi packages

Attribution

License

About

Releases

Packages

Used by

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

pi-agent-toolkit

Quick start

For users (copy mode)

For development (link mode)

Bringing outside work into the repo

Full usage

Updating third-party skills and packages

What's in this repo

Tracked Pi packages

Extensions (20)

Skills

Custom sub-agent roles (2)

Prompt templates (1)

Themes (1)

Config files

MCP servers

How to add new components

Extensions, agents, skills, prompts, and themes

External skills

Pi packages

Attribution

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages