pi-cowboy

License: MIT

pi-cowboy is a multi-agent orchestrator for pi. Break a large job into focused subtasks, hand them off to background agents running in parallel, and merge their branches back when they finish.

Each agent runs in its own terminal pane inside Herdr and works in an isolated copy-on-write Git worktree. You can watch agents work in real time, jump into any pane to steer them, or mix and match harnesses like Pi, Claude Code, OpenCode, and Codex in the same session. When the work is merged, pi-cowboy cleans up the panes, worktrees, and branches for you.

Why should I use it?

Focused tasks produce better code

Give each agent a smaller, isolated subtask. A single task with clear instructions leaves little room for error, whereas a long list of expectations invites drift and over-engineering. Because each agent commits to its own branch, you can review and merge each subtask on its own.

Foreign harness support

pi-cowboy can orchestrate Claude Code, Codex, OpenCode, and more: start work on Pi, continue on Claude Code, finish on OpenCode. Do you need support for something else? Create an issue on GitHub.

Parallel work with minimal disk overhead

Multiple agents can edit, build, and run tests at the same time without interfering with each other. Copy-on-write worktrees make high parallelism practical by keeping disk usage small even when your repository has gigabytes of untracked build artifacts or dependencies.

The numbers below come from a Git repository with 153,607 files in total (479 MiB tracked, 27 GiB total including untracked files):

Live visibility in Herdr

Each task gets its own shell, a visible terminal pane you can open at any time, and notifications when an agent needs your attention.

Custom workflows

Define reusable agent templates for specialist roles and orchestrator templates to adapt how agents work and report back.

Grazing cows and a cowboy on your screen

Who wouldn’t want their agents visualized as cow emojis? Go on… guess. That's exactly right. No one.

Requirements

• Linux or macOS
• herdr 0.8 or later, with the herdr pi integration enabled
• python3 on macOS (used for copy-on-write worktrees; macOS has not shipped python3 since 12.3, so install the Xcode Command Line Tools with xcode-select --install)
• Copy-on-write capable filesystem (APFS on macOS; BTRFS or ZFS on Linux)
  • ext4 does not support copy-on-write. On ext4, agent.worktreeMaterialization falls back to checkout.

Install

Install from npm:

pi install npm:pi-cowboy

Usage

pi-cowboy activates automatically whenever you run pi inside a Git repository.

1. Delegating a task

pi-cowboy spawns background agents for the subtasks right away:

✓ Spawned agent b7g2nspx (general-purpose) ✓ Spawned agent 5m1xx7fa (general-purpose) ...

If you spawn more agents than your concurrency limit allows, the extras wait in a queue. With the default global limit of 4, the first 4 agents start immediately and the remaining 6 start as slots open up.

2. Agent isolation

Each agent runs as a separate process in its own Herdr workspace, inside its own tab and terminal pane. You can switch to an agent's workspace at any time to watch its progress or steer it directly.

On disk, each agent works in a dedicated Git worktree under <agent dir>/pi-cowboy/worktrees/ (~/.pi/agent by default).

3. Agent completion

When an agent finishes its turn (settles), its report arrives as a message in the parent session:

✓ [Cowboy agent "general-purpose" b7g2nspx completed] Addressed all the points raised in the security audit for the given set of files. (Worktree: $HOME/.pi/agent/pi-cowboy/worktrees/cow-audit-perms-b7g2nspx (branch cow-audit-perms-b7g2nspx). The agent process and its herdr pane stay until you call cleanup_cowboy_agent — its pane is closed, which ends that process. The worktree stays until you call cleanup_cowboy_agent to remove it — call it once the branch is merged or rejected.)

The parent session can then review the report, steer the agent if something needs another pass, or merge the branch.

4. Merging

To bring the changes in, the orchestrator calls merge_cowboy_branch, which merges the agent's branch into your repository's main working tree:

✓ Merged "cow-audit-perms-b7g2nspx" into "main" in pi-mono.

5. Cleanup

Once the work is merged, the orchestrator cleans up the agent's resources (or you can ask it to):

cleanup_cowboy_agent closes the Herdr pane and tab, removes the worktree, and deletes the branch:

✓ Cleaned up agent b7g2nspx: agent status: completed pane: closed worktree: removed ($HOME/.pi/agent/pi-cowboy/worktrees/cow-audit-perms-b7g2nspx) branch: deleted (cow-audit-perms-b7g2nspx)

Cleanup is safe by default: it refuses to touch an agent that is still running, keeps any worktree that still has uncommitted changes, and deletes the branch only if it has already been merged. If one step cannot be completed, pi-cowboy reports the reason and finishes the rest.

Customizing your workflow

Agent templates

If you find yourself repeating the same instructions for recurring jobs, you can package them into an agent template with its own system prompt, model, harness, and tool permissions.

For example, a release-notes template looks like this:

name = "release-notes"
description = "Prepares release notes."
system_prompt = '''
You prepare release notes for this repository. Read the history and tags
(git log, git tag) and report the changes as a message.
'''

You can then ask for it by name in the parent session:

See Agent Templates for all template fields and directory locations.

Orchestrator templates

