pi-cowboy is an orchestrator for the Pi coding agent that hands one large job to several background agents at once, and those agents can be Claude Code, Codex or OpenCode as well as Pi. It was shared on Hacker News on October 18, 2026 by suoloordi, who answers questions in the thread as its developer; the code is in the electric-dragon-80000v/pi-cowboy repository under the MIT license. What follows is what the author reports in the README and the post.

On this page

The setup

The technique is a split of roles. One parent session, running in Pi, breaks a job into small subtasks and delegates each one. Every subtask becomes an agent with its own terminal pane in Herdr, a terminal workspace for coding agents, and its own copy-on-write Git worktree on its own branch. The author’s argument in the README: one task with clear instructions leaves less room for drift and over-engineering than a long list of expectations, and a branch per subtask lets you review and merge each one separately.

The README’s example prompt asks the parent to group the files from a security audit into 10 groups and launch parallel agents to fix them. With the default global limit of 4, the first four agents start and the other six wait in a queue until slots open.

Each agent’s run follows the same steps, as the README describes them:

  1. Spawn. The parent calls the cowboy_agent tool, which returns an agent ID right away.
  2. Isolate. The agent works in a worktree under ~/.pi/agent/pi-cowboy/worktrees/ by default, in a Herdr pane you can open to watch or steer it.
  3. Settle. When the agent finishes its turn, its report arrives as a message in the parent session. steer_cowboy_agent can send it back for another pass.
  4. Merge. merge_cowboy_branch merges the agent’s branch into the main working tree, which must be on the target branch with no uncommitted changes. A conflict is left in place for you to resolve.
  5. Clean up. cleanup_cowboy_agent closes the pane, removes the worktree and deletes the branch.

The README says cleanup is safe by default: it refuses to touch a running agent, keeps a worktree with uncommitted changes and deletes a branch only after it has been merged. A Force removal exists only in the /cowboy status menu, for a settled agent, and it discards anything uncommitted in that worktree after a confirmation that names what will be lost.

Mixing Claude Code, Codex and OpenCode

pi-cowboy auto-detects Codex, Claude Code, OpenCode, PiG and Pi-Bolt when they are on your PATH, according to the README. You can name a harness in the prompt (“Launch an OpenCode agent for this task”), pass harness_type (pi, pig, pi-bolt, opencode, codex or claude) on the tool call, or set a default in the configuration and agent templates.

In the Hacker News post, the author gives the use he has in mind: when Codex usage runs out, switch the harness to OpenCode, pick one of its free models and let it carry on. PiG and Pi-Bolt are Pi variants that he describes as lighter on memory, which matters when several agents run at once.

Concurrency can be capped at four levels: globally with concurrency.default (4 by default), and per harness, per provider and per model. A running agent holds a slot at every level that applies to it, and an agent waiting on a busy model does not block a queued agent that uses a different model.

Disk use

Copy-on-write worktrees are the reason the author gives for running many agents at once on a large repository. On a repository with 153,607 files (479 MiB tracked, 27 GiB including untracked files), the README reports:

Method Includes untracked files Size on disk
pi-cowboy copy-on-write yes 75 MiB
git worktree add no 479 MiB
git worktree add plus a copy of untracked files yes 27 GiB

This needs a copy-on-write filesystem: APFS on macOS, Btrfs or ZFS on Linux. On ext4, the README says agent.worktreeMaterialization falls back to checkout.

Templates

Recurring roles go into agent templates with their own system prompt, model, harness and tool permissions. The README’s example:

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.
'''

Orchestrator templates apply a rule to every agent instead. The README’s example makes each agent run an adversarial review tool before it commits:

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

Install

The README lists Linux or macOS, herdr 0.8 or later with the Herdr Pi integration enabled, a copy-on-write filesystem, and python3 on macOS. The install command from the repository:

pi install npm:pi-cowboy

pi-cowboy activates when you run pi inside a Git repository; /cowboy opens its menu and /cowboy status lists spawned, queued and settled agents. In the thread, the author says he is working on a plugin system that already makes the coding harnesses and the terminal multiplexer pluggable.

Claude Code has its own way to delegate inside one session; see Claude Code subagents for the built-in files, tools and models.