|
1 | 1 | # claude-opencode-delegate |
2 | 2 |
|
3 | | -Give Claude **every model in your [OpenCode](https://opencode.ai) install** as a delegate: Grok, |
4 | | -Kimi, GLM, Qwen, DeepSeek, MiMo, MiniMax, and any other provider you've connected. Claude stays |
5 | | -the orchestrator. It plans the work, briefs the other model, reviews the diff, and runs the tests. |
| 3 | +A Claude Code plugin that delegates scoped tasks to any model available in your [OpenCode](https://opencode.ai) install (Grok, Kimi, GLM, Qwen, DeepSeek, MiMo, MiniMax, …). Claude stays the orchestrator: it hands over the task, then reviews the diff and runs the tests. |
6 | 4 |
|
| 5 | +```text |
| 6 | +you ▸ /opencode grok 4.7 -- add input validation to the signup form |
| 7 | +claude ▸ spawns opencode-worker (model: grok 4.7, mode: write) |
| 8 | +worker ▸ opencode run … → session ses_abc, 3 files changed, report |
| 9 | +claude ▸ reads git diff, runs tests, reports which model did what and a verdict |
7 | 10 | ``` |
8 | | -you ▸ use grok 4.7 from xAI in opencode to implement the CSV export, you review it |
9 | | -
|
10 | | -claude ▸ spawn opencode-worker subagent with model "grok 4.7" and brief |
11 | 11 |
|
12 | | -opencode ▸ grok-4.7 edits src/export.ts, runs tests … |
13 | | -
|
14 | | -claude ▸ reviews git diff, runs `bun test`, and reports back |
15 | | -``` |
| 12 | +## What ships |
16 | 13 |
|
17 | | -It works in: |
| 14 | +| Surface | File | Role | |
| 15 | +| ------- | ----------------------------------- | ----------------------------------------------------------------------- | |
| 16 | +| Skill | `skills/opencode-delegate/SKILL.md` | Model picking, brief template, review-after-return rules | |
| 17 | +| Agent | `agents/opencode-worker.md` | Thin forwarder (`tools: Bash`, `model: haiku`): one `opencode run` | |
| 18 | +| Command | `commands/opencode.md` | `/opencode <model> -- <task>`: splits on `--`, spawns `opencode-worker` | |
18 | 19 |
|
19 | | -- **Claude Code** (CLI, IDE, desktop): you can ask directly, use `/opencode`, use the |
20 | | - `opencode-delegate` skill, or use the `opencode-worker` agent. |
21 | | -- **Claude Desktop** on Linux, macOS, or Windows: use the skill/agent files directly or run |
22 | | - OpenCode from the terminal. |
| 20 | +No MCP server, no build step, no `dist/`. Claude Desktop is not supported. |
23 | 21 |
|
24 | 22 | ## How it works |
25 | 23 |
|
| 24 | +```mermaid |
| 25 | +flowchart LR |
| 26 | + C[Claude] -->|model + task + mode| W[opencode-worker] |
| 27 | + W -->|one command, stdin closed| O["opencode run --format json"] |
| 28 | + O -->|JSON events| W |
| 29 | + W -->|"git status / diff --stat, report ≤150 words"| C |
| 30 | + C -->|reviews diff, runs tests| C |
| 31 | + C -.->|feedback + session id| W |
26 | 32 | ``` |
27 | | -Claude Code / Claude Desktop / subagent / workflow |
28 | | - │ agent activation (skill, slash-command, subagent) |
29 | | - ▼ |
30 | | -opencode-delegate skill/agent files |
31 | | - │ guide Claude |
32 | | - ▼ |
33 | | -opencode-worker agent (Bash only) |
34 | | - │ runs one command |
35 | | - ▼ |
36 | | -opencode run --format json --agent build --auto [-m <provider/model>] [--session …] -- "<prompt>" |
37 | | -``` |
38 | 33 |
|
39 | | -The `opencode-worker` agent is a thin forwarder: it resolves the model, prefixes the task with a short memory-restore preamble (OpenCode restores its own context from engram, Graphiti and codegraph), runs `opencode run` directly, and reports the session id, the reply and the changed files. Write tasks use `--agent build --auto`; read-only tasks use `--agent plan` without `--auto`. No MCP server, no stdio transport, no bun bundler. |
| 34 | +The worker resolves the model, builds the prompt, runs a single command, checks `git status --short` and `git diff --stat`, and reports the model, session id, exit status, changed files and OpenCode's own report. It never reviews, fixes or retries; iteration means Claude invokes it again with the session id. |
| 35 | + |
| 36 | +```bash |
| 37 | +${OPENCODE_BIN:-opencode} run --format json --agent build --auto [-m provider/model[#variant]] [--session <id>] --title "<title>" -- "<prompt>" </dev/null |
| 38 | +``` |
40 | 39 |
|
41 | | -The `opencode` CLI uses your existing OpenCode auth, config, agents, and permission rules. It |
42 | | -does not use a separate API. |
| 40 | +The run uses your existing OpenCode auth, config, agents and permission rules. |
43 | 41 |
|
44 | 42 | ## Requirements |
45 | 43 |
|
46 | | -- [OpenCode](https://opencode.ai) v2+ with at least one provider set up. Check that |
47 | | - `opencode models` lists something. |
| 44 | +- [OpenCode](https://opencode.ai) v2+ with at least one provider configured (`opencode models` lists something). Behaviour documented here was verified on 2.1.2. |
| 45 | +- `jq` on `PATH` (the worker parses the JSON event stream with it). |
| 46 | +- `git` (changed-file detection). |
48 | 47 |
|
49 | 48 | ## Install |
50 | 49 |
|
51 | | -### Claude Code: plugin (recommended) |
52 | | - |
53 | 50 | ```text |
54 | | -/plugin marketplace add aashahin/claude-opencode-delegate |
| 51 | +/plugin marketplace add lehcode/claude-opencode-delegate |
55 | 52 | /plugin install opencode-delegate@claude-opencode-delegate |
56 | 53 | ``` |
57 | 54 |
|
58 | | -This gives you the **opencode-delegate** skill, the **opencode-worker** agent, and the |
59 | | -**/opencode** command. |
| 55 | +To use a local clone, add it as a directory marketplace: `/plugin marketplace add /path/to/clone`. After pulling changes, refresh the plugin (`/plugin` → update, or reinstall). |
60 | 56 |
|
61 | 57 | ## Usage |
62 | 58 |
|
63 | | -Talk to Claude normally: |
| 59 | +Three entry points, all ending in the same `opencode-worker`: |
64 | 60 |
|
65 | | -- _"Use grok 4.7 from xAI in opencode to implement pagination for /api/users. You review it."_ |
66 | | -- _"Ask kimi k3 via opencode for a second opinion on this diff, read-only."_ |
67 | | -- _"Have glm 5.3 and qwen 3.8 max both implement the parser in separate worktrees, then pick the better one."_ |
68 | | -- `/opencode deepseek v4 flash -- write unit tests for src/date.ts` |
69 | | -- _"Spawn opencode-worker subagents: minimax m3 does the docs, kimi k3 does the tests."_ |
| 61 | +- **Natural language:** "Use kimi k3 via opencode to add tests for `src/date.ts`." |
| 62 | +- **Slash command:** `/opencode deepseek v4 flash -- write unit tests for src/date.ts` |
| 63 | +- **Agent:** spawn `opencode-worker` from a subagent or workflow with the model and task in its prompt. |
70 | 64 |
|
71 | | -### Model names |
| 65 | +### Modes |
72 | 66 |
|
73 | | -You can use exact ids (`opencode-go/grok-4.7`) or loose names (`grok 4.7`, `kimi k3`, `deepseek v4 flash`). |
| 67 | +| Mode | When | OpenCode flags | |
| 68 | +| --------------- | ----------------------------------------- | ---------------------------- | |
| 69 | +| write (default) | Implement, fix, refactor | `--agent build --auto` | |
| 70 | +| read-only | Review, question, summary, second opinion | `--agent plan` (no `--auto`) | |
74 | 71 |
|
75 | | -- A loose name is resolved by the `opencode-worker` agent against the output of `opencode models`, to a single exact `provider/model`. |
76 | | -- A version you name must match exactly, so `grok 4.7` never silently becomes 4.6. |
77 | | -- If a name matches several different models, you get a list of candidates instead of a guess. For example, `mimo` matches several MiMo models. |
78 | | -- Add `#variant` for a reasoning variant: `xai/grok-4.7#high`. |
79 | | -- If you don't name a model, `-m` is omitted and OpenCode uses its own configured default model. |
| 72 | +- Write mode passes `--agent build` because OpenCode's `default_agent` is commonly `plan`. |
| 73 | +- `--auto` approves permissions not explicitly denied; rules set to `deny` are still enforced. |
| 74 | +- Without `--auto`, a headless run auto-rejects permission requests and continues, which is what makes `plan` safe for read-only work. |
| 75 | +- `</dev/null` is mandatory: with an open stdin pipe, `opencode run` waits forever and never creates a session. |
80 | 76 |
|
81 | | -### Slash command |
| 77 | +### Models |
82 | 78 |
|
83 | | -`/opencode <model> -- <task>` — delegate to an OpenCode model. The slash command passes the task to an `opencode-worker` subagent and waits for the result, then reviews the diff and runs the tests. |
| 79 | +| Input | Behaviour | |
| 80 | +| ------------------------ | ---------------------------------------------------------------------------------------------------------------- | |
| 81 | +| none | `-m` omitted; OpenCode uses its configured default model (e.g. `"model"` in `~/.config/opencode/opencode.jsonc`) | |
| 82 | +| exact `provider/model` | Used as is | |
| 83 | +| loose name (`grok 4.7`) | Resolved against `opencode models`; a named version must match exactly (4.7 never becomes 4.6) | |
| 84 | +| ambiguous loose name | Candidate list returned to Claude instead of a guess | |
| 85 | +| `provider/model#variant` | Variant preserved, e.g. `xai/grok-4.7#high` | |
84 | 86 |
|
85 | | -### Agent |
| 87 | +There are no built-in default models. |
86 | 88 |
|
87 | | -The `opencode-worker` agent is a ready-made forwarder. Give it a model and task — it runs `opencode run` and reports the session id, the reply and the changed files. It does not review or retry; Claude reviews, and iterates by invoking the agent again with the session id and feedback. |
| 89 | +### Continuing a session |
88 | 90 |
|
89 | | -### Permissions |
| 91 | +The worker reports a session id. To give feedback, or to continue after a timeout, invoke `opencode-worker` again with that session id and precise feedback. A run is expected to finish within about 10 minutes (Bash tool timeout maximum is 600000 ms). |
90 | 92 |
|
91 | | -Write tasks run with `--agent build --auto`. The delegated model can edit files and run commands without asking, but any rule you set to `deny` in your OpenCode config is still enforced. Read-only tasks (reviews, questions, second opinions) run with `--agent plan` and without `--auto`, so permission requests are rejected. Claude is told to review every change it gets back. |
| 93 | +### Parallel work |
92 | 94 |
|
93 | | -### Using it from workflows |
| 95 | +Spawn one `opencode-worker` per model or subtask. Writers share the working directory, so parallel edits need separate git worktrees (`git worktree add`) or non-overlapping files. To compare models, give the same task to each in its own worktree, then diff the results. |
94 | 96 |
|
95 | | -Workflow `agent()` calls and subagents can use the `opencode-worker` agent directly. If you fan out |
96 | | -tasks that edit files, give each one its own `git worktree` so they don't conflict. |
| 97 | +## Context restore (optional) |
97 | 98 |
|
98 | | -## Configuration (env vars) |
| 99 | +The worker prefixes the task with a short preamble asking OpenCode to restore context itself from engram (`mem_context`, `mem_search`), Graphiti memory and `codegraph_explore`, to stay in scope, not to commit unless told to, and to end with a short report. This works only if those MCP servers are configured in your OpenCode, and it is advisory: models do not always follow it. Without them the preamble is harmless and the task brief should carry the needed context. |
99 | 100 |
|
100 | | -The `opencode-worker` agent honors only `OPENCODE_BIN`. The other variables are read only by the `src/` library. |
| 101 | +## Configuration |
101 | 102 |
|
102 | | -| Variable | Default | Description | |
103 | | -| --------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------ | |
104 | | -| `OPENCODE_BIN` | auto-detected | Path to the `opencode` executable. | |
105 | | -| `OPENCODE_DELEGATE_DEFAULT_MODEL` | `opencode-go/muse-spark-1.3-contributor` | Model used when `model` is omitted. Set it to `""` to use opencode's own default. | |
106 | | -| `OPENCODE_DELEGATE_READ_MODEL` | `opencode/muse-spark-1.3-contributor-free` | Model used when `model` is omitted and `auto` is false (reading files, reviews, questions). Free by default. | |
107 | | -| `OPENCODE_DELEGATE_AUTO` | `true` | Default for `auto`. | |
108 | | -| `OPENCODE_DELEGATE_TIMEOUT` | `1800` | Seconds before a run is killed. | |
109 | | -| `OPENCODE_DELEGATE_MAX_OUTPUT` | `40000` | Maximum number of response characters returned to Claude. | |
110 | | -| `OPENCODE_DELEGATE_CWD` | the server's cwd | Base directory for `cwd`. | |
111 | | -| `OPENCODE_DELEGATE_PREFERRED_PROVIDERS` | _(none)_ | Comma-separated provider order used when a model is offered by several providers, e.g. `xai,opencode-go`. | |
112 | | -| `OPENCODE_DELEGATE_THINKING` | `true` | Include `--thinking` so reasoning/thinking blocks appear in output. | |
| 103 | +| Variable | Default | Description | |
| 104 | +| -------------- | ---------- | ---------------------------------------------------- | |
| 105 | +| `OPENCODE_BIN` | `opencode` | Path to the `opencode` executable used by the worker | |
| 106 | +
|
| 107 | +This is the only variable the plugin honors. |
113 | 108 |
|
114 | 109 | ## Development |
115 | 110 |
|
116 | 111 | ```bash |
117 | 112 | bun install |
118 | | -bun test # unit tests (fixtures captured from real `opencode run --format json`) |
119 | | -bun run typecheck |
120 | | -bun run lint |
121 | | -bun run fmt |
| 113 | +bun run verify # typecheck + test + lint + format |
| 114 | +bun test test/models.test.ts # one file |
| 115 | +bun test -t "<name>" # filter by test name |
| 116 | +git config core.hooksPath hooks/ # pre-commit (staged lint/format), pre-push (verify) |
122 | 117 | ``` |
123 | 118 |
|
| 119 | +`.prettierignore` excludes local `.atl/`, `openspec/` and `odd/`. Tests are fixture-based and need no running services. |
| 120 | +
|
| 121 | +### Library (`src/`) |
| 122 | +
|
| 123 | +`src/` is a TypeScript library (`delegate`, `resolveModel`, `buildArgs`, `EventCollector`) left from the removed MCP server. No plugin surface imports it; only the tests exercise it, and it is the reference for how `opencode run` is invoked and its JSON stream parsed. Changing it does not change plugin behaviour. Its provider preference (direct provider over an aggregator, `OPENCODE_DELEGATE_PREFERRED_PROVIDERS` first) applies only here, not to the worker. Variables read by `src/config.ts`: |
| 124 | +
|
| 125 | +| Variable | Default | Description | |
| 126 | +| --------------------------------------- | ------------------- | ----------------------------------------------------------------- | |
| 127 | +| `OPENCODE_BIN` | auto-detected | Path to `opencode` | |
| 128 | +| `OPENCODE_DELEGATE_DEFAULT_MODEL` | see `src/config.ts` | Model when none given; empty string means OpenCode's own default | |
| 129 | +| `OPENCODE_DELEGATE_READ_MODEL` | see `src/config.ts` | Model when none given and `auto` is false; empty string as above | |
| 130 | +| `OPENCODE_DELEGATE_AUTO` | `true` | Default for `auto`; `0`, `false`, `no`, `off` disable it | |
| 131 | +| `OPENCODE_DELEGATE_TIMEOUT` | `1800` | Seconds before a run is killed | |
| 132 | +| `OPENCODE_DELEGATE_MAX_OUTPUT` | `40000` | Maximum response characters returned | |
| 133 | +| `OPENCODE_DELEGATE_THINKING` | `true` | Include reasoning blocks in output | |
| 134 | +| `OPENCODE_DELEGATE_CWD` | process cwd | Base working directory | |
| 135 | +| `OPENCODE_DELEGATE_PREFERRED_PROVIDERS` | none | Comma-separated provider order when a model has several providers | |
| 136 | +
|
124 | 137 | ## License |
125 | 138 |
|
126 | | -MIT |
| 139 | +MIT. Originally created by [aashahin](https://github.com/aashahin). |
0 commit comments