piñata

Pi stays small. Your subagent system should too.

Pinata is a fast, lightly opinionated subagent layer for Pi. You define agents, piñata delegates work, boundaries, and verifies results.

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

Scout, builder, and reviewer come in the box. These are lightweight definitions meant for common development tasks. Planner and researcher are examples to steal and make your own.

Watch the demo · Ten agents build and review a CLI.

Why use Pinata? Follow a real change from task to reviewed patch, inspect the evidence, and choose a first example.

Build Relay with your models: start from the demo's module stubs, run ten agents, inspect their reviews, and verify the assembled application.

Install

In Pi's terminal (manual):

pi install npm:pi-pinata

Reload Pi. You need Pi 1.1.0+, Node 22.19+ (for the pinata command), and Git, on Linux, macOS or Windows.

Herdr is optional (agents can run as their own panes inside Herdr).

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.
Bring back the relevant files, assumptions, and tests.

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

/pinata-review Focus on the error handling.

Pi picks the agents, writes their briefs, and decides who waits for whom. Start with the first-run tutorial.

The three agent presets

Custom agents

An agent is a reusable Markdown definition: instructions in the body, with its name, tools, workspace, and optional model defaults in YAML frontmatter. A task gives that agent a specific job. You choose which agents to use and how their tasks depend on each other.

Save definitions in either location:

A repository definition replaces a personal definition with the same name. The three preset names are reserved; give your custom version a new name.

For example, create a GitHub CI triage agent that inspects failed Actions runs and writes a report with evidence and next steps.

Save this as .pi/pinata/agents/ci-triage.md:

---
schemaVersion: 1
name: ci-triage
description: Diagnose failed GitHub Actions runs and recommend the next fix.
workspace: worktree
tools: [read, grep, find, ls, bash, write]
output:
  require: [brief]
---

Inspect the assigned GitHub Actions run using gh run view and its --log-failed
option. Always pass --repo OWNER/REPO. Record the run attempt and head commit,
then trace each failed job to its first actionable error.

Read the relevant workflow and source at the failing commit. If that revision
or its logs are unavailable, report the gap. Separate code, workflow, dependency,
and runner failures; call a failure flaky only with evidence from other attempts.

Write ci-triage.md with run and job links, short log excerpts, likely causes,
confidence, and the smallest suggested fix and verification command for each cause.
Return a brief summary of the findings and any blockers.

Use GitHub only for inspection. Do not rerun jobs, post comments, or change remote
state. Write only the report; do not fix code, install dependencies, or run tests.

Then ask Pi:

Have ci-triage investigate this failed run: <GitHub Actions run URL>.

Inside Pi, pinata_agents lists available definitions. From a terminal, use pinata agents list, pinata agents show ci-triage, or pinata agents validate.

See creating agents for all fields, custom tools, and the optional planner and researcher examples.

Configuration hierarchy

Agent definitions describe the agent. Configuration sets models, run limits, execution mode, backend, and worktree setup. Settings apply in this order, from lowest to highest priority:

models, fallbacks, limits, and toolProviders merge by entry: overriding limits.concurrency keeps the other limits. Other keys are replaced by the higher priority value. If you set PI_CODING_AGENT_DIR, that directory replaces ~/.pi/agent for both personal config and agent definitions.

For example, put this in .pi/pinata.json to allow four agents at once per run:

{
  "limits": { "concurrency": 4 }
}

Model selection uses the first defined value in this order:

1. The task's model.
2. models[agentName] from the merged config.
3. The agent definition's model.
4. models.default from the merged config.
5. The current Pi model.

If the selected model is unknown or lacks authentication, Pinata tries the agent's configured fallbacks, or its definition fallbacks when none are configured. See the configuration reference for all settings and defaults.

What it's like to use

• Fast. Agents share your Pi process by default. Startup, memory, and dispatch have performance budgets, including tests at 64 active agents.
• Visible. The widget above Pi's editor shows each agent's status, elapsed time, and activity, plus total tokens and cost. Open /pinata view to read conversations and steer agents. Shift+↑/↓ moves between conversations; Esc returns to Pi. Use /pinata view --external to enable live viewing and steering from another terminal. See watching agents.
• Verifiable. Writers work in isolated Git worktrees. Pinata checks their actual changes against the task's owned paths and runs the task's checks. The handoff and integration helpers require an independent reviewer to approve the exact change. Integration applies it to your checkout without staging or committing; checks in your checkout are recorded separately. See build and review.
• Recoverable. Runs, results, and logs are saved on disk. Agents launched with survive: true keep running when Pi exits; the next Pi session in the repository resumes the run. Use /pinata rerun <run> to restart tasks lost in a crash. See recovery.
• Scriptable. pinata run job.json runs a job without an interactive Pi session. It supports plain or JSONL output and exit codes for CI. See headless runs.

Keep it small

Pinata reuses Pi's sessions, models, tools, and extensions. Workflows live in editable agent definitions, prompts, and recipes. Each run saves the definitions it used, so you can inspect its instructions alongside its results. Tool extensions load only for agents that need them.

The benchmark suite tracks startup, memory, context size, and dispatch costs as the project grows.

Documentation

The documentation index lists everything, including maintainer docs.

MIT licensed.