piñata

Pi stays small. Your subagent system should too.

Piñata is a fast, extensible subagent framework for Pi. Ask Pi to split a change between builders and reviewers. Pinata coordinates the tasks and brings back changes, findings, and checks you can inspect.

piñata ships only three agent definitions: scout, builder, and reviewer. Add your own agents and tools as your workflow grows.

Pi keeps the harness small and lets you make it yours. Pinata follows that lead.

Install

Run in your terminal:

pi install npm:pi-pinata

Reload Pi. You need Pi 1.1.0+, Node 22.19+ (for the pinata cli), and Git. Herdr is optional. Piñata works on Linux, macOS, and Windows. See platform setup for more detail.

By default, Pinata's built-in agents use the current Pi model. Agent model definitions can be set in ~/.pi/agent/pinata.json (personal), .pi/pinata.json (repository), or a job's config. Tasks and agent definitions can also specify models; see model configuration for precedence and fallbacks.

Try it

Ask Pi in plain language:

Send two scouts out in parallel, one on the retry logic and one on its tests.
Bring back the relevant files, assumptions, and tests.

Or try a focused fix or review:

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

/pinata-review Focus on the error handling.

Pi can choose agents, write their briefs, and set dependencies. Follow the first-run tutorial for a guided start.

How it works

A run contains tasks, their agents, dependencies, and any file ownership and checks. Piñata orchestrates the DAG: independent tasks run in parallel; dependent tasks wait for their inputs. The included agents cover three common roles, and can be tailored to your liking:

• Scout maps the relevant code and returns a brief.
• Builder makes an assigned change in a separate Git worktree.
• Reviewer examines a specific change and its evidence.

Pinata jobs have a defined schema, so Pi or another capable coding agent can read the job format, inspect your repository, and turn a plan for your goal into a job with ownership, dependencies, checks, and independent review. Pinata runs the tasks and configured checks and records the results; your coordinator agent invoking pinata decides what to do next, including any repairs.

Build and review walks through the process.

Worktrees keep patches separate from your checkout, but they are not security sandboxes. Shell commands and custom tools have your operating-system permissions and network access. Read trust and safety before authorizing work.

Save the plan as a job file and you can run it from a terminal or CI (outside of pi) with pinata run job.json.

Headless runs (currently) leave builder changes in their worktrees; integrate them separately in Pi. See headless runs, or use the goal-to-job prompt to have a coordinator design a plan for your repository. Browse the job patterns for delivery, research, UX, accessibility, and data pipelines.

Make it yours

Agents are reusable Markdown definitions with instructions, tools, workspace, and optional model defaults. For example, save this as .pi/pinata/agents/api-scout.md:

---
schemaVersion: 1
name: api-scout
description: Map an API and its tests.
workspace: live-readonly
tools: [read, grep, find, ls]
output:
  require: [brief]
---

Find the API's entry points, callers, error handling, and tests. Return a brief
with file references and unanswered questions.

Ask Pi to use api-scout on a specific API. Personal definitions live in the global .pi dir or on a per-repo basis in .pi.

Set repository limits, fallbacks, backends, and custom tool providers in .pi/pinata.json. See creating agents and the configuration reference.

Pinata uses Pi's sessions, models, tools, and extensions. You can watch and steer agents in Pi, inspect saved runs, and choose process or Herdr backends when they suit your setup. Watching agents and backends show how.

Documentation

• Learn: First run, build and review, Relay walkthrough
• Do: Create agents, run headless, recover a run
• Look up: Tools, commands, configuration
• Understand: Why Pinata?, architecture, trust and safety

The documentation index has the full list, including maintainer docs.

MIT licensed.