Skip to content

Commit 2f7b37e

Browse files
omesserclaude
andcommitted
docs(research): OpenCode does not reload; correct the table
The reload table credited OpenCode with a `/reload` slash command, and §6 carried the registration pass's opposite finding as an open contradiction. Ran it again on 1.18.30 and the registration pass was right. A headless `opencode serve` was started against a config holding one MCP server, then a second was written into the same file with the process left running. `GET /mcp` and `GET /config` both still reported only the first, so the configuration is read once at start and never re-read. The `/reload` came from this document's own source list: `anomalyco/opencode#6719` is titled "[FEATURE]: slash command for reload" and is open. A request, not a command. Corrected the summary table, the reload table, the per-harness instruction and the #599 recommendation — two of six harnesses need a restart, not one. `POST /mcp` was confirmed in the same run: it registers a server in memory with no restart and no config write, and `POST /mcp/{name}/connect` exists too. Neither helps the BYO case, which has no address for the user's server. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
1 parent e83d806 commit 2f7b37e

1 file changed

Lines changed: 35 additions & 15 deletions

File tree

‎docs/research/byo-harness-mcp-reload.md‎

Lines changed: 35 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ This research answers:
2121
| **Claude Code** | `claude mcp add --header "Authorization: Bearer <token>"` | **No** — must exit and restart session | **Yes** — silently keeps stale | CLI with `remove` then `add` (omit `-s`, local default) |
2222
| **Codex** | CLI: `export` + `codex mcp add --bearer-token-env-var`; Alt: config with `http_headers` | **Yes** — `mcpServer/refresh` command | Unknown | CLI `export` + `codex mcp add` (TOML alt) |
2323
| **Hermes** | CLI: `hermes mcp add --auth header`; Alt: config YAML | **Yes** — `/reload-mcp` | Unknown | CLI `hermes mcp add --auth header` (YAML alt) |
24-
| **OpenCode** | CLI: `opencode mcp add --header`; Alt: flat JSON `type:remote` + `oauth:false` | **Yes** — `/reload` | Unknown | CLI `opencode mcp add --header` (flat JSON alt) |
24+
| **OpenCode** | CLI: `opencode mcp add --header`; Alt: flat JSON `type:remote` + `oauth:false` | **No** — restart; `/reload` does not exist (§6) | Unknown | CLI `opencode mcp add --header` (flat JSON alt) |
2525
| **Grok** | `grok mcp add` with `--header`, or config TOML | **Yes** — `/mcps` then press `r` | Unknown | CLI `grok mcp add` (default scope: user) |
2626
| **Pi** | Config: `.mcp.json` or `~/.pi/agent/mcp.json` | **Yes** — `/reload` + `/mcp reconnect` | Unknown | Config snippet + `/reload` |
2727

@@ -201,7 +201,7 @@ CLI (PRIMARY):
201201
opencode mcp add ai-buddy --url 'http://127.0.0.1:<port>/mcp' --header "Authorization=Bearer <token>"
202202
```
203203

204-
Instructions: "Run it in a terminal, then run `/reload` in your OpenCode session. If OpenCode tries OAuth, set `\"oauth\": false` in the config. Alternatively, merge flat `mcp.ai-buddy` content into `opencode.jsonc` (NOT nested `mcp.servers.<name>` shape); use `type: \"remote\"` and `oauth: false`."
204+
Instructions: "Run it in a terminal, then restart OpenCode. If OpenCode tries OAuth, set `\"oauth\": false` in the config. Alternatively, merge flat `mcp.ai-buddy` content into `opencode.jsonc` (NOT nested `mcp.servers.<name>` shape); use `type: \"remote\"` and `oauth: false`."
205205

206206
---
207207

@@ -316,13 +316,13 @@ This confirms #580's finding: the stdio shim is never required for bearer auth.
316316
| Has Native Reload | Harness | Method |
317317
|-------------------|---------|--------|
318318
| ✅ Yes | Hermes | `/reload-mcp` |
319-
| ✅ Yes | OpenCode | `/reload` |
320319
| ✅ Yes | Grok | `/mcps` + `r` |
321320
| ✅ Yes | Pi | `/reload` + `/mcp reconnect` |
322321
| ✅ Yes | Codex | `mcpServer/refresh` |
323322
| ❌ **No** | **Claude Code** | Must restart session |
323+
| ❌ **No** | **OpenCode** | Must restart; see §6 |
324324

325-
**Inference**: Five of six harnesses support mid-session reload. Only Claude Code requires full session restart.
325+
**Fact**: Four of six harnesses support mid-session reload. Claude Code and OpenCode both require a restart; OpenCode's entry was corrected in §6 after a live run.
326326

327327
### 3. The Claude Code Re-Add Trap
328328

@@ -392,17 +392,36 @@ pastes. There is no version of this where ai-buddy talks the harness into
392392
registering itself, so nothing should be designed on the assumption that one
393393
arrives later.
394394

