Skip to content

Commit 501d133

Browse files
committed
docs(readme): document thin opencode-worker and drop MCP-era claims
1 parent c58b5b4 commit 501d133

1 file changed

Lines changed: 89 additions & 76 deletions

File tree

‎README.md‎

Lines changed: 89 additions & 76 deletions
Original file line numberDiff line numberDiff line change
@@ -1,126 +1,139 @@
11
# claude-opencode-delegate
22

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

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
710
```
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
1111

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
1613

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

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

2422
## How it works
2523

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
2632
```
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-
```
3833

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+
```
4039
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.
4341
4442
## Requirements
4543
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).
4847
4948
## Install
5049
51-
### Claude Code: plugin (recommended)
52-
5350
```text
54-
/plugin marketplace add aashahin/claude-opencode-delegate
51+
/plugin marketplace add lehcode/claude-opencode-delegate
5552
/plugin install opencode-delegate@claude-opencode-delegate
5653
```
5754
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).
6056
6157
## Usage
6258
63-
Talk to Claude normally:
59+
Three entry points, all ending in the same `opencode-worker`:
6460
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.
7064
71-
### Model names
65+
### Modes
7266
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`) |
7471
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.
8076
81-
### Slash command
77+
### Models
8278
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` |
8486
85-
### Agent
87+
There are no built-in default models.
8688
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
8890
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).
9092
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
9294
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.
9496
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)
9798
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.
99100
100-
The `opencode-worker` agent honors only `OPENCODE_BIN`. The other variables are read only by the `src/` library.
101+
## Configuration
101102
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.
113108
114109
## Development
115110
116111
```bash
117112
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)
122117
```
123118
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+
124137
## License
125138
126-
MIT
139+
MIT. Originally created by [aashahin](https://github.com/aashahin).

0 commit comments

Comments
 (0)