baro-ai 0.103.0 → 0.103.1
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.
- package/README.md +82 -220
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,261 +1,123 @@
|
|
|
1
1
|
# baro
|
|
2
2
|
|
|
3
|
-
> Type a goal in your repo. Walk away. Come back to a pull request.
|
|
3
|
+
> Type a goal in your repo. Walk away. Come back to a verified pull request.
|
|
4
4
|
|
|
5
5
|
[](https://www.npmjs.com/package/baro-ai)
|
|
6
6
|
[](https://www.npmjs.com/package/baro-ai)
|
|
7
|
-
[](https://www.npmjs.com/package/baro-ai)
|
|
8
7
|
|
|
9
|
-
|
|
8
|
+
baro is an autonomous software factory. It compiles your goal into a machine-checkable
|
|
9
|
+
contract, splits it into a DAG of stories, builds them in parallel across isolated git
|
|
10
|
+
worktrees, and blocks every merge behind fail-closed gates — declared tests, build,
|
|
11
|
+
an evidence critic, write-surface ownership. You review a PR the gates already accepted.
|
|
10
12
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
and opened the PR — from a single sentence.
|
|
13
|
+
One prompt → a 33-story plan → 808 passing tests → a PR, in 71 minutes.
|
|
14
|
+
[See a real run.](https://jigjoy.ai/blog/baro-808-nestjs-jest-tests)
|
|
14
15
|
|
|
15
|
-
|
|
16
|
+
## Install
|
|
16
17
|
|
|
17
18
|
```bash
|
|
18
19
|
npm install -g baro-ai
|
|
19
|
-
cd your-repo
|
|
20
|
-
baro "Add JWT authentication with role-based access control"
|
|
21
|
-
```
|
|
22
|
-
|
|
23
|
-
**No machine, or no Claude/Codex subscription?** Run the same fleet on **baro's cloud** — nothing to install, each run in an isolated sandbox, pay as you go. → **[app.baro.jigjoy.ai](https://app.baro.jigjoy.ai)**
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
<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>
|
|
28
|
-
|
|
29
|
-
## What happens when you run it
|
|
30
|
-
|
|
31
|
-
```mermaid
|
|
32
|
-
flowchart LR
|
|
33
|
-
G([your goal]) --> C[Conversation<br/><sub>asks only what matters</sub>]
|
|
34
|
-
C --> A[Architect<br/><sub>pins the design</sub>]
|
|
35
|
-
A --> P[Planner<br/><sub>splits into a story DAG</sub>]
|
|
36
|
-
P --> S[Story agents<br/><sub>parallel, isolated worktrees</sub>]
|
|
37
|
-
S --> V[Critic + Verifier<br/><sub>reviews, repairs, tests</sub>]
|
|
38
|
-
V --> PR([Pull Request])
|
|
39
|
-
```
|
|
40
|
-
|
|
41
|
-
1. **You describe the goal.** A conversation agent confirms the scope, or asks only the questions that would change it.
|
|
42
|
-
2. **The Architect pins the design** — file paths, schemas, API shapes, library choices — so dozens of agents don't each invent their own.
|
|
43
|
-
3. **The Planner splits it into a DAG of stories**, with dependencies, so independent work can run at the same time.
|
|
44
|
-
4. **A fleet of agents builds it**, each in its own git worktree — not one chat agent typing for an hour.
|
|
45
|
-
5. **It reviews and repairs itself.** A tool-less Critic gates each story; a Surgeon replans the ones that get stuck.
|
|
46
|
-
6. **You get a pull request**, build-verified, with a stories table and run stats.
|
|
47
|
-
|
|
48
|
-
The speedup scales with the width of your DAG, not the patience of a single session.
|
|
49
|
-
|
|
50
|
-
## Quick start
|
|
51
|
-
|
|
52
|
-
```bash
|
|
53
|
-
npm install -g baro-ai
|
|
54
|
-
|
|
55
|
-
baro "Migrate the hardcoded category data to a backend dictionary"
|
|
56
|
-
|
|
57
|
-
baro --quick "fix the typo on line 42 of README.md" # skip Architect/Critic/Surgeon
|
|
58
|
-
baro --parallel 3 "Add unit tests for the auth module"
|
|
59
|
-
baro --local-only "Your goal" # no pushes, no PR
|
|
60
|
-
baro --resume # pick up an existing prd.json
|
|
61
|
-
baro --continue "…and add refresh tokens" # follow-up onto the same PR
|
|
62
|
-
baro --doctor # self-diagnostic
|
|
63
|
-
```
|
|
64
|
-
|
|
65
|
-
Full options, `.barorc` config and per-phase overrides: [**docs.baro.rs**](https://docs.baro.rs).
|
|
66
|
-
|
|
67
|
-
## Execution modes
|
|
68
|
-
|
|
69
|
-
`--mode` decides how much runs at once. The default asks the intake to propose one and
|
|
70
|
-
lets you confirm it.
|
|
71
|
-
|
|
72
|
-
| mode | what it does |
|
|
73
|
-
|---|---|
|
|
74
|
-
| `auto` *(default)* | intake proposes a mode from the goal; you confirm |
|
|
75
|
-
| `focused` | a single story, start to finish |
|
|
76
|
-
| `sequential` | one story at a time, in dependency order |
|
|
77
|
-
| `parallel` | every ready story at once, up to `--parallel` |
|
|
78
|
-
|
|
79
|
-
## Use any model — or mix them
|
|
80
|
-
|
|
81
|
-
Same orchestration, same DAG, same prompts. The only thing that moves is which provider
|
|
82
|
-
each agent talks to. Auth inherits from whichever CLI you already have signed in — no API
|
|
83
|
-
key plumbing for the subscription backends.
|
|
84
|
-
|
|
85
|
-
```bash
|
|
86
|
-
baro --llm claude "Your goal" # default — Claude Code on an Anthropic Max subscription
|
|
87
|
-
baro --llm codex "Your goal" # Codex CLI on a ChatGPT Plus/Pro subscription
|
|
88
|
-
baro --llm opencode "Your goal" # OpenCode CLI — multi-provider agent shell
|
|
89
|
-
baro --llm openai "Your goal" # native OpenAI-compatible API (per-call billing)
|
|
90
|
-
baro --llm hybrid "Your goal" # Claude plans and reviews, Codex writes
|
|
91
|
-
baro --llm jigjoy "Your goal" # hosted baro gateway — we hold the upstream keys
|
|
92
20
|
```
|
|
93
21
|
|
|
94
|
-
|
|
95
|
-
|
|
22
|
+
Needs Node 20+, git, and at least one backend: the `claude` CLI (default), `codex`,
|
|
23
|
+
or any OpenAI-compatible endpoint. `baro --doctor` checks your setup.
|
|
96
24
|
|
|
97
|
-
|
|
25
|
+
## Use
|
|
98
26
|
|
|
99
27
|
```bash
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
"Your goal"
|
|
103
|
-
```
|
|
104
|
-
|
|
105
|
-
### Custom OpenAI-compatible endpoints
|
|
106
|
-
|
|
107
|
-
Anything speaking OpenAI **Chat Completions** works with `--llm openai`. Point
|
|
108
|
-
`OPENAI_BASE_URL` at it and pass any model name:
|
|
109
|
-
|
|
110
|
-
```bash
|
|
111
|
-
OPENAI_API_KEY=your-key OPENAI_BASE_URL=https://openrouter.ai/api/v1 \
|
|
112
|
-
baro --llm openai --story-model anthropic/claude-3.5-sonnet "Your goal"
|
|
113
|
-
|
|
114
|
-
OPENAI_API_KEY=not-needed OPENAI_BASE_URL=http://localhost:11434/v1 \
|
|
115
|
-
baro --llm openai --story-model llama3 "Your goal"
|
|
28
|
+
cd your-repo
|
|
29
|
+
baro "Add JWT authentication with role-based access control"
|
|
116
30
|
```
|
|
117
31
|
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
> **Gotcha.** Model names matching `gpt-*`, `o1`–`o9`, `chatgpt-*`, `text-*` or `davinci*`
|
|
121
|
-
> are treated as native OpenAI and go to the **Responses API** (`POST /v1/responses`),
|
|
122
|
-
> not Chat Completions (`POST /v1/chat/completions`) — two different wire protocols.
|
|
123
|
-
> Setting `OPENAI_BASE_URL` alone does not change that. Pass `--openai-base-url`
|
|
124
|
-
> explicitly and you get Chat Completions regardless of the model name.
|
|
32
|
+
That opens the TUI: intake asks only what matters, you confirm the plan, the fleet runs.
|
|
125
33
|
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
`--llm` picks a backend per *phase*. `--tier-map` tiers per *story* instead: the Planner
|
|
129
|
-
tags each story by blast radius — `light` (mechanical), `standard` (one module), `heavy`
|
|
130
|
-
(cross-cutting, schema, a DAG hub) — and the map binds each tier to a `backend:model`.
|
|
34
|
+
For automation, detach and follow from anywhere:
|
|
131
35
|
|
|
132
36
|
```bash
|
|
133
|
-
|
|
134
|
-
baro
|
|
135
|
-
|
|
136
|
-
|
|
37
|
+
baro --headless --detach --goal-file goal.txt # prints a run id, returns immediately
|
|
38
|
+
baro watch <run-id> # follow milestone events
|
|
39
|
+
baro logs <run-id> --follow # tail the raw log
|
|
40
|
+
baro runs # list live runs
|
|
41
|
+
baro stop <run-id> # stop one
|
|
137
42
|
```
|
|
138
43
|
|
|
139
|
-
|
|
140
|
-
OpenAI route can name its own endpoint with `@` — so one run can hit several endpoints at
|
|
141
|
-
once. Keys never go on the command line: each endpoint reads `BARO_OPENAI_KEY_<NAME>`,
|
|
142
|
-
falling back to `OPENAI_API_KEY`.
|
|
143
|
-
|
|
144
|
-
Provider economics and a side-by-side benchmark across three real tasks:
|
|
145
|
-
[**Claude Code vs OpenAI Codex in my parallel agent setup**](https://jigjoy.ai/blog/claude-code-vs-codex-baro).
|
|
146
|
-
|
|
147
|
-
## Under the hood: participants on an event bus
|
|
148
|
-
|
|
149
|
-
Most multi-agent setups put one orchestrator function in the middle driving N agents. That
|
|
150
|
-
orchestrator becomes the bottleneck the moment you go past a handful of concurrent agents,
|
|
151
|
-
and every new behaviour means editing its control flow.
|
|
152
|
-
|
|
153
|
-
baro has no such function. Every role is a participant on a shared event bus
|
|
154
|
-
([Mozaik](https://github.com/jigjoy-ai/mozaik)), reacting to typed events:
|
|
44
|
+
## Commands
|
|
155
45
|
|
|
156
|
-
|
|
157
|
-
flowchart LR
|
|
158
|
-
subgraph A["Typical orchestrator"]
|
|
159
|
-
direction TB
|
|
160
|
-
C{{Coordinator}}
|
|
161
|
-
C --> A1[Agent 1]
|
|
162
|
-
C --> A2[Agent 2]
|
|
163
|
-
C --> A3[Agent N]
|
|
164
|
-
end
|
|
165
|
-
subgraph B["baro on Mozaik"]
|
|
166
|
-
direction TB
|
|
167
|
-
Bus[(shared event bus)]
|
|
168
|
-
P1[Board + Broker] -.-> Bus
|
|
169
|
-
P2[Story Agent 1] -.-> Bus
|
|
170
|
-
P3[Story Agent N] -.-> Bus
|
|
171
|
-
P4[Critic / Surgeon / …] -.-> Bus
|
|
172
|
-
end
|
|
173
|
-
```
|
|
174
|
-
|
|
175
|
-
| Participant | Role |
|
|
46
|
+
| Command | What it does |
|
|
176
47
|
|---|---|
|
|
177
|
-
|
|
|
178
|
-
|
|
|
179
|
-
|
|
|
180
|
-
|
|
|
181
|
-
|
|
|
182
|
-
|
|
|
183
|
-
|
|
|
184
|
-
|
|
|
185
|
-
|
|
|
186
|
-
|
|
|
187
|
-
|
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
trigger — changes no existing code. Workers can also message each other and propose
|
|
191
|
-
changes to not-yet-started parts of the DAG; the Board stays the only thing allowed to
|
|
192
|
-
mutate it.
|
|
193
|
-
|
|
194
|
-
**Details:** [collective runtime architecture](docs/collective-runtime.md) covers the
|
|
195
|
-
execution guarantees, lease and authority fencing, failure policy, runtime DAG changes,
|
|
196
|
-
progressive planning, and the provider-free verification contract. The
|
|
197
|
-
[local collective experiment](docs/collective-experiment.md) is the hands-on guide.
|
|
198
|
-
|
|
199
|
-
## Semantic memory
|
|
200
|
-
|
|
201
|
-
Parallel agents share what they discover. When one reads a file or greps a pattern, the
|
|
202
|
-
finding is embedded locally (CPU-only ONNX, no API calls) and indexed, so siblings don't
|
|
203
|
-
redo the same exploration — only semantically relevant findings get injected.
|
|
48
|
+
| `baro "<goal>"` | run a goal in the current repo (TUI) |
|
|
49
|
+
| `baro --goal-file <path>` | read the goal from a file |
|
|
50
|
+
| `baro --headless --detach ...` | background run for CI/automation; prints the run id |
|
|
51
|
+
| `baro watch <run-id>` | follow a live run's milestones |
|
|
52
|
+
| `baro logs <run-id> [--follow]` | print or tail a run's log |
|
|
53
|
+
| `baro runs` / `baro stop <id>` | list / stop live runs |
|
|
54
|
+
| `baro --resume` | resume an interrupted run from `prd.json` — **never re-plans** |
|
|
55
|
+
| `baro --continue` | follow-up on the current branch — **always re-plans** |
|
|
56
|
+
| `baro --doctor` | self-diagnostic: backends, auth, gh, permissions |
|
|
57
|
+
| `baro login` | browser sign-in for baro cloud |
|
|
58
|
+
| `baro connect [--install-service]` | attach this machine as a cloud runner |
|
|
59
|
+
|
|
60
|
+
## The flags that matter
|
|
204
61
|
|
|
205
62
|
```bash
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
63
|
+
--llm claude|codex|openai|opencode|pi|hybrid|jigjoy # backend for all phases
|
|
64
|
+
-m opus|sonnet|haiku # model override (verbatim pass-through on other backends)
|
|
65
|
+
--effort low..max # thinking per turn (default: high)
|
|
66
|
+
--parallel N # max parallel story agents (0 = unlimited)
|
|
67
|
+
--mode focused|sequential|parallel # force an execution mode (default: intake proposes)
|
|
68
|
+
--quick # trivial goals: one story, no architect/critic/surgeon
|
|
69
|
+
--local-only # no pushes, no PRs — hard isolation
|
|
70
|
+
--shell-budget <seconds> # per-command budget for story shell tools
|
|
71
|
+
--openai-base-url <url> # any OpenAI-compatible provider (OpenRouter, vLLM, Ollama…)
|
|
72
|
+
--tier-map "light=openai:MiniMax-M3,heavy=claude:opus" # mix backends per story tier
|
|
209
73
|
```
|
|
210
74
|
|
|
211
|
-
|
|
212
|
-
|
|
75
|
+
Per-phase overrides (`--architect-llm`, `--story-model`, …), `.barorc`, and everything
|
|
76
|
+
else: [**docs.baro.rs**](https://docs.baro.rs)
|
|
213
77
|
|
|
214
|
-
##
|
|
78
|
+
## How it works
|
|
215
79
|
|
|
216
|
-
baro
|
|
217
|
-
GitHub issue labeled `baro`, and it executes here on your machine over your own
|
|
218
|
-
subscription. baro-cloud orchestrates and never sees your source — only metadata and diffs.
|
|
80
|
+
|
|
219
81
|
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
baro connect --uninstall-service # remove it
|
|
231
|
-
```
|
|
82
|
+
- **Contract first.** An architect turns the goal into invariants and obligations that
|
|
83
|
+
are machine-checkable — before any code is written.
|
|
84
|
+
- **A collective, not a coordinator.** Story agents are peers on an event bus: they see
|
|
85
|
+
the events that concern them, exchange notes, and suspend/resume on each other's work.
|
|
86
|
+
There is no single context window everything must squeeze through.
|
|
87
|
+
- **Gates, not vibes.** Declared tests, build-before-commit, an evidence critic that
|
|
88
|
+
judges captured command output, and write-surface ownership — fail-closed, blocking
|
|
89
|
+
every merge. The human reviews a PR the gates already accepted.
|
|
90
|
+
- **A live plan.** The plan is a DAG the run negotiates with: runtime replanning adds and
|
|
91
|
+
rewires stories mid-run, and a failed gate can spawn its own remediation story.
|
|
232
92
|
|
|
233
|
-
|
|
234
|
-
the runner reconnects and resumes streaming where it left off.
|
|
93
|
+
## Drive it with Claude Code
|
|
235
94
|
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
[app.baro.jigjoy.ai](https://app.baro.jigjoy.ai).
|
|
95
|
+
baro pairs well with a coding agent in the driver's seat. Paste this into Claude Code
|
|
96
|
+
inside your repo:
|
|
239
97
|
|
|
240
|
-
|
|
98
|
+
```text
|
|
99
|
+
Install baro (npm install -g baro-ai) and run `baro --doctor` to verify the setup.
|
|
100
|
+
Then drive it for me:
|
|
241
101
|
|
|
242
|
-
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
- `gh` CLI, optional, for automatic PR creation
|
|
102
|
+
1. Write my task as an evidence-rich goal file: name the exact files and line numbers
|
|
103
|
+
the change touches, state the constraints, and say which tests must prove it.
|
|
104
|
+
2. Launch it detached: `baro --headless --detach --goal-file goal.txt`, note the run id.
|
|
105
|
+
3. Follow it with `baro watch <run-id>`; if it stalls, read `baro logs <run-id>`.
|
|
106
|
+
4. When the pull request opens, review the diff against the goal, run the project's
|
|
107
|
+
test suite yourself, and report back: what shipped, what the gates proved, and
|
|
108
|
+
anything that needs my eyes. Merge only if everything is green.
|
|
250
109
|
|
|
251
|
-
|
|
110
|
+
Keep goals narrow — one concern per run. If the run fails, read why, tighten the goal
|
|
111
|
+
with the new evidence, and launch again.
|
|
112
|
+
```
|
|
252
113
|
|
|
253
|
-
|
|
254
|
-
is the fastest way to get it fixed — open an [issue](https://github.com/jigjoy-ai/baro/issues)
|
|
255
|
-
with that file attached.
|
|
114
|
+
## Cloud
|
|
256
115
|
|
|
257
|
-
|
|
116
|
+
No machine, or no Claude/Codex subscription? Run the same fleet on
|
|
117
|
+
[**app.baro.jigjoy.ai**](https://app.baro.jigjoy.ai) — nothing to install, isolated
|
|
118
|
+
sandboxes, our keys. Or keep your own hardware in the pool: `baro login`, then
|
|
119
|
+
`baro connect --install-service`.
|
|
258
120
|
|
|
259
|
-
|
|
121
|
+
---
|
|
260
122
|
|
|
261
|
-
|
|
123
|
+
Docs: [docs.baro.rs](https://docs.baro.rs) · Issues: [github.com/jigjoy-ai/baro/issues](https://github.com/jigjoy-ai/baro/issues) · Twitter: [@lotus_sbc](https://twitter.com/lotus_sbc)
|