395-
#### One unresolved conflict with the table in §2
395+
#### OpenCode does not reload, and the `/reload` in §2 was never shipped
396396

397-
The §2 table credits OpenCode with `/reload`. The earlier registration pass
398-
recorded the opposite from a live run of OpenCode 1.18.30: *"not hot-reloaded…
399-
quit and restart"*, quoted from the harness itself. Both cannot be right. Until
400-
someone re-runs it, treat OpenCode's mid-session reload as unverified rather
401-
than as the ✅ the table shows, and generate its snippet with a restart
402-
instruction.
397+
The §2 table originally credited OpenCode with `/reload`, while the earlier
398+
registration pass recorded the opposite from a live run. Settled by running it
399+
again on OpenCode 1.18.30, and the registration pass was right.
403400

404-
The same pass also reached Grok's refresh by reading its shipped documentation
405-
rather than exercising it, which matches the `~` this research already gives it.
401+
**Fact** (ran, 2026-09-16): a headless `opencode serve` was started against a
402+
throwaway config holding one MCP server, `alpha`. A second server, `beta`, was
403+
then written into that same config file with the process left running. Three
404+
seconds later `GET /mcp` still reported only `alpha`, and `GET /config` still
405+
returned an `mcp` object with `alpha` alone in it. The configuration is read
406+
once at start and cached; a file the user edits mid-session is not seen.
407+
408+
**Fact** (read): `sst/opencode#6719`, cited in this document's own sources, is
409+
titled *"[FEATURE]: slash command for reload"* and is **open**. It is a request
410+
for `/reload`, not documentation of it. That is where the ✅ came from.
411+
412+
**Fact** (ran, 2026-09-16): `POST /mcp` (`mcp.add`) does work, exactly as §6
413+
describes. Posting `gamma` to a running server registered it immediately and
414+
OpenCode attempted the connection, with no restart and no config write. The
415+
server list also carries `POST /mcp/{name}/connect` and
416+
`POST /mcp/{name}/disconnect`, so a registered server can be reconnected in
417+
place. None of this rescues the BYO case: every route needs the address of the
418+
user's own OpenCode server, which ai-buddy does not have.
419+
420+
**Implication for ai-buddy**: generate OpenCode's snippet with a restart
421+
instruction, alongside Claude Code's. Two of six, not one.
422+
423+
Grok's refresh remains read from its shipped documentation rather than
424+
exercised, which matches the `~` this research already gives it.
406425

407426
---
408427

@@ -431,7 +450,7 @@ rather than exercising it, which matches the `~` this research already gives it.
431450
| Claude Code | "Exit your Claude session and start a new one with `claude`." |
432451
| Codex | "Run `mcpServer/refresh` from your Codex session." (or "Restart your Codex session" if refresh unavailable) |
433452
| Hermes | "Run `/reload-mcp` in your Hermes session." |
434-
| OpenCode | "Run `/reload` in your OpenCode session." |
453+
| OpenCode | "Restart OpenCode." |
435454
| Grok | "Run `/mcps`, then press `r` to reload." |
436455
| Pi | "Run `/reload`, then `/mcp reconnect ai-buddy`." |
437456

@@ -568,6 +587,7 @@ These are answerable with execution once harness CLIs are installed.
568587
## Change Log
569588
570589
- **2026-09-12**: Initial research document created. Covers six harnesses (Claude Code, Codex, Hermes, OpenCode, Grok, Pi). Documented reload mechanisms, re-add trap (Claude Code), and config locations. Recommendations for PR #599 Settings UI.
571-
- **2026-09-16**: Added §6, Prompting Is Not a Route, carried over from an earlier registration pass (branch `research/byo-harness-mcp`) that never reached a pull request. That pass covered five harnesses — Claude Code, Hermes, OpenCode, Grok and Codex — and did not examine Pi, so §6 says nothing about Pi. It also contradicts this document on OpenCode's mid-session reload, which §6 records rather than resolves.
590+
- **2026-09-16**: Added §6, Prompting Is Not a Route, carried over from an earlier registration pass (branch `research/byo-harness-mcp`) that never reached a pull request. That pass covered five harnesses — Claude Code, Hermes, OpenCode, Grok and Codex — and did not examine Pi, so §6 says nothing about Pi. It also contradicted this document on OpenCode's mid-session reload.
591+
- **2026-09-16**: Settled that contradiction by running OpenCode 1.18.30 again. It does not re-read its config mid-session, and the `/reload` this document credited it with is an open feature request (`sst/opencode#6719`), not a shipped command. Corrected the summary table, the reload table, the per-harness instruction, and the #599 recommendation. Confirmed `POST /mcp` in-memory registration at the same time.
572592
573593
_— Cursor agent (Coder), on [@omesser](https://github.com/omesser)'s behalf._

0 commit comments

Comments
 (0)