Harpy is my personal Pi coding agent package. It bundles repo-local extensions, prompt additions, and a theme.
Clone the repo, run ./setup.sh, restart Pi, and Pi will load this checkout.
I built this for myself first. You are welcome to use it or copy pieces from it, but expect rough edges and opinionated defaults.
- Node.js 20+
- Pi installed locally
If Pi is not installed yet:
npm install -g @mariozechner/pi-coding-agentInstall Harpy:
git clone https://github.com/Isaac-Flath/harpy.git
cd harpy
./setup.shThen restart Pi and verify the install:
npm run typecheck
pi -p "List available tools" --no-session./setup.sh is the main install and update step. It:
- Installs npm dependencies.
- Symlinks
prompts/APPEND_SYSTEM.mdto~/.pi/agent/APPEND_SYSTEM.md. - Adds this repo's
extensions/andthemes/directories to~/.pi/agent/settings.json. - If
~/.agentkb/skills/.claude/skillsexists, symlinks those AgentKB skills into~/.pi/agent/skills.
Re-run ./setup.sh after changing prompts, extensions, or themes.
| Path | Purpose |
|---|---|
extensions/agentkb.ts |
Adds kb_search, kb_read, kb_list, kb_chat_read, and kb_wiki_path |
extensions/rlm.ts |
Adds rlm_query for deeper KB investigations |
extensions/colgrep.ts |
Adds colgrep semantic + regex code search |
extensions/git-dashboard.ts |
Adds git_dashboard for a one-call repo snapshot |
extensions/review-prep.ts |
Adds review_prep for commits, diffstat, and diff |
extensions/list-dir.ts |
Adds list_dir for recursive tree views |
extensions/web.ts |
Adds web_fetch for web pages, YouTube transcripts, and PDFs |
extensions/gemini.ts |
Adds gemini for PDF, image, and video analysis |
extensions/think.ts |
Adds think for explicit planning steps |
extensions/diff-view.ts |
Improves how edit and write diffs render |
extensions/read-view.ts |
Improves collapsed summaries for read output |
extensions/prevent-idle-sleep.ts |
Prevents macOS idle sleep with caffeinate |
extensions/resume-last.ts |
Prints the exact pi --session ... command to resume the current session when Pi exits |
prompts/APPEND_SYSTEM.md |
Extends the system prompt with AgentKB, colgrep, RLM, GitHub API, and Gemini guidance |
themes/ghostie.json |
Adds a Ghostty-friendly light theme |
Harpy works as a basic Pi package with just Node and Pi. A few tools need extra local setup.
AgentKB-related tools depend on a local AgentKB install and local AgentKB data.
That affects:
kb_searchkb_readkb_listkb_chat_readkb_wiki_path- AgentKB skills linked into
~/.pi/agent/skills
rlm_query ships with Harpy, but notebook reruns and deeper local experiments also need model auth configured in Pi.
Background and design context:
- Blog post: https://isaacflath.com/writing/rlm
You can smoke-test it with:
npm run spike -- "What does my KB say about concurrency gotchas in Go?"The gemini extension calls the Gemini API directly.
Set one of these up before using it:
# Direct Gemini API
export GEMINI_API_KEY=...
# Optional Vertex AI fallback
export GOOGLE_GENAI_USE_VERTEXAI=true
export VERTEX_AI_API_KEY=... # or GOOGLE_API_KEY=...The tool tries the direct Gemini API first. If that fails, it retries with Vertex AI when configured. Use it for PDFs, images, and videos. Do not use it as a general code or long-context text tool.
./setup.sh: installs dependencies and wires Harpy into~/.pi/agent/npm run typecheck: type-checks the extensionsnpm run spike -- "question": standalone RLM smoke test and debugging helperscripts/rlm-server.ts: internal helper for notebook reruns generated by RLM logs
pi
pi -p "query" --no-sessionUse this repo if you already use Pi and want a working set of extra tools, prompts, and themes without building everything yourself.
If you want a polished starter kit, this is probably not it. The easiest way to borrow from Harpy is usually to point an agent at this repo and ask it to copy the parts you want into your own setup.
prevent-idle-sleepis macOS-only and starts automatically when Pi starts.- You do not need to adopt the whole repo. Copy the ideas you like.
- If Harpy saves you time, leave a star.