Skip to content

Commit 22b192d

Browse files
chernistryclaude
chernistry
and
claude
authored
docs: add adapter selection guide matrix + Redoc API reference (#590)
- ADAPTER_GUIDE.md: add reasoning strength, cost tier, and recommended use cases columns to comparison matrix; covers all 19 adapters - docs/adapters.html: replace feature matrix with full adapter-centric comparison table (models, reasoning, cost, tool use, structured output, MCP, best-for); keep detailed feature matrix as secondary reference - docs/api-reference.html: new Redoc-based OpenAPI reference page, auto-generated from live server spec (216 endpoints); dark/light theme aware, loads from openapi.json - docs/openapi.json: generated OpenAPI 3.1 spec with enhanced metadata (title, description, servers, tags, error format docs) Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
1 parent 3845d8e commit 22b192d

4 files changed

Lines changed: 11622 additions & 30 deletions

File tree

‎docs/ADAPTER_GUIDE.md‎

Lines changed: 26 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# Adapter Selection Guide
22

3-
Bernstein supports 19 adapters for different CLI coding agents. This guide covers
4-
when to use each, what they support, and how to configure them.
3+
Bernstein supports 19 adapters for different CLI coding agents. This guide helps
4+
you pick the right one for your use case.
55

66
All adapters implement the `CLIAdapter` interface (`adapters/base.py`): `spawn()`,
77
process monitoring via PID, log capture to `.sdd/runtime/<session>.log`, and
@@ -13,29 +13,30 @@ Source of truth: `src/bernstein/adapters/registry.py`, individual adapter files.
1313

1414
## Comparison Matrix
1515

16-
| Adapter | Provider | Models | Cost Tier | Tool Use | Structured Output | MCP Support | Install |
17-
|---------|----------|--------|-----------|----------|-------------------|-------------|---------|
18-
| `claude` | Anthropic | opus, sonnet, haiku | $$-$$$ | Full (scoped by role) | JSON schema enforced | Yes (--mcp-config) | `npm i -g @anthropic-ai/claude-code` |
19-
| `codex` | OpenAI | gpt-4o, o3, o4-mini | $$-$$$ | Full | JSON (--json) | No | `npm i -g @openai/codex` |
20-
| `gemini` | Google | gemini-2.5-pro/flash | Free-$$$ | Full | JSON (--output-format json) | No | `npm i -g @google/gemini-cli` |
21-
| `aider` | Multi | Any via provider prefix | $-$$$ | File editing | No | No | `pip install aider-chat` |
22-
| `amp` | Sourcegraph | Anthropic + OpenAI models | $$-$$$ | Full | No | No | `brew install amp` |
23-
| `qwen` | Multi | qwen3-coder, qwen3.6 | Free-$$ | Full | No | No | Qwen CLI |
24-
| `ollama` | Local | deepseek-r1, qwen2.5-coder, etc. | Free | File editing (via Aider) | No | No | `brew install ollama` + `pip install aider-chat` |
25-
| `cody` | Sourcegraph | Anthropic/OpenAI/Google via SG | $$ | Chat only | No | No | Sourcegraph CLI (`sg`) |
26-
| `cursor` | Cursor | Cursor's model routing | $$ | Full | No | Yes (--add-mcp) | `cursor` CLI from cursor.com |
27-
| `goose` | Block | Anthropic models | $$-$$$ | Full | No | No | Block's Goose CLI |
28-
| `roo-code` | Multi | Anthropic + OpenAI | $$-$$$ | Full | JSON (--output-format json) | No | `npm i -g @roo-code/cli` |
29-
| `continue` | Multi | Anthropic/OpenAI/Google | $-$$$ | Full | No | Via config.yaml | `npm i -g @continuedev/continue-cli` |
30-
| `opencode` | Multi | Any configured provider | $-$$$ | Full | JSON (--format json) | No | OpenCode CLI |
31-
| `kiro` | AWS | AWS-managed models | $$ | Full | No | No | `kiro-cli` |
32-
| `kilo` | Stackblitz | Any via provider routing | $-$$$ | Full | No | Yes (--mcp) | `kilo` from kilocode.ai |
33-
| `tabby` | Self-hosted | Server-configured model | Free | Agent tasks | No | No | `npm i -g @tabbyml/tabby-agent` + server |
34-
| `iac` | N/A | N/A (Terraform/Pulumi) | N/A | IaC plan+apply | No | No | `terraform` or `pulumi` |
35-
| `generic` | Any | Pass-through | Varies | Depends on CLI | No | No | User-provided binary |
36-
| `mock` | None | None (simulated) | Free | Simulated | Simulated | No | Built-in (testing only) |
37-
38-
**Cost tier key:** Free = no API cost, $ = <$0.01/task, $$ = $0.01-$0.10/task, $$$ = $0.10+/task.
16+
| Adapter | Provider | Models | Reasoning | Cost Tier | Tool Use | Structured Output | MCP | Recommended Use Case |
17+
|---------|----------|--------|-----------|-----------|----------|-------------------|-----|----------------------|
18+
| `claude` | Anthropic | opus, sonnet, haiku | ★★★★★ (opus) / ★★★★ (sonnet) / ★★ (haiku) | $$–$$$ | Full (role-scoped) | JSON schema enforced | Yes | Primary workhorse — architecture, features, tests, docs |
19+
| `codex` | OpenAI | o3, o4-mini, gpt-4o | ★★★★★ (o3/o4) / ★★★★ (gpt-4o) | $$–$$$ | Full | JSON (`--json`) | No | Provider diversity; OpenAI reasoning models |
20+
| `gemini` | Google | gemini-2.5-pro, flash | ★★★★ (pro) / ★★★ (flash) | Free–$$$ | Full | JSON (`--output-format json`) | No | Free-tier usage; cost-effective medium tasks |
21+
| `aider` | Multi | Any (Anthropic/OpenAI/Azure) | Inherited from model | $–$$$ | File editing | No | Commit-per-change workflows; focused file edits |
22+
| `amp` | Sourcegraph | Anthropic + OpenAI models | ★★★★★ (opus/o3) | $$–$$$ | Full | No | Sourcegraph-integrated teams; codebase-aware context |
23+
| `qwen` | Multi | qwen3-coder, qwen3.6-plus | ★★★ | Free–$$ | Full | No | Cost-sensitive; low-complexity tasks; free OpenRouter |
24+
| `ollama` | Local | deepseek-r1, qwen2.5-coder, phi4 | ★★★ (r1:70b) / ★★ (7b) | Free | File editing (via Aider) | No | Air-gapped; privacy-sensitive; zero API cost |
25+
| `cody` | Sourcegraph | Anthropic/OpenAI/Google (via SG) | Inherited from model | $$ | Chat only | No | Sourcegraph-integrated with codebase-level context |
26+
| `cursor` | Cursor | Cursor's model routing | ★★★★ | $$ | Full | No | Teams with Cursor subscriptions |
27+
| `goose` | Block | Anthropic models | ★★★★ | $$–$$$ | Full | No | Teams already using Block's Goose |
28+
| `roo-code` | Multi | Anthropic + OpenAI | ★★★★ | $$–$$$ | Full | JSON (`--output-format json`) | No | VS Code extension users wanting headless CLI |
29+
| `continue` | Multi | Anthropic/OpenAI/Google | Inherited from model | $–$$$ | Full | No | Teams with existing Continue.dev configurations |
30+
| `opencode` | Multi | Any configured provider | Inherited from model | $–$$$ | Full | JSON (`--format json`) | No | Multi-provider setups; single CLI interface |
31+
| `kiro` | AWS | AWS-managed models | ★★★ | $$ | Full | No | AWS-centric teams using AWS AI services |
32+
| `kilo` | Stackblitz | Any (via provider routing) | Inherited from model | $–$$$ | Full | No | Web development; Stackblitz-integrated teams |
33+
| `tabby` | Self-hosted | Server-configured model | Varies | Free | Agent tasks | No | Self-hosted; compliance-restricted; full model control |
34+
| `iac` | N/A | N/A (Terraform/Pulumi) | N/A | N/A | IaC plan+apply | No | Infrastructure tasks — pair with LLM adapter for codegen |
35+
| `generic` | Any | Pass-through | Depends on CLI | Varies | Depends on CLI | No | Unlisted CLIs; prototyping new adapters |
36+
| `mock` | None | None (simulated) | N/A | Free | Simulated | Simulated | Unit and integration tests only |
37+
38+
**Reasoning key:** ★★★★★ Exceptional (frontier reasoning) · ★★★★ Strong · ★★★ Good · ★★ Basic · ★ Minimal
39+
**Cost tier key:** Free = no API cost · $ = <$0.01/task · $$ = $0.01–$0.10/task · $$$ = $0.10+/task
3940
Actual costs depend on task complexity, token usage, and provider pricing.
4041

4142
---

‎docs/adapters.html‎

Lines changed: 229 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -116,7 +116,231 @@ <h2 id="why">Why model-agnostic</h2>
116116
<li><strong>Future-proof</strong> — your task graph, roles, and prompts outlive any single model generation.</li>
117117
</ul>
118118

119-
<h2 id="matrix">Feature matrix</h2>
119+
<h2 id="matrix">Adapter comparison matrix</h2>
120+
121+
<p>Quick-reference for choosing an adapter. Reasoning scale: ★★★★★ exceptional (frontier) · ★★★★ strong · ★★★ good · ★★ basic. Cost: Free = no API cost · $ = &lt;$0.01/task · $$ = $0.01–$0.10 · $$$ = $0.10+.</p>
122+
123+
<div class="table-wrap">
124+
<table>
125+
<thead>
126+
<tr>
127+
<th>Adapter</th>
128+
<th>Provider</th>
129+
<th>Models</th>
130+
<th>Reasoning</th>
131+
<th>Cost Tier</th>
132+
<th>Tool Use</th>
133+
<th>Structured Output</th>
134+
<th>MCP</th>
135+
<th>Best For</th>
136+
</tr>
137+
</thead>
138+
<tbody>
139+
<tr>
140+
<td><a href="#claude"><code>claude</code></a></td>
141+
<td>Anthropic</td>
142+
<td>opus / sonnet / haiku</td>
143+
<td>★★★★★ opus · ★★★★ sonnet</td>
144+
<td>$$–$$$</td>
145+
<td>Full (role-scoped)</td>
146+
<td>JSON schema enforced</td>
147+
<td>✓</td>
148+
<td>Primary workhorse — architecture, features, tests, docs</td>
149+
</tr>
150+
<tr>
151+
<td><a href="#codex"><code>codex</code></a></td>
152+
<td>OpenAI</td>
153+
<td>o3, o4-mini, gpt-4o</td>
154+
<td>★★★★★ o3 · ★★★★ gpt-4o</td>
155+
<td>$$–$$$</td>
156+
<td>Full</td>
157+
<td>JSON (<code>--json</code>)</td>
158+
<td>—</td>
159+
<td>Provider diversity; OpenAI reasoning models</td>
160+
</tr>
161+
<tr>
162+
<td><a href="#gemini"><code>gemini</code></a></td>
163+
<td>Google</td>
164+
<td>gemini-2.5-pro / flash</td>
165+
<td>★★★★ pro · ★★★ flash</td>
166+
<td>Free–$$$</td>
167+
<td>Full</td>
168+
<td>JSON (<code>--output-format</code>)</td>
169+
<td>—</td>
170+
<td>Free-tier usage; cost-effective medium tasks</td>
171+
</tr>
172+
<tr>
173+
<td><a href="#aider"><code>aider</code></a></td>
174+
<td>Multi</td>
175+
<td>Any (Anthropic/OpenAI/Azure)</td>
176+
<td>Inherited from model</td>
177+
<td>$–$$$</td>
178+
<td>File editing</td>
179+
<td>—</td>
180+
<td>—</td>
181+
<td>Commit-per-change workflows; focused file edits</td>
182+
</tr>
183+
<tr>
184+
<td><a href="#amp"><code>amp</code></a></td>
185+
<td>Sourcegraph</td>
186+
<td>opus 4.6, sonnet, o3</td>
187+
<td>★★★★★ opus/o3</td>
188+
<td>$$–$$$</td>
189+
<td>Full</td>
190+
<td>—</td>
191+
<td>—</td>
192+
<td>Sourcegraph-integrated teams; codebase-aware context</td>
193+
</tr>
194+
<tr>
195+
<td><a href="#qwen"><code>qwen</code></a></td>
196+
<td>Multi</td>
197+
<td>qwen3-coder, qwen3.6-plus</td>
198+
<td>★★★</td>
199+
<td>Free–$$</td>
200+
<td>Full</td>
201+
<td>—</td>
202+
<td>—</td>
203+
<td>Cost-sensitive; low-complexity tasks; free OpenRouter</td>
204+
</tr>
205+
<tr>
206+
<td><a href="#ollama"><code>ollama</code></a></td>
207+
<td>Local</td>
208+
<td>deepseek-r1, qwen2.5-coder, phi4</td>
209+
<td>★★★ r1:70b · ★★ 7b</td>
210+
<td>Free</td>
211+
<td>File editing (Aider)</td>
212+
<td>—</td>
213+
<td>—</td>
214+
<td>Air-gapped; privacy-sensitive; zero API cost</td>
215+
</tr>
216+
<tr>
217+
<td><a href="#cody"><code>cody</code></a></td>
218+
<td>Sourcegraph</td>
219+
<td>Via SG routing</td>
220+
<td>Inherited from model</td>
221+
<td>$$</td>
222+
<td>Chat</td>
223+
<td>—</td>
224+
<td>—</td>
225+
<td>Sourcegraph-integrated with codebase-level context</td>
226+
</tr>
227+
<tr>
228+
<td><a href="#cursor"><code>cursor</code></a></td>
229+
<td>Cursor</td>
230+
<td>Cursor's model routing</td>
231+
<td>★★★★</td>
232+
<td>$$</td>
233+
<td>Full</td>
234+
<td>—</td>
235+
<td>✓ (<code>--add-mcp</code>)</td>
236+
<td>Teams with Cursor subscriptions</td>
237+
</tr>
238+
<tr>
239+
<td><a href="#goose"><code>goose</code></a></td>
240+
<td>Block</td>
241+
<td>Anthropic models</td>
242+
<td>★★★★</td>
243+
<td>$$–$$$</td>
244+
<td>Full</td>
245+
<td>—</td>
246+
<td>—</td>
247+
<td>Teams already using Block's Goose</td>
248+
</tr>
249+
<tr>
250+
<td><a href="#roo-code"><code>roo-code</code></a></td>
251+
<td>Multi</td>
252+
<td>Anthropic + OpenAI</td>
253+
<td>★★★★</td>
254+
<td>$$–$$$</td>
255+
<td>Full</td>
256+
<td>JSON (<code>--output-format</code>)</td>
257+
<td>—</td>
258+
<td>VS Code extension users wanting headless CLI</td>
259+
</tr>
260+
<tr>
261+
<td><a href="#continue"><code>continue</code></a></td>
262+
<td>Multi</td>
263+
<td>Anthropic/OpenAI/Google</td>
264+
<td>Inherited from model</td>
265+
<td>$–$$$</td>
266+
<td>Full</td>
267+
<td>—</td>
268+
<td>Via config</td>
269+
<td>Teams with existing Continue.dev configurations</td>
270+
</tr>
271+
<tr>
272+
<td><a href="#opencode"><code>opencode</code></a></td>
273+
<td>Multi</td>
274+
<td>Any configured provider</td>
275+
<td>Inherited from model</td>
276+
<td>$–$$$</td>
277+
<td>Full</td>
278+
<td>JSON (<code>--format json</code>)</td>
279+
<td>—</td>
280+
<td>Multi-provider setups; single CLI interface</td>
281+
</tr>
282+
<tr>
283+
<td><a href="#kiro"><code>kiro</code></a></td>
284+
<td>AWS</td>
285+
<td>AWS-managed models</td>
286+
<td>★★★</td>
287+
<td>$$</td>
288+
<td>Full</td>
289+
<td>—</td>
290+
<td>—</td>
291+
<td>AWS-centric teams using AWS AI services</td>
292+
</tr>
293+
<tr>
294+
<td><a href="#kilo"><code>kilo</code></a></td>
295+
<td>Stackblitz</td>
296+
<td>Any (provider routing)</td>
297+
<td>Inherited from model</td>
298+
<td>$–$$$</td>
299+
<td>Full</td>
300+
<td>—</td>
301+
<td>✓ (<code>--mcp</code>)</td>
302+
<td>Web development; Stackblitz-integrated teams</td>
303+
</tr>
304+
<tr>
305+
<td><a href="#tabby"><code>tabby</code></a></td>
306+
<td>Self-hosted</td>
307+
<td>Server-configured</td>
308+
<td>Varies</td>
309+
<td>Free</td>
310+
<td>Agent tasks</td>
311+
<td>—</td>
312+
<td>—</td>
313+
<td>Self-hosted; compliance-restricted; full model control</td>
314+
</tr>
315+
<tr>
316+
<td><a href="#iac"><code>iac</code></a></td>
317+
<td>N/A</td>
318+
<td>N/A (Terraform/Pulumi)</td>
319+
<td>N/A</td>
320+
<td>N/A</td>
321+
<td>IaC plan+apply</td>
322+
<td>—</td>
323+
<td>—</td>
324+
<td>Infrastructure tasks — pair with LLM adapter for codegen</td>
325+
</tr>
326+
<tr>
327+
<td><a href="#generic"><code>generic</code></a></td>
328+
<td>Any</td>
329+
<td>Pass-through</td>
330+
<td>Depends on CLI</td>
331+
<td>Varies</td>
332+
<td>Depends on CLI</td>
333+
<td>—</td>
334+
<td>—</td>
335+
<td>Unlisted CLIs; prototyping new adapters</td>
336+
</tr>
337+
</tbody>
338+
</table>
339+
</div>
340+
341+
<h3>Detailed feature matrix</h3>
342+
343+
<p>Adapter capabilities at a glance:</p>
120344

121345
<div class="table-wrap">
122346
<table>
@@ -188,14 +412,14 @@ <h2 id="matrix">Feature matrix</h2>
188412
<td>—</td>
189413
<td>—</td>
190414
<td>✓ (stream-json)</td>
415+
<td>✓ (--json)</td>
191416
<td>—</td>
192-
<td>—</td>
193-
<td>—</td>
417+
<td>✓ (--output-format json)</td>
194418
<td>—</td>
195419
<td>✓ (--format json)</td>
420+
<td>✓ (--format json)</td>
196421
<td>—</td>
197-
<td>—</td>
198-
<td>—</td>
422+
<td>✓ (--output-format json)</td>
199423
<td>—</td>
200424
</tr>
201425
<tr>

0 commit comments

Comments
 (0)