piñata

Fast, observable subagents for Pi.

Ask for a scout, a researcher, a planner, a builder, or a reviewer, and each one opens in its own Herdr workspace where you can watch it work. When they finish, Pi brings their results back. Every builder change gets a separate review before it reaches your checkout.

https://github.com/user-attachments/assets/d1b45899-beef-4dcc-9b0e-d59ab28c6a5d

Install

pi install npm:pi-pinata

Then enable Herdr's Pi integration, so Pi can resume on its own when the agents finish:

herdr integration install pi

Reload Pi, run it inside a Herdr session, and you're ready. You'll need Pi 1.0.2+, Herdr 0.9.1+, Node 22.19+, and Git; research also uses pi-web-access. Setup covers models, sessions, and checking your install.

Try this first

Ask Pi in plain language:

Have a scout figure out how request validation works in this repo.

Send two scouts out in parallel, one on the retry logic and one on its tests.
Then have research check both reports against the official docs.

/skill:engmgmt Fix this bug, test it, and have a reviewer sign off before it
touches my checkout.

/pinata-fix Correct the seconds-to-milliseconds conversion in src/duration.mjs.

/pinata-review Focus on the error handling.

That's enough to start. Pi picks the agents, writes their briefs, and decides who waits for whom.

Meet the team

Rule of thumb: scout before you understand the code, research before you trust an outside fact, plan when the change is big, build when the path is clear, and always review before you merge.

What it's like to use

• Watch any agent. Each agent is a real Pi session in its own Herdr workspace. Switch to one whenever you like and see what it's reading and running.
• Pi picks up the results. With Herdr's Pi integration enabled, Pi resumes on its own when the agents finish and reads their reports. While they work, it sits idle and uses no tokens.
• Agents work from your current files. Uncommitted edits and new files come along, so agents see the same code you're looking at.
• Agents can wait on each other. Ask for "research once both scouts are done" and Pi sets up the order. Anything that doesn't depend on other work runs in parallel.
• Builder changes are reviewed before they land. Each builder works in its own worktree, and a separate reviewer has to approve that exact change before pinata applies it to your checkout. You can roll an integration back as long as you haven't edited those files since. Committing is left to you.
• Review your own work, too. /pinata-review points several reviewers at your uncommitted changes, a branch, or a GitHub pull request and gives you one combined list of findings.
• Cost and memory are visible. Above the editor, Pi lists each running agent with time, tokens, cost, and sampled memory usage. Set limits.costUsd to stop a run at a dollar amount.
• Cleanup is automatic. Finished workspaces close, and worktrees are removed once their work is done or merged. Results are kept, so you can go back and read what each agent found.
• Same model as you. Agents use your current Pi model by default. You can give each role its own model and thinking level.

Common asks

Where to look while it runs

Each agent gets its own Herdr workspace in the sidebar. Open one to watch that agent think, read files, and call tools as it goes.

While a run is going, Pi shows each agent's state, time, tokens, cost, and sampled memory above the editor, and a one-line summary in the footer. Type /pinata for the same view in the transcript, or /pinata runs for past runs in this repository. Neither sends anything to the model.

For a little paper magic, open /pinata live: a turning 3D terminal piñata with colored ribbons and the actual task statuses beside it. Press Space to bonk, M to toggle motion, and Esc to return to Pi; workers keep going. In fullscreen Pi you can also click the small companion above the editor to open it. The victory confetti waits for successful tasks and, for builder runs, verified integration. Try /pinata live demo without starting agents, then follow the live mascot walkthrough.

If something feels off

Ask Pi for the run's status first; it says which agent is stuck and why. Recovery covers resuming, repairing, and cleaning up a run, and setup helps when an agent won't start.

Process overhead

Each agent runs in its own Pi process. For a tiny task, starting the agent can take longer than doing the work. piñata is built for jobs with several independent tasks, where running them in parallel can make up for that overhead.

Good to know

• Agents get a copy of your files as they were when you asked, uncommitted changes included. Ignored files like node_modules and .env are left out unless you list them in .worktreeinclude.
• Builders run commands with your permissions, so read a builder's task before you approve it. Concepts has details.
• Tested on Linux; macOS should work. See validation.

Documentation

The documentation index also links to contributor testing, recorded validation, and npm publication instructions.

MIT licensed. Made w/ Opus 5.5, a bit of hand crafted code, and a lot of stepping through & debugging :P