electric-dragon-80000v/pi-cowboy

A Herdr-native agent orchestrator for Pi. In addition to Pi itself, it can run Codex, Claude Code, OpenCode, and more as subagents in isolated, copy-on-write Git worktrees

Summary

pi-cowboy is a multi-agent orchestrator for the Pi coding assistant that breaks large jobs into focused subtasks and runs them in parallel as background agents. Each agent works in an isolated copy-on-write Git worktree inside its own Herdr terminal pane, and the orchestrator can mix different coding harnesses such as Pi, Claude Code, OpenCode, and Codex in the same session. When agents finish, their branches are merged back into the main checkout and the worktrees are cleaned up.

What it is useful for

Use it when a single coding agent would otherwise juggle too many changes at once. A large security audit, a multi-file refactor, or a sprawling test-fix pass can be split into smaller subtasks, each handled by its own agent on its own branch. Because the worktrees are copy-on-write, parallel agents editing a large repo don't multiply disk usage the way git worktree add does. The README reports a 153,607-file repository (479 MiB tracked, 27 GiB with untracked files) fitting in 75 MiB with pi-cowboy, versus 479 MiB for a classic worktree or 27 GiB if untracked files are copied too.

It is also useful when you want to mix harnesses: start a task in Pi, hand off to Claude Code, finish in OpenCode, or pin specific models per agent type. Live Herdr panes let you watch each agent in real time, jump in to steer one that is drifting, and merge or reject each branch independently. Recurring roles can be packaged as agent templates (system prompt, model, harness, tool permissions) and orchestrator templates can apply cross-cutting rules such as "run the adversarial-review tool before you commit" to every job in a session.

How engineers can use it

Install with pi install npm:pi-cowboy, then run pi inside any Git repository and pi-cowboy activates on its own. From the parent session, ask Pi to delegate subtasks, for example: "group the audit files into 10 groups and launch parallel cowboy agents to address them." Spawned agents beyond the default global concurrency of 4 are queued until slots free up. Use /cowboy status to see what is running, queued, or settled, and /cowboy model provider/model-id to set the default agent model for the session.

Five tools cover the lifecycle: cowboy_agent to delegate, steer_cowboy_agent to send a follow-up (reviving a settled agent in its existing pane), stop_cowboy_agent to interrupt, merge_cowboy_branch to bring changes in (default target main, conflicts are left in place for you to resolve), and cleanup_cowboy_agent to close the pane, remove the worktree, and delete the branch once merged. Cleanup refuses to delete worktrees with uncommitted changes and only deletes a branch if it has already been merged.

Documented requirements: Linux or macOS, Herdr 0.8 or later with the pi integration enabled, python3 on macOS (install with xcode-select --install), and a copy-on-write filesystem such as APFS, BTRFS, or ZFS. On ext4, worktree materialization falls back to a regular checkout and loses the disk-saving benefit.