|
| 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