While agent templates specialize individual workers, orchestrator templates apply rules across every agent you spawn. They also let you customize the status messages ("cues") sent to the parent session when agents spawn, queue, or settle.

For instance, if you use an adversarial review tool, you can define an orchestrator template that requires every agent to run it before committing:

name = "adversarial-review"
guidance = '''
Run the adversarial-review tool before you commit, and fix any glaring mistakes that the review finds and then commit.
'''

You can switch the active orchestrator at any time from /cowboy > Default orchestrator. See Orchestrator Templates for details.

Foreign harnesses

pi-cowboy auto-detects Codex, Claude Code, OpenCode, PiG, and Pi-Bolt when they are installed on your PATH. You can request a specific harness directly in your prompt (for example, "Launch an OpenCode agent for this task") or set defaults in your configuration and agent templates.

Concurrency

You can cap how many agents run at the same time across four independent levels:

• Global: concurrency.default (default 4), which applies to every agent
• Per harness: concurrency.harnesses.<harness-id>
• Per provider: concurrency.providers.<provider>
• Per model: concurrency.models["<provider>/<model-id>"]

A running agent occupies a slot in every limit that applies to it. When the agent settles, it releases those slots and pi-cowboy starts the next queued agent that has room at all of its levels. An agent waiting on a busy model limit will not block a queued agent behind it that uses a different model.

If you steer a settled agent, it wakes up in its existing pane and runs immediately, even if that temporarily puts a limit over capacity.

Configure these limits in config.json or live in your session via /cowboy > Settings > Concurrency Settings. See Configuration for details.

Model resolution

When pi-cowboy spawns an agent, it picks the model using the first match in this order:

1. The model parameter passed to the cowboy_agent tool call
2. The session per-type model override (/cowboy > Model overrides)
3. The config per-type override (agent.<agent-type>)
4. The model set in the agent template for the launching harness family
5. The session default model (/cowboy model)
6. The launching harness's configured default (agent.default for the Pi family, or agent.defaultModelByHarness for foreign harnesses)
7. For Pi-family launches, the parent session's active model

See Configuration for the full rules.

Commands

Run /cowboy to open the interactive menu, or pass a subcommand directly. See Menu for a guide to every screen.

/cowboy                         # Open the pi-cowboy menu
/cowboy status                  # List spawned, queued, and settled agents
/cowboy spawn                   # Spawn an agent manually
/cowboy worktree                # Create a git worktree with no agent attached
/cowboy model                   # Pick the default agent model for this session
/cowboy model provider/model-id # Set the default agent model for this session
/cowboy model clear             # Clear the session model override
/cowboy enable                  # Enable pi-cowboy
/cowboy disable                 # Disable pi-cowboy

Tools

cowboy_agent

Delegates one or more tasks to cowboy agents. By default, the call returns immediately with an agent ID for each task, and results arrive in the parent session as each agent settles.

Each item in agents[] takes:

steer_cowboy_agent

Sends a follow-up message to one or more agents. If an agent is running, it receives the message before its next model call. If an agent has already settled, steering revives it in the same pane for another turn and delivers a new completion message when it settles again.

Queued agents cannot be steered because they do not have a pane yet. Agents that have already been cleaned up (or are currently being cleaned up) cannot be steered either.

stop_cowboy_agent

Interrupts one or more running agents and marks them as stopped. Their worktrees, branches, and panes are preserved so you can inspect or clean them up afterward.

merge_cowboy_branch

Merges one or more settled agent branches into a target branch in your repository's main working tree. Your main working tree must already be on the target branch with no uncommitted changes. If a merge conflict occurs, pi-cowboy leaves the conflict in place so you can resolve it.

cleanup_cowboy_agent

Closes the Herdr pane and tab, removes the worktree, and deletes the branch for one or more settled agents. The tool reports the result for each agent.

Cleanup never throws on partial failures: it deletes a branch only after it has been merged, and it keeps any worktree that still has uncommitted changes (reporting why it was kept).

FAQ

Why is my agent queued, not running?

Every running agent occupies a slot in each concurrency limit that applies to it: model, provider, harness, and global (model and provider keys can also be scoped to a harness, like opencode:provider/model). pi-cowboy queues new agents until all of their applicable limits have room. You can raise limits in /cowboy > Settings > Concurrency Settings or in your config file. See Concurrency.

Why did my worktree survive cleanup?

cleanup_cowboy_agent refuses to delete a worktree that still has uncommitted changes or whose git status cannot be verified. Commit or discard the leftover changes, make sure the agent is stopped, and run cleanup again. See cleanup_cowboy_agent.

Isn't one pi process per agent too much overhead?

For a single tiny change, spinning up a fresh process can take longer than making the edit directly. pi-cowboy is built for running several tasks in parallel, where that startup cost is paid once across all concurrent agents.

If you want faster startup and lower memory usage, pi-cowboy also supports pig (a drop-in Pi replacement written in Go) and pi-bolt (an ahead-of-time compiled Pi variant). Set agent.harnessType in Configuration to use them.

I don't like the emojis, can I turn them off?

Yes. You can disable both the cowboy indicator and the grazing cows in /cowboy > Settings or in your config file. See Configuration.

References

• Configuration
• Menu
• Agent Templates
• Orchestrator Templates