Skip to content

docs(settings): Say why OpenCode registration needs a restart - #757

Merged
omesser merged 1 commit into
mainfrom
fix/opencode-registration-says-restart
Sep 16, 2026
Merged

omesser merged 1 commit into
mainfrom
fix/opencode-registration-says-restart

Conversation

@omesser

@omesser omesser commented Sep 15, 2026 •

Copy link
Copy Markdown
Owner

What changed

Eight lines of comment above byo_registration()'s opencode arm. No behaviour, no user-facing text.

Why this shrank

This PR opened as a fix for the OpenCode registration steps, which told users to run /reload. That command does not exist. While it was in flight, main got the same correction from someone else — the steps now read "then restart your OpenCode session. OpenCode does not re-read MCP mid-session."

So the user-facing half is already done, and I rebased onto it and kept their wording. What is still missing is the reason. Read cold, "OpenCode does not re-read MCP mid-session" is a bare assertion with no source, and the next person to touch this arm has nothing to check it against.

The comment records two things:

  • Where the wrong instruction came from. sst/opencode#6719 is titled "[FEATURE]: slash command for reload" and is open. It was read as documentation of a shipped command. The same misreading put a ✅ in the research doc's reload table, corrected in docs(research): Record that prompting cannot register an MCP server #743.
  • What was measured. Against OpenCode 1.18.30, a headless opencode serve was started with one MCP server in its config, and a second was written into that same file with the process running. GET /mcp and GET /config both still reported only the first. Configuration is read once at start and cached.

That is cheap insurance against someone restoring /reload from the same source that put it there in the first place.

Verification

cargo test -p ai-buddy byo   # 8 passed

Comment-only, so nothing else can move. Full suites were green before the rebase reduced this to a comment: cargo test -p ai-buddy 475 passed, node --test tests/ 203 passed.

Not touched

pi's arm still says /reload then /mcp reconnect ai-buddy. Pi 0.85.1 does have /reload, whose banner names "keybindings, extensions, skills, prompts, themes, and context files" — MCP is not listed, but Pi gets MCP through an extension, so reloading extensions may cover it. /mcp reconnect is absent from Pi's core bundle, though extensions can contribute commands and pi-mcp-adapter is not installed here to check. Both halves are plausible and neither is proven, so changing them would swap one unverified instruction for another.

Related: #577, #580, #599, #743.

— Claude Code agent, on @omesser's behalf.

🤖 Generated with Claude Code

The steps were corrected on main while this was in flight, so the user-facing
text is already right. What is missing is the reason, and without it the next
reader has a bare assertion that OpenCode "does not re-read MCP mid-session".

Record what was measured and where the wrong instruction came from.
`anomalyco/opencode#6719` is titled "[FEATURE]: slash command for reload" and is
open, so `/reload` was never a shipped command. Against OpenCode 1.18.30, a
server written into the config of a running `opencode serve` never appeared in
`GET /mcp` or `GET /config`.

Cheap insurance against someone restoring `/reload` from the same source that
put it there the first time.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@omesser
omesser force-pushed the fix/opencode-registration-says-restart branch from 3e0bd00 to aef90cf Compare September 15, 2026 23:23
@omesser omesser changed the title fix(settings): Tell OpenCode users to restart, not to run /reload docs(settings): Say why OpenCode registration needs a restart Sep 15, 2026
@omesser
omesser merged commit 78ebbe6 into main Sep 16, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant