pi-cowboy 0.10.1 → 0.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +151 -152
  2. package/package.json +4 -3
package/README.md CHANGED
@@ -4,45 +4,53 @@
4
4
 
5
5
  **License:** MIT
6
6
 
7
- pi-cowboy is an agent orchestrator for [pi](https://pi.dev). It is designed for step-by-step task decomposition and supervision. It coordinates multiple agents in the background while keeping their work visible and actionable. Each agent gets a dedicated pi process and an isolated Herdr workspace backed by its own copy-on-write worktree. pi-cowboy creates those worktrees and cleans them up for you automatically.
7
+ `pi-cowboy` is a multi-agent orchestrator for [pi](https://pi.dev). Break a large job into focused subtasks, hand them off to background agents running in parallel, and merge their branches back when they finish.
8
+
9
+ Each agent runs in its own terminal pane inside [Herdr](https://github.com/electric-dragon-80000v/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.
8
10
 
9
11
  ## Why should I use it?
10
12
 
11
- - **Improved code understanding:** Give each agent a smaller, isolated subtask. A single focused task with clear guidance leaves little room for error; a long list of tasks and expectations creates more room for drift and over-engineering. Smaller tasks therefore improve code quality and yield results that are easier to review: each agent commits to its own branch, so a subtask is reviewed and merged on its own, separately from the others.
13
+ ### Focused tasks produce better code
12
14
 
13
- - **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](https://github.com/electric-dragon-80000v/pi-cowboy/issues/new).
15
+ 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.
14
16
 
15
- - **Parallel work with minimal disk overhead:** Multiple agents can edit, build, and run tests concurrently without interfering with each other. Copy-on-write unlocks more parallelism by reducing the disk overhead of the worktrees.
16
- The numbers below are from a Git repository containing 153,607 files in total. The tracked files occupy 479 MiB, while the repository is 27 GiB in total, including untracked files.
17
+ ### Foreign harness support
17
18
 
18
- | Method | Including untracked | Size on disk |
19
- | ------------------------------ | ------------------- | ------------ |
20
- | Pi-cowboy's copy-on-write | yes | 75 MiB |
21
- | Classic `git worktree add` | no | 479 MiB |
22
- | Classic wt + copy of untracked | yes | 27 GiB |
19
+ `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](https://github.com/electric-dragon-80000v/pi-cowboy/issues/new).
23
20
 
24
- - **Herdr integration:** Each task gets its own shell, a visible pane, and notifications when an agent needs your attention.
21
+ ### Parallel work with minimal disk overhead
25
22
 
26
- - **Custom workflows:** You can specify custom workflows via agent and orchestrator templates to fit your environment and working style.
23
+ 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.
27
24
 
28
- - **Grazing cows and a cowboy on your screen**:
25
+ The numbers below come from a Git repository with 153,607 files in total (479 MiB tracked, 27 GiB total including untracked files):
29
26
 
30
- ![image-20260930022747492](https://raw.githubusercontent.com/electric-dragon-80000v/pi-cowboy/main/docs/assets/grazing.png)
27
+ | Method | Including untracked | Size on disk |
28
+ | ------------------------------ | ------------------- | ------------ |
29
+ | Pi-cowboy's copy-on-write | yes | 75 MiB |
30
+ | Classic `git worktree add` | no | 479 MiB |
31
+ | Classic wt + copy of untracked | yes | 27 GiB |
31
32
 
32
- Who wouldn’t want their agents visualized as cow emojis? Go on… guess. That's exactly right. No one.
33
+ ### Live visibility in Herdr
33
34
 
34
- ## Requirements
35
+ Each task gets its own shell, a visible terminal pane you can open at any time, and notifications when an agent needs your attention.
35
36
 
36
- - Linux/macOS
37
- - `herdr` 0.8 or later
38
- - `herdr` pi integration
39
- - macOS also needs `python3` for copy-on-write worktrees
37
+ ### Custom workflows
40
38
 
41
- - macOS has shipped no `python3` since 12.3. Install the Xcode Command Line Tools: `xcode-select --install`
39
+ Define reusable [agent templates](#agent-templates) for specialist roles and [orchestrator templates](#orchestrator-templates) to adapt how agents work and report back.
42
40
 
43
- - Copy-on-write capable filesystem (APFS on macOS, BTRFS, and ZFS on Linux)
41
+ ### Grazing cows and a cowboy on your screen
44
42
 
45
- - ext4 does not support CoW. If you use ext4, `agent.worktreeMaterialization` falls back to `checkout`.
43
+ ![image-20260930022747492](https://raw.githubusercontent.com/electric-dragon-80000v/pi-cowboy/main/docs/assets/grazing.png)
44
+
45
+ Who wouldn’t want their agents visualized as cow emojis? Go on… guess. That's exactly right. No one.
46
+
47
+ ## Requirements
48
+
49
+ - Linux or macOS
50
+ - `herdr` 0.8 or later, with the `herdr` pi integration enabled
51
+ - `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`)
52
+ - Copy-on-write capable filesystem (APFS on macOS; BTRFS or ZFS on Linux)
53
+ - `ext4` does not support copy-on-write. On `ext4`, `agent.worktreeMaterialization` falls back to `checkout`.
46
54
 
47
55
  ## Install
48
56
 
@@ -52,34 +60,33 @@ Install from npm:
52
60
 
53
61
  ## Usage
54
62
 
55
- ##### Delegating a task
63
+ `pi-cowboy` activates automatically whenever you run `pi` inside a Git repository.
64
+
65
+ ##### 1. Delegating a task
56
66
 
57
67
  <hr>
58
68
  <code>Based on the security audit, group the relevant files into 10 groups, and launch parallel cowboy agents to address their audit results.</code>
59
-
60
69
  <hr>
61
70
 
62
- pi-cowboy spawns agents for the tasks in the background.
71
+ `pi-cowboy` spawns background agents for the subtasks right away:
63
72
 
64
73
  <code>✓ Spawned agent b7g2nspx (general-purpose)</code><br>
65
74
  <code>✓ Spawned agent 5m1xx7fa (general-purpose)</code><br>
66
75
  <code>...</code>
67
76
 
68
- Depending on your concurrency settings, some of the tasks queue. The default global concurrency is 4, so 6 of them queue and start as soon as a spot opens.
77
+ 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.
69
78
 
70
- ##### Agent isolation
79
+ ##### 2. Agent isolation
71
80
 
72
81
  ![herdr-containers](https://raw.githubusercontent.com/electric-dragon-80000v/pi-cowboy/main/docs/assets/herdr-containers.png)
73
82
 
74
- Each agent runs as a separate pi process in its own Herdr workspace. Open a workspace at any time to monitor the agent or to steer it.
75
-
76
- Three Herdr terms recur below: a **workspace** is the outermost Herdr container and holds tabs, a **tab** holds panes, and a **pane** is one terminal session, the one the agent's pi process runs in. pi-cowboy gives each agent its own workspace and tab, and puts the agent in that tab's root pane. pi-cowboy needs a git repository because each agent works in a worktree of it; outside a repository the extension stays inactive for that session. The pane id is the durable handle `cleanup_cowboy_agent` uses to find that pane again.
83
+ 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.
77
84
 
78
- The agents work in separate git worktrees placed under `<agent dir>/pi-cowboy/worktrees/` (`~/.pi/agent` by default).
85
+ On disk, each agent works in a dedicated Git worktree under `<agent dir>/pi-cowboy/worktrees/` (`~/.pi/agent` by default).
79
86
 
80
- ##### Agent completion
87
+ ##### 3. Agent completion
81
88
 
82
- When an agent settles, its result arrives in the parent session that started it:
89
+ When an agent finishes its turn (settles), its report arrives as a message in the parent session:
83
90
 
84
91
  <code>✓ [Cowboy agent "general-purpose" b7g2nspx completed]</code><br>
85
92
  <br>
@@ -87,26 +94,23 @@ When an agent settles, its result arrives in the parent session that started it:
87
94
  <br>
88
95
  <code>(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.)</code>
89
96
 
90
- The orchestrator then follows your instructions and the agent's report.
97
+ The parent session can then review the report, steer the agent if something needs another pass, or merge the branch.
91
98
 
92
- ##### Merging
99
+ ##### 4. Merging
93
100
 
94
- pi-cowboy calls the `merge_cowboy_branch` tool, which merges the branch in your repository's main working tree:
101
+ To bring the changes in, the orchestrator calls `merge_cowboy_branch`, which merges the agent's branch into your repository's main working tree:
95
102
 
96
103
  <code>✓ Merged "cow-audit-perms-b7g2nspx" into "main" in pi-mono.</code>
97
104
 
98
- ##### Cleanup
105
+ ##### 5. Cleanup
99
106
 
100
- The orchestrator cleans up the branches after merging when your instructions call for it. If it has not, tell it to clean up.
107
+ Once the work is merged, the orchestrator cleans up the agent's resources (or you can ask it to):
101
108
 
102
109
  <hr>
103
110
  <code>Clean up perms audit agent.</code>
104
-
105
111
  <hr>
106
112
 
107
- Clean up comes last. The tool refuses an agent that is still running, removes a branch only once you have merged it, and keeps any worktree that still holds uncommitted changes.
108
-
109
- pi-cowboy calls the `cleanup_cowboy_agent` tool, which removes the agent's artifacts and reports the results:
113
+ `cleanup_cowboy_agent` closes the Herdr pane and tab, removes the worktree, and deletes the branch:
110
114
 
111
115
  <code>✓ Cleaned up agent b7g2nspx:</code><br>
112
116
  <code>agent status: completed</code><br>
@@ -114,184 +118,179 @@ pi-cowboy calls the `cleanup_cowboy_agent` tool, which removes the agent's artif
114
118
  <code>worktree: removed ($HOME/.pi/agent/pi-cowboy/worktrees/cow-audit-perms-b7g2nspx)</code><br>
115
119
  <code>branch: deleted (cow-audit-perms-b7g2nspx)</code>
116
120
 
117
- The `cleanup_cowboy_agent` tool removes the pane, its tab, the worktree, and the branch.
118
- If pi-cowboy cannot remove one of them, it reports the failure and completes the removals it can.
121
+ 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.
119
122
 
120
- ## Commands
123
+ ## Customizing your workflow
124
+
125
+ ### Agent templates
126
+
127
+ 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.
128
+
129
+ For example, a `release-notes` template looks like this:
130
+
131
+ ```toml
132
+ name = "release-notes"
133
+ description = "Prepares release notes."
134
+ system_prompt = '''
135
+ You prepare release notes for this repository. Read the history and tags
136
+ (git log, git tag) and report the changes as a message.
137
+ '''
138
+ ```
139
+
140
+ You can then ask for it by name in the parent session:
141
+
142
+ <hr>
143
+ <code>> Spawn a cowboy agent using release notes template to prepare the release notes for the most recent changes.</code>
144
+ <hr>
145
+
146
+ See [Agent Templates](docs/Agent%20Templates.md) for all template fields and directory locations.
147
+
148
+ ### Orchestrator templates
149
+
150
+ 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.
151
+
152
+ For instance, if you use an adversarial review tool, you can define an orchestrator template that requires every agent to run it before committing:
153
+
154
+ ```toml
155
+ name = "adversarial-review"
156
+ guidance = '''
157
+ Run the adversarial-review tool before you commit, and fix any glaring mistakes that the review finds and then commit.
158
+ '''
159
+ ```
160
+
161
+ You can switch the active orchestrator at any time from `/cowboy` > `Default orchestrator`. See [Orchestrator Templates](docs/Orchestrator%20Templates.md) for details.
121
162
 
122
- `/cowboy` opens a menu. See [Menu](docs/Menu.md).
163
+ ### Foreign harnesses
123
164
 
124
- <code>/cowboy                         # pi-cowboy menu</code><br>
165
+ `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](docs/Configuration.md#agentharnesstype) and [agent templates](docs/Agent%20Templates.md).
125
166
 
126
- <code>/cowboy status                  # List spawned, queued, and settled agents</code><br>
167
+ ## Concurrency
127
168
 
128
- <code>/cowboy spawn                   # Spawn an agent manually</code><br>
169
+ You can cap how many agents run at the same time across four independent levels:
129
170
 
130
- <code>/cowboy worktree                # Create a git worktree with no agent attached</code><br>
171
+ - Global: `concurrency.default` (default `4`), which applies to every agent
172
+ - Per harness: `concurrency.harnesses.<harness-id>`
173
+ - Per provider: `concurrency.providers.<provider>`
174
+ - Per model: `concurrency.models["<provider>/<model-id>"]`
131
175
 
132
- <code>/cowboy model                   # Model selection for the agents</code><br>
176
+ 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.
133
177
 
134
- <code>/cowboy model provider/model-id # Set the model for this session</code><br>
178
+ 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.
135
179
 
136
- <code>/cowboy model clear             # Clear the model set for this session</code><br>
180
+ Configure these limits in `config.json` or live in your session via `/cowboy` > `Settings` > `Concurrency Settings`. See [Configuration](docs/Configuration.md#concurrency) for details.
137
181
 
138
- <code>/cowboy enable                  # Enables pi-cowboy</code><br>
182
+ ## Model resolution
183
+
184
+ When `pi-cowboy` spawns an agent, it picks the model using the first match in this order:
185
+
186
+ 1. The `model` parameter passed to the `cowboy_agent` tool call
187
+ 2. The session per-type model override (`/cowboy` > `Model overrides`)
188
+ 3. The config per-type override (`agent.<agent-type>`)
189
+ 4. The model set in the [agent template](docs/Agent%20Templates.md) for the launching harness family
190
+ 5. The session default model (`/cowboy model`)
191
+ 6. The launching harness's configured default (`agent.default` for the Pi family, or `agent.defaultModelByHarness` for foreign harnesses)
192
+ 7. For Pi-family launches, the parent session's active model
193
+
194
+ See [Configuration](docs/Configuration.md#model-keys) for the full rules.
195
+
196
+ ## Commands
139
197
 
140
- <code>/cowboy disable # Disables pi-cowboy</code>
198
+ Run `/cowboy` to open the interactive menu, or pass a subcommand directly. See [Menu](docs/Menu.md) for a guide to every screen.
199
+
200
+ ```text
201
+ /cowboy # Open the pi-cowboy menu
202
+ /cowboy status # List spawned, queued, and settled agents
203
+ /cowboy spawn # Spawn an agent manually
204
+ /cowboy worktree # Create a git worktree with no agent attached
205
+ /cowboy model # Pick the default agent model for this session
206
+ /cowboy model provider/model-id # Set the default agent model for this session
207
+ /cowboy model clear # Clear the session model override
208
+ /cowboy enable # Enable pi-cowboy
209
+ /cowboy disable # Disable pi-cowboy
210
+ ```
141
211
 
142
212
  ## Tools
143
213
 
144
214
  ### `cowboy_agent`
145
215
 
146
- Delegates one or more tasks to cowboy agents. Each cowboy agent runs in its own pi process and works in its own branch. The call returns immediately, one agent ID per task. Results arrive as a message as each agent settles.
216
+ 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.
147
217
 
148
218
  | Parameter | Required | Description |
149
219
  | ------------------- | -------- | ------------------------------------------------------------------------------------------------ |
150
220
  | `agents[]` | yes | One object per task. |
151
221
  | `run_in_background` | no | Set to `false` to wait for the result in the same turn. Only allowed when `agents` has one task. |
152
222
 
153
- `agents[]`:
223
+ Each item in `agents[]` takes:
154
224
 
155
- | Field | Required | Description |
156
- | -------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
157
- | `prompt` | yes | Task instructions for the cowboy agent. |
158
- | `task_name` | yes | Short 2-3-word name (e.g. "fix login flow") that names the agent's branch, worktree, and tab. |
159
- | `agent_type` | no | Agent type to use. Defaults to the type set at `/cowboy` > `Agent`. |
160
- | `model` | no | Model for this cowboy agent as `"provider/model-id"`. Defaults are resolved in the order under [Model resolution](#model-resolution). |
161
- | `harness_type` | no | Harness that launches this agent: `pi`, `pig`, `pi-bolt`, `opencode`, `codex`, or `claude`. Overrides the agent template's `harness_type` and the `agent.harnessType` setting. If this machine cannot launch the harness, the call fails before anything spawns. |
225
+ | Field | Required | Description |
226
+ | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
227
+ | `prompt` | yes | Task instructions for the cowboy agent. |
228
+ | `task_name` | yes | Short 2-3-word name (e.g. `"fix login flow"`) used to name the agent's branch, worktree, and tab. |
229
+ | `agent_type` | no | Agent template to use. Defaults to the type selected at `/cowboy` > `Agent`. |
230
+ | `model` | no | Model for this agent as `"provider/model-id"`. Resolved according to [Model resolution](#model-resolution). |
231
+ | `harness_type` | no | Harness that launches this agent: `pi`, `pig`, `pi-bolt`, `opencode`, `codex`, or `claude`. Overrides the agent template's `harness_type` and the `agent.harnessType` setting. If this machine cannot launch the requested harness, the call fails before spawning. |
162
232
 
163
233
  ### `steer_cowboy_agent`
164
234
 
165
- Sends a message to one or more agents. `steer_cowboy_agent` revives a settled agent for another turn: the same agent in its pane picks the message up, and you get another completion message when it settles again.
166
- A queued agent cannot be steered, because it has no pane yet. Neither can an agent whose pane is gone (cleaned up), whose id is unknown, or that is being cleaned up.
235
+ 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.
236
+
237
+ 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.
167
238
 
168
239
  | Parameter | Required | Description |
169
240
  | ------------- | -------- | ------------------------------------- |
170
- | `agent_ids[]` | yes | Agent ids to send the message to. |
241
+ | `agent_ids[]` | yes | Agent IDs to send the message to. |
171
242
  | `message` | yes | The message to deliver to each agent. |
172
243
 
173
244
  ### `stop_cowboy_agent`
174
245
 
175
- Stops one or more running agents. The agent's worktree and branch are preserved.
246
+ 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.
176
247
 
177
248
  | Parameter | Required | Description |
178
249
  | ------------- | -------- | ------------------ |
179
- | `agent_ids[]` | yes | Agent ids to stop. |
250
+ | `agent_ids[]` | yes | Agent IDs to stop. |
180
251
 
181
252
  ### `merge_cowboy_branch`
182
253
 
183
- Merges one or more settled agent branches into a target branch in your repository's main working tree. A merge conflict stays in place for you to resolve. The main working tree must be on the target branch and have no uncommitted changes.
254
+ 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.
184
255
 
185
256
  | Parameter | Required | Description |
186
257
  | ------------ | -------- | ------------------------------------------------------------------------------- |
187
- | `branches[]` | yes | The `cow-<task>-<id>` branches from the agent results. |
258
+ | `branches[]` | yes | The `cow-<task>-<id>` branch names from the agent completion reports. |
188
259
  | `target` | no | Branch to merge into. Defaults to `main`. |
189
260
  | `repo` | no | Path inside the repository. Defaults to the parent session's working directory. |
190
261
 
191
262
  ### `cleanup_cowboy_agent`
192
263
 
193
- Removes the pane, its tab, the worktree, and the branch of one or more settled agents.
194
- The tool reports the result for each agent.
264
+ 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.
195
265
 
196
- A removal that fails does not throw. The branch is removed only after you have merged it, and a worktree with uncommitted changes is kept and reported instead of removed.
266
+ 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).
197
267
 
198
268
  | Parameter | Required | Description |
199
269
  | ------------- | -------- | ------------------------------------------------------------------------------------- |
200
- | `agent_ids[]` | yes | Agent ids to clean up. `cleanup_cowboy_agent` refuses an agent that is still running. |
201
-
202
- ## Model resolution
203
-
204
- A model set in the `cowboy_agent` call wins over everything; below it come the session per-type override, the config per-type override, the agent template, the session default, the launching harness's default, and finally, under the pi family, the model of the parent session. The authoritative order is in [Configuration](docs/Configuration.md#model-keys).
205
-
206
- ## Concurrency
207
-
208
- A running agent holds a place in every concurrency limit that applies to it. pi-cowboy releases those places when the agent settles, then the next queued agent starts. You can define concurrency limits as follows:
209
-
210
- - Per model: `concurrency.models["<provider>/<model-id>"]`
211
- - Per provider: `concurrency.providers.<provider>`
212
- - Per harness: `concurrency.harnesses.<harness-id>`
213
- - Global: `concurrency.default` (default `4`), which every agent counts against
214
-
215
- The levels are independent: an agent whose model, provider, and harness all have limits counts against all of them and against the global limit, so you have to free room at every level that applies.
216
- pi-cowboy starts the first waiting agent whose every level has room: an agent that waits for one limit to clear does not hold back an agent behind it.
217
-
218
- An agent with no model selection counts against the global limit alone.
219
-
220
- pi-cowboy floors limits at one, so `0` and a negative number both mean one at a time. See [Configuration](docs/Configuration.md#concurrency).
221
-
222
- A steered agent that settled and starts again is a second live process. It counts against its limits at once, even when it then exceeds a limit. The message is already in the pane of that agent, so its second turn cannot wait for room.
223
-
224
- These settings can be configured via the configuration file or via the menu `/cowboy` > `Settings` > `Concurrency Settings`.
225
-
226
- ## Agent templates
227
-
228
- You can define custom agent templates for tasks that keep coming back and would otherwise make you repeat the same instructions.
229
-
230
- As an example, a release notes template may look like this:
231
-
232
- ```toml
233
- name = "release-notes"
234
- description = "Prepares release notes."
235
- system_prompt = '''
236
- You prepare release notes for this repository. Read the history and tags
237
- (git log, git tag) and report the changes as a message.
238
- '''
239
- ```
240
-
241
- You can then refer to this in the parent session to trigger it:
242
-
243
- <hr>
244
- <code>> Spawn a cowboy agent using release notes template to prepare the release notes for the most recent changes.</code>
245
-
246
- <hr>
247
-
248
- Agent templates have more configuration options. See [Agent Templates](docs/Agent%20Templates.md) for the full list.
249
-
250
- ## Orchestrator templates
251
-
252
- You can define custom orchestrator templates when the same instructions should apply to every agent you spawn, no matter the task.
253
-
254
- If you have an adversarial review tool installed, you can define an "adversarial-review" orchestrator:
255
-
256
- ```toml
257
- name = "adversarial-review"
258
- guidance = '''
259
- Run the adversarial-review tool before you commit, and fix any glaring mistakes that the review finds and then commit.
260
- '''
261
- ```
262
-
263
- You can switch orchestrators during a session at `/cowboy` > `Default orchestrator`. See [Menu](docs/Menu.md).
264
-
265
- Orchestrator templates also allow you to customize how the agent communicates with the orchestrator. See [Orchestrator Templates](docs/Orchestrator%20Templates.md) for more details.
266
-
267
- ### Foreign harnesses
268
-
269
- pi-cowboy can also orchestrate Codex, Claude Code, and OpenCode. It auto-detects them, so you can reference them directly (e.g., "Launch an OpenCode agent for this task") or configure them as defaults in your [settings](docs/Configuration.md#agentharnesstype) and [agent templates](docs/Agent%20Templates.md).
270
+ | `agent_ids[]` | yes | Agent IDs to clean up. `cleanup_cowboy_agent` refuses an agent that is still running. |
270
271
 
271
272
  ## FAQ
272
273
 
273
274
  ### Why is my agent queued, not running?
274
275
 
275
- Every running agent holds a place in every concurrency limit that applies to it: the limit of its model, the limit of its provider, the limit of its harness, and the global limit. Model and provider keys may carry a harness qualifier (`opencode:provider/model`); a bare key names pi's pool. pi-cowboy queues the other agents until every one of those limits has room. Raise the limit in `/cowboy` > `Settings` > `Concurrency Settings`, or in the `concurrency` config keys. See [Concurrency](#concurrency).
276
+ 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](#concurrency).
276
277
 
277
278
  ### Why did my worktree survive cleanup?
278
279
 
279
- `cleanup_cowboy_agent` will not remove a worktree that has uncommitted changes or whose state it cannot read. Commit or discard the changes, stop the agent if it is still running, then call the tool again. See [`cleanup_cowboy_agent`](#cleanup_cowboy_agent).
280
+ `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`](#cleanup_cowboy_agent).
280
281
 
281
282
  ### Isn't one pi process per agent too much overhead?
282
283
 
283
- It can be. For a single small task the overhead can cost more time than the task itself. pi-cowboy is built for many tasks at once, where that overhead is amortized by parallelization.
284
+ 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.
284
285
 
285
- To avoid the overhead, pi-cowboy has support for [pig](https://github.com/MichaelKinsy/PiG), a drop-in replacement for pi written in Go, and for [pi-bolt](https://github.com/opensec-git/Pi-Bolt), faster, lighter Pi variant compiled ahead of time. They start up fast and have a lower memory footprint. See `agent.harnessType` in [Configuration](docs/Configuration.md).
286
+ If you want faster startup and lower memory usage, `pi-cowboy` also supports [pig](https://github.com/MichaelKinsy/PiG) (a drop-in Pi replacement written in Go) and [pi-bolt](https://github.com/opensec-git/Pi-Bolt) (an ahead-of-time compiled Pi variant). Set `agent.harnessType` in [Configuration](docs/Configuration.md) to use them.
286
287
 
287
288
  ### I don't like the emojis, can I turn them off?
288
289
 
289
- Yes. You can disable both the cowboy and the grazing in settings. See [Configuration](docs/Configuration.md).
290
+ Yes. You can disable both the cowboy indicator and the grazing cows in `/cowboy` > `Settings` or in your config file. See [Configuration](docs/Configuration.md).
290
291
 
291
292
  ## References
292
293
 
293
- The settings, screens and template files mentioned above are documented in these four pages.
294
-
295
294
  - [Configuration](docs/Configuration.md)
296
295
  - [Menu](docs/Menu.md)
297
296
  - [Agent Templates](docs/Agent%20Templates.md)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-cowboy",
3
- "version": "0.10.1",
3
+ "version": "0.12.0",
4
4
  "type": "module",
5
5
  "packageManager": "pnpm@12.9.1",
6
6
  "description": "Agent orchestrator for pi: can manage Codex, Claude Code, OpenCode, pi, pig and pi-bolt as subagents. Runs subagents in background Herdr panes, isolated in copy-on-write Git worktrees.",
@@ -62,11 +62,12 @@
62
62
  "commitlint": "commitlint",
63
63
  "release": "semantic-release",
64
64
  "release:stage": "npm stage publish",
65
+ "release:approve": "scripts/publish.sh",
65
66
  "prepare": "husky"
66
67
  },
67
68
  "pi": {
68
69
  "image": "https://raw.githubusercontent.com/electric-dragon-80000v/pi-cowboy/main/docs/assets/logo-pi-package-landscape.png",
69
- "video": "https://raw.githubusercontent.com/electric-dragon-80000v/pi-cowboy/main/docs/assets/pi-cowboy-ad-trimmed.mp4",
70
+ "video": "https://raw.githubusercontent.com/electric-dragon-80000v/pi-cowboy/main/docs/assets/pi-cowboy.mp4",
70
71
  "extensions": [
71
72
  "./dist/index.js"
72
73
  ]
@@ -96,7 +97,7 @@
96
97
  "eslint-plugin-import-x": "^4.17.1",
97
98
  "husky": "^9.1.7",
98
99
  "oxlint": "1.87.0",
99
- "oxlint-tsgolint": "7.0.2003",
100
+ "oxlint-tsgolint": "7.0.2004",
100
101
  "prettier": "^3.9.9",
101
102
  "semantic-release": "^25.0.9",
102
103
  "typescript": "npm:@typescript/typescript6@^6.0.2",