baro-ai 0.81.7 → 0.81.8

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 +131 -380
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -24,60 +24,55 @@ baro "Add JWT authentication with role-based access control"
24
24
 
25
25
  <sub>baro at the end of an [actual run](https://jigjoy.ai/blog/baro-808-nestjs-jest-tests) — one prompt → 33-story DAG → 32 files modified → PR opened. The summary panel shows wall time, parallel speedup (2.2×), token usage, and the PR URL.</sub>
26
26
 
27
- ## What you actually get
28
-
29
- You write one sentence. baro does the rest:
30
-
31
- - **You describe the goal** — a conversation agent either confirms the scope or asks only the questions that materially change it.
32
- - **An Architect pins the design** — file paths, schemas, API shapes, library choices — so dozens of agents don't each invent their own.
33
- - **A Planner splits it into a DAG of stories** — with dependencies, so independent work runs at the same time.
34
- - **A fleet of agents builds it in parallel** — not one chat agent typing for an hour, dozens, each in its own isolated git branch.
35
- - **It reviews and repairs itself** — a tool-less Critic gates supported routes and corrects live workers on failure; a Surgeon replans stories that get stuck.
36
- - **You get a pull request** — build-verified, with a stories table and run stats.
27
+ ## What happens when you run it
37
28
 
38
29
  ```mermaid
39
30
  flowchart LR
40
- Goal([your goal]) --> C[Conversation<br/><sub>clarifies intent<br/>when needed</sub>]
41
- C --> R[RepoScout<br/><sub>autonomous read-only<br/>research</sub>]
42
- R --> C
43
- C --> K[Candidate<br/>GoalEnvelope]
44
- K --> A[Architect<br/><sub>validates repository<br/>and pins decisions</sub>]
45
- A -. material question .-> C
46
- A --> G[Validated<br/>GoalEnvelope]
47
- G --> P[Planner<br/><sub>emits story DAG</sub>]
48
- P --> S1[Story 1]
49
- P --> S2[Story 2]
50
- P --> S3[Story 3]
51
- S1 --> S4[Story 4]
52
- S2 --> S4
53
- S3 --> S5[Story 5]
54
- S4 --> F[Finalizer<br/><sub>opens PR</sub>]
55
- S5 --> F
56
- F --> PR([Pull Request])
31
+ G([your goal]) --> C[Conversation<br/><sub>asks only what matters</sub>]
32
+ C --> A[Architect<br/><sub>pins the design</sub>]
33
+ A --> P[Planner<br/><sub>splits into a story DAG</sub>]
34
+ P --> S[Story agents<br/><sub>parallel, isolated worktrees</sub>]
35
+ S --> V[Critic + Verifier<br/><sub>reviews, repairs, tests</sub>]
36
+ V --> PR([Pull Request])
57
37
  ```
58
38
 
59
- ## Why it's fast: a real fleet, not one chat agent
39
+ 1. **You describe the goal.** A conversation agent confirms the scope, or asks only the questions that would change it.
40
+ 2. **The Architect pins the design** — file paths, schemas, API shapes, library choices — so dozens of agents don't each invent their own.
41
+ 3. **The Planner splits it into a DAG of stories**, with dependencies, so independent work can run at the same time.
42
+ 4. **A fleet of agents builds it**, each in its own git worktree — not one chat agent typing for an hour.
43
+ 5. **It reviews and repairs itself.** A tool-less Critic gates each story; a Surgeon replans the ones that get stuck.
44
+ 6. **You get a pull request**, build-verified, with a stories table and run stats.
60
45
 
61
- Most tools give you a single agent in a chat box. baro plans your goal into a DAG and
62
- runs a whole fleet at once — every independent story is scheduled in parallel in its
63
- own git worktree. CLI routes use subprocesses, while native OpenAI-compatible routes
64
- run in-process:
46
+ The speedup scales with the width of your DAG, not the patience of a single session.
47
+
48
+ ## Quick start
65
49
 
66
50
  ```bash
67
- cd your-repo
68
- baro "Add JWT authentication with role-based access control"
69
- ```
51
+ npm install -g baro-ai
70
52
 
53
+ baro "Migrate the hardcoded category data to a backend dictionary"
54
+
55
+ baro --quick "fix the typo on line 42 of README.md" # skip Architect/Critic/Surgeon
56
+ baro --parallel 3 "Add unit tests for the auth module"
57
+ baro --local-only "Your goal" # no pushes, no PR
58
+ baro --resume # pick up an existing prd.json
59
+ baro --continue "…and add refresh tokens" # follow-up onto the same PR
60
+ baro --doctor # self-diagnostic
71
61
  ```
72
- → Architect (45s) — design decisions pinned for every story
73
- → Planner (38s) — 7 stories in 3 levels
74
- → Executing — 4 parallel agents on baro/jwt-auth branch
75
- → Critic — per-turn acceptance evaluation, self-corrects on fail
76
- → Finalizer — PR #142 opened ✓
77
- ```
78
62
 
79
- That parallelism is where the 2.2× speedup in the run above comes from — and it scales
80
- with the width of your DAG, not the patience of a single session.
63
+ Full options, `.barorc` config and per-phase overrides: [**docs.baro.rs**](https://docs.baro.rs).
64
+
65
+ ## Execution modes
66
+
67
+ `--mode` decides how much runs at once. The default asks the intake to propose one and
68
+ lets you confirm it.
69
+
70
+ | mode | what it does |
71
+ |---|---|
72
+ | `auto` *(default)* | intake proposes a mode from the goal; you confirm |
73
+ | `focused` | a single story, start to finish |
74
+ | `sequential` | one story at a time, in dependency order |
75
+ | `parallel` | every ready story at once, up to `--parallel` |
81
76
 
82
77
  ## Use any model — or mix them
83
78
 
@@ -86,82 +81,51 @@ each agent talks to. Auth inherits from whichever CLI you already have signed in
86
81
  key plumbing for the subscription backends.
87
82
 
88
83
  ```bash
89
- baro --llm claude "Your goal" # default — Claude Code on Anthropic Max subscription
90
- baro --llm codex "Your goal" # Codex CLI for every phase, including isolated evidence review
91
- baro --llm codex --critic-llm claude "Your goal" # Codex execution + tool-less Claude review
92
- baro --llm openai "Your goal" # Mozaik-native OpenAI (per-call API billing)
93
- baro --llm opencode "Your goal" # OpenCode CLI — multi-provider agent shell (any model)
94
- baro --llm hybrid "Your goal" # Claude on Architect/Planner/Critic/Surgeon, Codex on Story
84
+ baro --llm claude "Your goal" # default — Claude Code on an Anthropic Max subscription
85
+ baro --llm codex "Your goal" # Codex CLI on a ChatGPT Plus/Pro subscription
86
+ baro --llm opencode "Your goal" # OpenCode CLI — multi-provider agent shell
87
+ baro --llm openai "Your goal" # native OpenAI-compatible API (per-call billing)
88
+ baro --llm hybrid "Your goal" # Claude plans and reviews, Codex writes
89
+ baro --llm jigjoy "Your goal" # hosted baro gateway — we hold the upstream keys
95
90
  ```
96
91
 
97
- `--llm hybrid` is the recommendation for serious runs — Claude for planning,
98
- tool-less review, and recovery; Codex for parallel story work. A pure Codex run
99
- reviews only Baro-captured evidence in an isolated least-privilege process. Each phase
100
- also has its own override flag if you want to mix it yourself:
92
+ `--llm hybrid` is the recommendation for serious runs. `--llm jigjoy` needs no provider
93
+ account at all — run `baro login` once and phases route through the hosted gateway.
94
+
95
+ Every phase also has its own override:
101
96
 
102
97
  ```bash
103
- baro --architect-llm claude \
104
- --planner-llm claude \
105
- --story-llm opencode \
106
- --critic-llm claude \
107
- --surgeon-llm claude \
98
+ baro --architect-llm claude --planner-llm claude \
99
+ --story-llm opencode --critic-llm claude --surgeon-llm claude \
108
100
  "Your goal"
109
101
  ```
110
102
 
111
103
  ### Custom OpenAI-compatible endpoints
112
104
 
113
- Any provider that exposes an OpenAI-compatible Chat Completions API works with `--llm openai`.
114
- Set `OPENAI_BASE_URL` to point at your endpoint and pass any model name via `--story-model`:
105
+ Anything speaking OpenAI **Chat Completions** works with `--llm openai`. Point
106
+ `OPENAI_BASE_URL` at it and pass any model name:
115
107
 
116
108
  ```bash
117
- # Xiaomi MiMo
118
- OPENAI_API_KEY=your-key OPENAI_BASE_URL=https://api.mimo.xiaomi.com/v1 \
119
- baro --llm openai --story-model MiMo-7B-RL "Your goal"
120
-
121
- # OpenRouter (any model)
122
109
  OPENAI_API_KEY=your-key OPENAI_BASE_URL=https://openrouter.ai/api/v1 \
123
110
  baro --llm openai --story-model anthropic/claude-3.5-sonnet "Your goal"
124
111
 
125
- # Local vLLM / Ollama
126
112
  OPENAI_API_KEY=not-needed OPENAI_BASE_URL=http://localhost:11434/v1 \
127
113
  baro --llm openai --story-model llama3 "Your goal"
128
114
  ```
129
115
 
130
- The `--openai-base-url` flag also works (wins over the env var when both are set).
131
-
132
- ### OpenCode (multi-provider agent shell)
133
-
134
- [OpenCode](https://opencode.ai) is an open-source coding agent that supports any LLM provider.
135
- With `--llm opencode`, baro delegates story execution to the `opencode` CLI. Model selection
136
- uses the `-m provider/model` format:
137
-
138
- ```bash
139
- baro --llm opencode -m anthropic/claude-sonnet-4 "Your goal" # Claude via OpenCode
140
- baro --llm opencode -m openai/gpt-4o "Your goal" # OpenAI via OpenCode
141
- baro --llm opencode -m lmstudio/qwen3-coder "Your goal" # local model
142
-
143
- # Mix: Claude plans, OpenCode executes stories.
144
- baro --architect-llm claude --planner-llm claude \
145
- --story-llm opencode "Your goal"
146
- ```
147
-
148
- OpenCode manages its own API keys and per-provider model defaults via `opencode providers` —
149
- no extra env vars, and no `-m` required when you're happy with its default. `-m provider/model`
150
- sets the model for **all** phases at once, so use it only when every phase runs on a non-Claude
151
- backend. Runs with `--dangerously-skip-permissions` for unattended execution in baro's per-story
152
- worktrees.
116
+ `--openai-base-url` does the same and wins over the env var.
153
117
 
154
- Full breakdown at [docs.baro.rs/llm-providers](https://docs.baro.rs/llm-providers) — provider
155
- economics, per-phase routing, and the side-by-side benchmark across three real tasks:
156
- [**I tested Claude Code vs OpenAI Codex in my parallel agent setup. Then I built a hybrid.**](https://jigjoy.ai/blog/claude-code-vs-codex-baro)
118
+ > **Gotcha.** Model names matching `gpt-*`, `o1`–`o9`, `chatgpt-*`, `text-*` or `davinci*`
119
+ > are treated as native OpenAI and go to the **Responses API** (`POST /v1/responses`),
120
+ > not Chat Completions (`POST /v1/chat/completions`) — two different wire protocols.
121
+ > Setting `OPENAI_BASE_URL` alone does not change that. Pass `--openai-base-url`
122
+ > explicitly and you get Chat Completions regardless of the model name.
157
123
 
158
- ### Per-story model tiering (mixed fleet)
124
+ ### Per-story model tiering
159
125
 
160
- `--llm` / `--story-llm` pick a backend per *phase* — every story runs on the same one. With
161
- `--tier-map` you tier per *story* instead: the Planner tags each story with a blast-radius tier
162
- (`light` = mechanical/self-contained, `standard` = one contained module, `heavy` = cross-cutting /
163
- schema / a DAG hub — "what breaks if an agent gets this wrong?"), and the tier map binds each
164
- tier to a concrete `backend:model`. One DAG, several backends, chosen by risk:
126
+ `--llm` picks a backend per *phase*. `--tier-map` tiers per *story* instead: the Planner
127
+ tags each story by blast radius — `light` (mechanical), `standard` (one module), `heavy`
128
+ (cross-cutting, schema, a DAG hub) — and the map binds each tier to a `backend:model`.
165
129
 
166
130
  ```bash
167
131
  # Cheap single-concern stories on MiniMax, cross-cutting stories on Claude Opus
@@ -170,338 +134,125 @@ baro --openai-endpoint minimax=https://api.minimax.io/v1 \
170
134
  "Your goal"
171
135
  ```
172
136
 
173
- Tiers are a blast-radius class, not a model: a `heavy` story may well run on DeepSeek or GPT —
174
- whatever its route says. The legacy tier spellings `haiku`/`sonnet`/`opus` are still accepted
175
- everywhere a tier can appear (story `model` fields, `--tier-map` keys, `BARO_TIER_MAP`), so old
176
- PRDs and maps keep working unchanged.
137
+ A route can name any backend (`claude:opus`, `openai:MiniMax-M3`, `codex:gpt-5.5`), and an
138
+ OpenAI route can name its own endpoint with `@` — so one run can hit several endpoints at
139
+ once. Keys never go on the command line: each endpoint reads `BARO_OPENAI_KEY_<NAME>`,
140
+ falling back to `OPENAI_API_KEY`.
177
141
 
178
- A story's route can name **any** backend (`claude:opus`, `openai:MiniMax-M3`, `codex:gpt-5.5`) and
179
- an OpenAI route can name its **own endpoint** with `@` — a registered name (`--openai-endpoint
180
- name=url`, repeatable) or an inline `@https://…` URL — so a single run can hit several
181
- OpenAI-compatible endpoints at once. API keys are never put on the command line: each endpoint
182
- resolves its key from `BARO_OPENAI_KEY_<NAME>`, falling back to `OPENAI_API_KEY`. When the Surgeon
183
- splits a failed story, it tiers the pieces and escalates a tier up for any same-scope replacement.
184
- Without `--tier-map`, per-story tiers resolve on the phase backend exactly as before.
142
+ Provider economics and a side-by-side benchmark across three real tasks:
143
+ [**Claude Code vs OpenAI Codex in my parallel agent setup**](https://jigjoy.ai/blog/claude-code-vs-codex-baro).
185
144
 
186
145
  ## Under the hood: participants on an event bus
187
146
 
188
- Most multi-agent setups have one orchestrator function in the middle that drives N agents. The
189
- orchestrator becomes the bottleneck the moment you push past a handful of concurrent agents — and
190
- adding a new behaviour means editing its control flow.
191
-
192
- Every new run starts with a durable conversation session. Goal and clarification
193
- turns first enter a short-lived pre-PRD Mozaik environment: Conversation requests
194
- a bounded repository brief over semantic events, and a Baro-owned `RepoScout`
195
- first builds a deterministic snapshot, then autonomously chooses bounded
196
- `read_file`, literal `grep`, or `glob` observations until it can finish a
197
- structured evidence brief. Baro, not the model, executes those shell-free
198
- tools; observed symlinks, known credential/key/cloud-state paths, generated work
199
- directories, binary files and configured work/byte limits are excluded. On
200
- success, the brief identity hashes the exact bootstrap projection and ordered
201
- observation suffix visible in the finishing policy call, including its omission
202
- count; it identifies the evidence set, not the semantic truth of model-authored text.
203
- Clipped bootstrap paths are not trusted until Scout rediscovers them, and an
204
- omitted observation suffix forces an explicitly truncated result.
205
- This is a capability boundary, not a proof that model-authored summaries or
206
- questions are immune to repository prompt injection; they remain untrusted model output.
207
- Fact paths require bootstrap/read/search provenance, and an optional source line
208
- must have been visibly returned by read/search. A malformed decision receives a
209
- bounded same-step repair, while Scout provider failure performs a final stability
210
- rescan and falls back to the latest deterministic snapshot so Conversation can
211
- still be attempted; Conversation itself still requires the selected provider.
212
- RepoScout and the provider-facing Conversation model run as
213
- separate roles in an empty temporary harness directory. They default to the
214
- same selected backend/model, but use independent provider-neutral seams so the
215
- Scout can later be routed to a cheaper model. Claude, OpenCode and Pi receive
216
- explicit no-tool profiles. Codex runs with a strict least-privilege permission
217
- profile: its empty workspace is denied, tool network and inherited shell
218
- environment are disabled, and user/project config and rules are ignored. Large
219
- Claude/Codex prompt payloads travel over stdin instead of argv for Windows-safe
220
- launches. Repository
221
- observations remain explicitly untrusted data; neither role can choose workers,
222
- routes, leases or DAG mutations. Chat turns also request context because a chat
223
- response may identify a new implementation follow-up and return `ready`.
224
-
225
- A `ready` GoalEnvelope is only a candidate. Every provider route runs a
226
- pre-acceptance Architect validation before the durable session accepts it. The
227
- Claude Code, Codex and native OpenAI-compatible routes can inspect the checkout
228
- with repository read-only capabilities. OpenCode and Pi have no equivalent
229
- repository read-only CLI profile, so their pre-acceptance Architect runs as an
230
- inference-only evaluator in an empty directory and receives only Baro's bounded,
231
- brokered repository context. The Architect may return repository-cited questions;
232
- when it returns `ready`, the same validated decision document is reused by Planner,
233
- so there is no second Architect charge. Quick mode keeps its existing single-story
234
- Architect skip.
235
-
236
- The pre-acceptance Codex Architect keeps the checkout as its read-only working
237
- root so its normal search tools can investigate it, but starts with strict CLI
238
- config and `project_doc_max_bytes=0`. This prevents repository-owned
239
- `AGENTS.md`/project documents from becoming model instructions before the goal
240
- is trusted; their contents remain ordinary repository evidence if Codex
241
- explicitly reads them during investigation.
242
-
243
- The broker rejects symlinks it observes, but a concurrently hostile checkout can
244
- still race path checks. Use a disposable, remote-free immutable clone when hard
245
- filesystem isolation is required.
246
-
247
- The execution runtime then uses one shared event bus
248
- ([Mozaik](https://github.com/jigjoy-ai/mozaik)). Its Board/Conductor, factories, critics and
249
- other observers are participants; N parallel story agents are N independently scheduled
250
- executions whose activity is projected onto typed events. CLI routes use subprocesses and a
251
- local bridge, while native OpenAI-compatible routes run in-process. Architect and Planner run
252
- before this execution environment. The default `collective` engine splits
253
- allocation, leases, integration and completion across participants and lets workers publish peer
254
- messages and propose versioned changes to planned future work. The Board validates and
255
- persists the complete candidate before it reports the change as applied. Offered-but-unleased
256
- work can move only after the Broker atomically retracts the exact offer; leased, integrating,
257
- reviewing, recovery and cleanup work remains fenced. `legacy` remains as the explicit
258
- Conductor compatibility path for old-run comparison and rollback.
259
-
260
- Collective messages also carry execution authority: trusted participants submit
261
- intents to the run-local Bridge, which binds them to the recipient's current
262
- run/lease/generation. All Claude Code, Codex, OpenCode, Pi, and native OpenAI
263
- story adapters reject direct or stale deliveries. Supervisor, Librarian, and
264
- Dialogue observations are likewise tied to exact Broker/worker/control-plane
265
- sources, so a same-label bus participant cannot transitively steer a worker.
266
-
267
- Fresh headless Collective runs also have an experimental progressive-planning
268
- path. With `BARO_PROGRESSIVE_PLANNING=1`, a native OpenAI-compatible Planner
269
- (including GLM on that route) may publish dependency-closed, add-only story
270
- fragments through Mozaik while it continues planning. The Board validates and
271
- durably admits each fragment before it can execute, and the final PRD must keep
272
- the admitted stories as an exact prefix. Claude Code and Codex Planners expose
273
- the same fragment capability through an isolated run-scoped stdio MCP bridge;
274
- OpenCode and Pi Planners remain final-only. Resume and follow-up runs are not
275
- eligible for this version; interactive and `legacy` runs are unchanged. See
276
- [Collective runtime architecture](docs/collective-runtime.md#progressive-planning-experimental-opt-in)
277
- for the fail-closed lifecycle, limitations and provider-free checks. This
278
- opt-in is an evaluation surface, not a production-readiness or benchmark claim.
279
-
280
- Try the collective engine with Baro-owned pushes and PR creation disabled:
281
-
282
- ```bash
283
- baro --local-only "Your goal"
284
- ```
147
+ Most multi-agent setups put one orchestrator function in the middle driving N agents. That
148
+ orchestrator becomes the bottleneck the moment you go past a handful of concurrent agents,
149
+ and every new behaviour means editing its control flow.
285
150
 
286
- In collective mode, the same user-facing session also has a run-local
287
- `DialogueAgent` on the bus:
288
-
289
- ```bash
290
- baro --local-only "Your goal"
291
- ```
292
-
293
- It is text-only, receives no repository tools, and cannot grant leases, mutate
294
- the DAG directly, integrate work, verify the run, or report success. It may
295
- explain the bounded run projection, message an active worker, or submit a
296
- versioned add-only proposal that the Board independently validates. Removing it
297
- does not stop the collective. While a run is active, press `c` for collective chat;
298
- `m` still sends a direct message to the selected worker. Direct/headless
299
- clients can use the `dialogue_message` stdin event. Local Claude Code and Codex
300
- runs pass continuity through a PRD-bound, size-limited temporary snapshot that
301
- is deleted when the orchestrator exits; the transcript is not copied into the
302
- repository.
303
-
304
- Use `--coordination legacy` only when you explicitly want the earlier Conductor
305
- compatibility path.
306
- For hard network isolation, point it at a disposable clone with its git remotes removed;
307
- story agents can execute shell commands, so `--local-only` is a coordinator policy, not an OS sandbox.
308
-
309
- Collective mode can also run an opt-in worker market. Candidate workers advertise safe route
310
- descriptors and submit bounded cost/latency/success estimates; the Broker applies policy and picks
311
- one winner deterministically. Credentials and endpoint URLs remain local to the worker. The
312
- estimates are configuration until they have been calibrated from externally verified runs — they
313
- are not presented as measured truth. See the [local collective experiment](docs/collective-experiment.md)
314
- and [candidate example](docs/collective-workers.example.json).
151
+ baro has no such function. Every role is a participant on a shared event bus
152
+ ([Mozaik](https://github.com/jigjoy-ai/mozaik)), reacting to typed events:
315
153
 
316
154
  ```mermaid
317
155
  flowchart LR
318
- subgraph A["Typical multi-agent orchestrator"]
156
+ subgraph A["Typical orchestrator"]
319
157
  direction TB
320
158
  C{{Coordinator}}
321
159
  C --> A1[Agent 1]
322
160
  C --> A2[Agent 2]
323
161
  C --> A3[Agent N]
324
162
  end
325
- subgraph B["baro domain authorities on Mozaik"]
163
+ subgraph B["baro on Mozaik"]
326
164
  direction TB
327
165
  Bus[(shared event bus)]
328
- P1[Conductor or Board + Broker] -.-> Bus
166
+ P1[Board + Broker] -.-> Bus
329
167
  P2[Story Agent 1] -.-> Bus
330
168
  P3[Story Agent N] -.-> Bus
331
- P4[Critic / Surgeon / ...] -.-> Bus
169
+ P4[Critic / Surgeon / …] -.-> Bus
332
170
  end
333
171
  ```
334
172
 
335
173
  | Participant | Role |
336
174
  |---|---|
337
- | **Architect** | One strong-model design pass before planning — for read-only-capable routes it first validates the candidate goal and may return repository-cited questions; its accepted `DecisionDocument` is reused by Planner without a second call |
338
- | **Planner** | Decomposes the goal into a story DAG, with the DecisionDocument already pinned |
339
- | **Conversation session** | Durable first contact and sole user-facing intake authority: clarifies intent, persists a repository-scoped correlated transcript across pre-PRD restarts, and hands exactly one accepted GoalEnvelope to planning |
340
- | **RepoScout** | Source-bound autonomous researcher in the short-lived pre-PRD Mozaik lane. It iteratively chooses from Baro-owned read/search/glob capabilities and returns a frozen 64 KiB evidence brief; deterministic retrieval remains its bootstrap and fail-safe. It cannot plan, route work, mutate the DAG, run code, use the network, or write the checkout |
341
- | **Conductor** | Explicit `legacy` compatibility state machine that drives DAG levels by reacting to bus events |
342
- | **Board + Broker** | Default collective policy: Board remains the deterministic scheduler and durable graph-transaction arbiter; Broker independently auctions and grants correlated leases. Offered work requires a Broker retraction ACK before reorganization, and process exit is never proof of success |
343
- | **GoalGuardian** | Independent goal-semantic authority: projects the accepted GoalContract, accepts source-bound invariant challenges, proposes corrective stories, and attests completion from durable integration plus exact lease-correlated quality evidence. It cannot schedule, lease, merge or mutate the DAG |
344
- | **DialogueAgent** | Automatic collective participant that continues the bounded conversation during a run and may submit Bridge-routed messages or Board-validated add-only proposals from an exact source-bound observation set, but has no control-plane authority |
345
- | **StoryAgent** | One isolated worker per story and git worktree. Native OpenAI runs in-process through Mozaik; Claude Code is a multi-turn CLI worker, while Codex, OpenCode and Pi story workers are currently one-shot CLI processes |
346
- | **Critic + AcceptanceGate** | Evaluates terminal output against acceptance criteria. Live backends can consume corrective turns; one-shot backends produce a blocking verdict that triggers recovery instead of a message to a dead process |
347
- | **Sentry** | Flags overlapping Edit/Write tool calls across concurrent stories |
348
- | **CollaborationBridge** | Issues an opaque loopback endpoint/token capability for one exact run/story/lease/generation, routes trusted peer events, and revokes all ordinary influence at lease release; no worker sees its manager-private session state |
349
- | **Librarian** | Indexes exact active-worker Read/Grep findings so siblings don't redo the exploration; forged or stale tool output cannot enter shared context |
350
- | **Supervisor** | Independently detects non-converging active workers and may request only an exact lease-correlated abort; it does not schedule recovery |
351
- | **Surgeon** | On execution, integration or acceptance failure, proposes a bounded replan (split / prerequisite / rewire / escalation) |
352
- | **RunVerifier / Finalizer** | Produces correlated build/test evidence for collective completion; optional publishing reuses that evidence when opening the PR |
353
-
354
- In collective mode, an active leased worker may propose an atomic change to
355
- the not-yet-started part of the story DAG. Native OpenAI receives a
356
- closed-schema `propose_replan` tool inside its Mozaik inference loop; CLI
357
- workers use the same correlated semantic events through the local
358
- `agent-collab.mjs` helper and a short-lived loopback capability. Claude and
359
- native OpenAI receive messages live; messages known before launch enter every
360
- backend's initial prompt exactly once, while later messages for one-shot Codex,
361
- OpenCode and Pi workers are consumed through their capability inbox. The Board remains the only mutation authority and
362
- emits `runtime_replan_applied` only after the new graph and version are
363
- durable. See [the local collective experiment guide](docs/collective-experiment.md#runtime-dag-adaptation)
364
- for the safety and replay contract.
365
-
366
- The bus is open. CI deployers, Slack notifiers, ticket triggers — all new participants, no
367
- orchestrator changes. Architecture deep-dive:
368
- [I tested Claude Code's new /goal feature against my parallel agent setup](https://jigjoy.ai/blog/baro-vs-claude-code).
369
-
370
- ## Semantic memory (cross-agent context sharing)
371
-
372
- baro includes an optional semantic memory system that lets parallel story agents share discoveries
373
- in real time. When one agent reads a file or greps a pattern, the finding is embedded (CPU-only
374
- ONNX, no API calls) and stored in a local [Vectra](https://github.com/stevenic/vectra) vector index
375
- on disk. Other agents query this shared memory mid-flight, so siblings don't redo the same
376
- exploration — roughly 50% fewer findings injected, because only semantically relevant ones surface.
377
-
378
- ```
379
- Collective manager Story Agents (parallel)
380
- ────────────────── ──────────────────────
381
- intercepts authenticated tool output receive relevant context at launch
382
- → embeds via ONNX MiniLM → share explicit notes through their
383
- → indexes in manager-private memory lease-bound collaboration capability
384
- → injects only relevant findings → never receive an index/session path
385
- ```
175
+ | **Conversation** | Sole user-facing intake; turns a sentence into one accepted goal, and survives restarts |
176
+ | **RepoScout** | Read-only researcher that investigates the repo before planning; cannot run code or write |
177
+ | **Architect** | One strong-model design pass; its decisions are pinned for every story |
178
+ | **Planner** | Decomposes the goal into a story DAG |
179
+ | **Board + Broker** | Scheduling and ownership: the Board arbitrates the graph, the Broker auctions and grants leases |
180
+ | **StoryAgent** | One isolated worker per story, in its own git worktree |
181
+ | **Critic + AcceptanceGate** | Evaluates each story against its acceptance criteria and blocks or corrects |
182
+ | **GoalGuardian** | Independent goal authority — attests completion from evidence; cannot schedule or merge |
183
+ | **Surgeon** | Replans a failed story: split, add a prerequisite, rewire, or escalate |
184
+ | **Librarian + Sentry** | Share findings between siblings; flag overlapping edits across concurrent stories |
185
+ | **RunVerifier / Finalizer** | Produces build/test evidence and opens the PR from it |
186
+
187
+ Because it's a bus, adding a participant — a CI deployer, a Slack notifier, a ticket
188
+ trigger — changes no existing code. Workers can also message each other and propose
189
+ changes to not-yet-started parts of the DAG; the Board stays the only thing allowed to
190
+ mutate it.
191
+
192
+ **Details:** [collective runtime architecture](docs/collective-runtime.md) covers the
193
+ execution guarantees, lease and authority fencing, failure policy, runtime DAG changes,
194
+ progressive planning, and the provider-free verification contract. The
195
+ [local collective experiment](docs/collective-experiment.md) is the hands-on guide.
196
+
197
+ ## Semantic memory
198
+
199
+ Parallel agents share what they discover. When one reads a file or greps a pattern, the
200
+ finding is embedded locally (CPU-only ONNX, no API calls) and indexed, so siblings don't
201
+ redo the same exploration — only semantically relevant findings get injected.
386
202
 
387
203
  ```bash
388
- baro "your goal" # memory enabled by default
389
- baro --no-memory "goal" # disable (falls back to tag-based Librarian)
390
- BARO_DEBUG=memory baro ... # debug logging to stderr + ~/.baro/runs/memory-*.log
391
- ```
392
-
393
- **Helps most:** large codebases (20+ files) with overlapping exploration, staggered DAGs where
394
- later stories benefit from earlier ones, runs with 5+ stories touching the same subsystems.
395
- **Adds slight overhead with no benefit:** small codebases (1–3 files), fully parallel DAGs with no
396
- dependencies, quick single-story tasks (`--quick`). It adds ~1s startup (ONNX model load).
397
- Collective memory is run-local and manager-private. Legacy mode may persist its index under an
398
- explicit run-scoped `~/.baro/sessions/.../memory/` path for the legacy CLI; Baro never installs that
399
- path into the process-global `BARO_MEMORY_PATH` environment.
400
-
401
- ## Try it
402
-
403
- ```bash
404
- npm install -g baro-ai
405
-
406
- # Full run (default — Claude on every phase via Claude Code CLI)
407
- baro "Migrate the hardcoded category data to a backend dictionary"
408
-
409
- # Trivial goal — skip Architect + Critic + Surgeon, single story
410
- baro --quick "fix the typo on line 42 of README.md"
411
-
412
- # Codex everywhere (ChatGPT Pro/Plus subscription, ~3-11× cheaper per run than Claude)
413
- baro --llm codex "Refactor the database layer"
414
-
415
- # Per-phase routing — Claude upstream (tight plans), Codex downstream (cheap writes)
416
- baro --llm hybrid "Add WebSocket support across api and frontend"
417
-
418
- # Route every phase through GPT-5.5 (Mozaik-native OpenAI API)
419
- OPENAI_API_KEY=sk-... baro --llm openai "Refactor the database layer"
420
-
421
- # Route through any OpenAI-compatible endpoint (Xiaomi MiMo, OpenRouter, vLLM, Ollama, etc.)
422
- OPENAI_API_KEY=your-key OPENAI_BASE_URL=https://api.mimo.xiaomi.com/v1 baro --llm openai "Refactor the database layer"
423
-
424
- # Limit parallelism (plan-tier concurrency caps)
425
- baro --parallel 3 "Add unit tests for the auth module"
426
-
427
- # Dry-run first, execute later
428
- baro --dry-run "Add WebSocket support"
429
- baro --resume
430
-
431
- # Self-diagnostic
432
- baro --doctor
204
+ baro "your goal" # on by default
205
+ baro --no-memory "goal" # off
206
+ BARO_DEBUG=memory baro … # debug to stderr + ~/.baro/runs/memory-*.log
433
207
  ```
434
208
 
435
- Full options + `.barorc` config + per-phase model overrides: [**docs.baro.rs**](https://docs.baro.rs).
209
+ Worth it on large codebases with overlapping exploration and DAGs where later stories
210
+ build on earlier ones. Adds ~1s of startup and little else on 1–3 file tasks.
436
211
 
437
212
  ## Run it from the cloud — `baro connect`
438
213
 
439
- baro can also run as a **remote runner** for baro-cloud: fire a goal from a web
440
- dashboard, a teammate, or a GitHub issue labeled `baro`, and it executes here on
441
- your machine over your own subscription — your code never leaves it. baro-cloud
442
- orchestrates (Architect/Planner/Critic/Surgeon) and never sees your source, only
443
- metadata + diffs. Pair a machine with one line:
214
+ baro can run as a **remote runner**: fire a goal from a web dashboard, a teammate, or a
215
+ GitHub issue labeled `baro`, and it executes here on your machine over your own
216
+ subscription. baro-cloud orchestrates and never sees your source — only metadata and diffs.
444
217
 
445
218
  ```bash
446
219
  curl -fsSL https://api.baro.jigjoy.ai/install.sh | sh -s -- --token rt_…
447
220
  ```
448
221
 
449
- That installs baro and registers a background **service** that survives terminal
450
- close, logout, and reboot — launchd (macOS), systemd (Linux), or a logon task
451
- (Windows). Or do it by hand:
222
+ That installs baro and registers a background service that survives terminal close,
223
+ logout and reboot — launchd, systemd, or a Windows logon task. By hand:
452
224
 
453
225
  ```bash
454
226
  baro connect --install-service --token rt_… # persistent background service
455
227
  baro connect --token rt_… # foreground, this terminal only
456
- baro connect --uninstall-service # remove the service
228
+ baro connect --uninstall-service # remove it
457
229
  ```
458
230
 
459
- Get a pairing token (`rt_…`) from baro-cloud → Runners. A mid-run network blip
460
- won't kill a run: the runner reconnects and resumes streaming where it left off.
461
-
462
- **No machine or subscription?** baro-cloud can also run a goal entirely on
463
- **baro's cloud** — each run executes in an isolated sandbox on our infrastructure,
464
- billed from prepaid credits. Pick **☁ baro's cloud** in the dashboard (no runner
465
- to pair) at [app.baro.jigjoy.ai](https://app.baro.jigjoy.ai).
466
-
467
- ## What Baro adds to a coding harness
468
-
469
- Modern coding harnesses can already plan, use subagents and run work in
470
- parallel; those capabilities are not Baro's unique claim. The collective
471
- experiment focuses on an explicit control plane around heterogeneous workers:
472
-
473
- | Capability | Typical single-vendor harness | DIY parallel processes | Baro collective |
474
- |---|---|---|---|
475
- | **Model/provider mix** | vendor-specific | wire it yourself | per-story routes and deterministic bids |
476
- | **Plan state** | session-internal | application-specific | explicit, versioned DAG |
477
- | **Work ownership** | harness-internal | wire it yourself | correlated offers, leases and authority fencing |
478
- | **Runtime adaptation** | harness-specific | wire it yourself | validated future-DAG transaction, persist-before-Applied |
479
- | **Auditability** | harness logs | build it yourself | typed semantic event and model-usage audit |
480
- | **Completion evidence** | model/harness result | build it yourself | Critic gate, repository integration and objective verifier |
481
- | **Cost/quality routing** | vendor model family | build it yourself | provider-neutral policy surface (estimates must be calibrated) |
231
+ Get a pairing token from baro-cloud → Runners. A mid-run network blip won't kill a run:
232
+ the runner reconnects and resumes streaming where it left off.
482
233
 
483
- For a historical side-by-side on one real refactor, see [baro vs Claude Code `/goal`](https://jigjoy.ai/blog/baro-vs-claude-code). Treat it as a case study, not a current capability matrix.
234
+ **No machine or subscription?** baro-cloud can run the goal entirely on our
235
+ infrastructure, billed from prepaid credits — pick **☁ baro's cloud** at
236
+ [app.baro.jigjoy.ai](https://app.baro.jigjoy.ai).
484
237
 
485
238
  ## Requirements
486
239
 
487
- - At least one of:
488
- - [Claude CLI](https://docs.anthropic.com/en/docs/claude-cli) authenticated (for `--llm claude`, the default)
489
- - [OpenAI Codex CLI](https://github.com/openai/codex) authenticated (for `--llm codex`)
490
- - [OpenCode CLI](https://opencode.ai) with a provider configured (for `--llm opencode`)
491
- - `OPENAI_API_KEY` set (for `--llm openai`)
492
- - `OPENAI_BASE_URL` set to a custom endpoint (optional, for `--llm openai` — routes through Xiaomi MiMo, OpenRouter, vLLM, Ollama, or any OpenAI-compatible API)
493
- - Both Claude CLI **and** Codex CLI authenticated (for `--llm hybrid`)
494
- - Node.js 20+
240
+ - Node.js 20+, and at least one of:
241
+ - [Claude CLI](https://docs.anthropic.com/en/docs/claude-cli) signed in — for `--llm claude` (default)
242
+ - [Codex CLI](https://github.com/openai/codex) signed in — for `--llm codex`
243
+ - [OpenCode CLI](https://opencode.ai) with a provider — for `--llm opencode`
244
+ - `OPENAI_API_KEY` (optionally `OPENAI_BASE_URL`) — for `--llm openai`
245
+ - nothing at all — `baro login`, then `--llm jigjoy`
495
246
  - macOS (arm64/x64), Linux (x64/arm64), Windows (x64)
496
- - `gh` CLI (optional, for automatic PR creation)
247
+ - `gh` CLI, optional, for automatic PR creation
497
248
 
498
249
  ## Status & feedback
499
250
 
500
- baro is a work in progress. If a run explodes, the audit log at `~/.baro/runs/<run-id>.jsonl` is
501
- the fastest way to get it fixed — open an [issue](https://github.com/jigjoy-ai/baro/issues) with
502
- that file attached.
251
+ baro is a work in progress. If a run explodes, the audit log at `~/.baro/runs/<run-id>.jsonl`
252
+ is the fastest way to get it fixed — open an [issue](https://github.com/jigjoy-ai/baro/issues)
253
+ with that file attached.
503
254
 
504
- Ideas, use cases, bug reports — Discord: [**discord.gg/dvxY9J2kWX**](https://discord.gg/dvxY9J2kWX) · Twitter: [**@lotus_sbc**](https://twitter.com/lotus_sbc)
255
+ Discord: [**discord.gg/dvxY9J2kWX**](https://discord.gg/dvxY9J2kWX) · Twitter: [**@lotus_sbc**](https://twitter.com/lotus_sbc)
505
256
 
506
257
  ## License
507
258
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "baro-ai",
3
- "version": "0.81.7",
3
+ "version": "0.81.8",
4
4
  "description": "Autonomous parallel coding - plan and execute with AI",
5
5
  "type": "module",
6
6
  "bin": {