Skip to content

Commit 35e7c5e

Browse files
committed
docs: add CLAUDE.md with runtime model and opencode invocation gotchas
1 parent 5c401ae commit 35e7c5e

1 file changed

Lines changed: 46 additions & 0 deletions

File tree

‎CLAUDE.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
@AGENTS.md
6+
7+
## Running a single test
8+
9+
- `bun test test/models.test.ts` — one file
10+
- `bun test -t "ambiguous"` — filter by test name (regex)
11+
12+
Bun runs `.ts` directly. Nothing is compiled or bundled (`tsconfig` sets `noEmit`); there is no `dist/`.
13+
14+
## What actually ships
15+
16+
The plugin's runtime behaviour lives in markdown, not in `src/`:
17+
18+
| Surface | File | Role |
19+
| --------- | ------------------------------------------------ | -------------------------------------------------------------------------------- |
20+
| Skill | `skills/opencode-delegate/SKILL.md` | Model picking, brief template, review-after-return rules |
21+
| Agent | `agents/opencode-worker.md` | Thin forwarder: one `opencode run` (write: `build --auto`; read: `plan`), report |
22+
| Command | `commands/opencode.md` | `/opencode <model> -- <task>`: splits on `--`, spawns `opencode-worker` |
23+
| Manifests | `.claude-plugin/plugin.json`, `marketplace.json` | Plugin identity; `plugin.json` carries homepage/repository shown by Claude Code |
24+
25+
`src/` is a library that no plugin surface imports since the MCP server was removed; only the tests exercise it. Its exports (`delegate`, `resolveModel`, `buildArgs`, `EventCollector`) are the reference for how `opencode run` must be invoked and how its JSON stream is parsed. Changing behaviour in `src/` does NOT change what the plugin does — the markdown files do. `opencode-worker` shells out to `opencode run` itself; keep its command consistent with `buildArgs`.
26+
27+
Invocation gotchas (observed on opencode 2.1.2):
28+
29+
- The command needs `</dev/null`. When stdin is an open pipe (as in Claude's Bash tool), `opencode run` waits for it to close and never creates a session.
30+
- Write tasks must pass `--agent build`, because `default_agent` is `plan` both in this repo's `opencode.json` and in typical user configs.
31+
- Without `--auto`, a headless run auto-rejects permission requests and continues; this is what makes `--agent plan` safe for read-only work.
32+
- If no model is named, omit `-m` so opencode's configured default model is used.
33+
34+
Call chain inside `src/`: `delegate.ts` → `models.resolveModelOrThrow` (`listModels` → `opencode models`, cached 5 min) → `opencode.runOpencode` (spawns the process, folds stdout through `EventCollector`) → git-diff changed-files detection → `formatOutcome`.
35+
36+
## Model resolution rules (`src/models.ts`)
37+
38+
- An exact `provider/model` id wins first; `#variant` is split off and re-appended.
39+
- Every token containing a digit must appear in the model name, so `grok 4.7` never matches 4.6.
40+
- Ties prefer the candidate with fewer unrequested name tokens; a query without a version token is ambiguous whenever candidates tie.
41+
- The same model from several providers goes to `OPENCODE_DELEGATE_PREFERRED_PROVIDERS` order first, then a direct provider over an `AGGREGATORS` reseller.
42+
43+
## Keeping docs and manifests in sync
44+
45+
- Defaults and env vars are defined in `src/config.ts` and documented in the README env table and the skill — update all three together.
46+
- Version `0.1.0` appears in `package.json`, `plugin.json` and `marketplace.json` — bump all three.

0 commit comments

Comments
 (0)