You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 2f7b37e
Browse filesBrowse the repository at this point in the historyBrowse files
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]>
Copy file name to clipboardExpand all lines: docs/research/byo-harness-mcp-reload.md
+35-15Lines changed: 35 additions & 15 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -21,7 +21,7 @@ This research answers:
21
21
|**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) |
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`."
205
205
206
206
---
207
207
@@ -316,13 +316,13 @@ This confirms #580's finding: the stdio shim is never required for bearer auth.
| ❌ **No** | **OpenCode** | Must restart; see §6 |
324
324
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.
326
326
327
327
### 3. The Claude Code Re-Add Trap
328
328
@@ -392,17 +392,36 @@ pastes. There is no version of this where ai-buddy talks the harness into
392
392
registering itself, so nothing should be designed on the assumption that one
393
393
arrives later.
394
394
395
-
#### One unresolved conflict with the table in §2
395
+
#### OpenCode does not reload, and the `/reload` in §2 was never shipped
396
396
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.
403
400
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.
406
425
407
426
---
408
427
@@ -431,7 +450,7 @@ rather than exercising it, which matches the `~` this research already gives it.
431
450
| Claude Code | "Exit your Claude session and start a new one with `claude`." |
432
451
| Codex | "Run `mcpServer/refresh` from your Codex session." (or "Restart your Codex session" if refresh unavailable) |
433
452
| Hermes | "Run `/reload-mcp` in your Hermes session." |
434
-
| OpenCode | "Run `/reload` in your OpenCode session." |
453
+
| OpenCode | "Restart OpenCode." |
435
454
| Grok | "Run `/mcps`, then press `r` to reload." |
436
455
| Pi | "Run `/reload`, then `/mcp reconnect ai-buddy`." |
437
456
@@ -568,6 +587,7 @@ These are answerable with execution once harness CLIs are installed.
568
587
## Change Log
569
588
570
589
- **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.
572
592
573
593
_— Cursor agent (Coder), on [@omesser](https://github.com/omesser)'s behalf._
0 commit comments