Use Guilduo with OpenCode

Requirements

• Tested on Windows with OpenCode 1.18.32 and 1.18.35. OpenCode v2 compatibility is untested.
• OpenCode owns authentication and credential storage. The plugin adds no credential store or token bridge.
• Normal installation starts no extra model continuation. phaseSync is OFF by default.

Add the plugin to opencode.json

Add this entry to your existing project plugin array, preserving other plugins and settings. Exit every OpenCode process using the configuration before changing it.

1. Restart to load the compiled plugin and Skill. No consumer build is needed. Replace @latest with @0.6.0-beta.16 for a fixed release.
2. Existing official-endpoint aliases, disabled settings and occupied guilduo keys are preserved. Resolve conflicting endpoints in your own MCP settings.

{
  "plugin": [
    "@guilduo/opencode-plugin@latest"
  ]
}

Use native OpenCode OAuth

The endpoint is https://mcp.guilduo.com/mcp. Substitute your existing alias for guilduo when applicable. Approve the same Guilduo account in the browser and return to the host. Do not paste callback URLs or authentication files into chat.

opencode mcp list
opencode mcp auth guilduo
opencode mcp auth list

Check the Agent and task permission

Free allows 2 registered Agents. Installation, OAuth and Agent linking neither register an Agent automatically nor authorize continuing Quest writes. The guilduo-workflows Skill guides authorized work; it grants no completion, acceptance or reward permission. OAuth connection-management grants and Agent execution scopes are distinct. Do not broaden execution scopes to fix a linking error.

1. Read get_agent_link first to check the association with the intended existing Registry Agent. Use list_registered_agents to identify an existing permitted Agent if needed. Never infer IDs from display names or client names.
2. For an unlinked dedicated connection, obtain explicit owner approval and pass the existing Agent ID to link_agent. Preserve a correct link. Never use link_agent to switch a shared connection between Agents.
3. Read get_current_agent_context and the exact get_quest, and check the returned Agent and Quest IDs. When requiresAgentSelection is true, select the owner-authorized actingAgentId from allowedAgentIds and retain it on every preview, read and write call.
4. Authorize the exact Quest and allowed changes before working. Preview tools that support dryRun. For update_quest, send a narrow patch with fresh expectedUpdatedAt and read back the saved result; do not send dryRun to update_quest.

Check loading and connection

--version reports the host version. Check that guilduo-workflows is listed and MCP has the intended connection status. Then actually read the Agent context and exact Quest. Saved authorization or tool discovery alone proves no successful read or write.

opencode --version
opencode debug skill
opencode mcp list
opencode mcp auth list

Optional: enable phaseSync for one conversation

Use this only for a Quest/Agent pair with continuing update permission. In a new project, create a native session with phaseSync OFF, fully exit OpenCode, then set its existing session ID and exact host-resolved cwd and restart. Replace the placeholders below with verified values.

• After a matching build session completes a stop response and becomes idle, it can request at most one extra model check per original user input. Provider costs may apply. It never writes MCP directly.
• The exact binding includes directory casing. Do not copy it to new conversations or forks. Plan/read-only, errors, compaction, mismatches and disabled MCP suppress continuation. Failed or ambiguous delivery is not automatically retried.

{
  "plugin": [
    [
      "@guilduo/opencode-plugin@latest",
      {
        "phaseSync": {
          "sessionId": "ses-your-existing-session",
          "questId": "your-quest-id",
          "actingAgentId": "your-allowed-agent-id",
          "cwd": "D:\\your-project"
        }
      }
    ]
  ]
}

Update and stop

Exit OpenCode, review compatibility and the release, and set the plugin entry to latest or a reviewed fixed version. Preserve other settings, restart, and recheck the Skill, connection and first read.

Use native interrupt/abort to stop current inference. For a persistent phaseSync stop, exit the host, remove the option or set it to false, and restart.

When a binding and free command name exist, /guilduo-sync-off clears that conversation binding until plugin reload; it does not stop a different conversation. Slash commands submit prompts, so this does not abort inference or guarantee a cost-free stop. Withdraw task permission and OAuth separately.

Disconnect and remove

The host manages the npm plugin entry. Explicit MCP settings and native authentication survive plugin removal. If you installed a local archive into dedicated .opencode/guilduo, remove it only from that dedicated prefix. Do not run npm uninstall against shared .opencode and affect other packages.

1. Log out using your alias and disable phaseSync. To prevent reconnection, retain an explicit official MCP entry with enabled: false. Deleting the entry alone lets the plugin restore its default on reload.
2. Revoke server-side authorization separately through connection management at https://app.guilduo.com/.
3. Exit OpenCode and remove only this plugin string/tuple from opencode.json and any separately installed loader. Restart and check that the Skill and plugin-owned command disappear.

opencode mcp logout guilduo
opencode mcp auth list

Accepted scope and upstream listing

On Windows 1.18.35, the records cover public OAuth, dedicated linked Agent/Quest reads, narrow version-guarded updates and readback, saved Human answer → same Go session resumption, public refresh triggered by a QA 401 carrier, revocation and reconnection. Real-model phaseSync checks used synthetic loopback MCP on both tested host versions; they are separate from public phaseSync acceptance.

OpenCode Ecosystem PR #54271 was closed without merge under the v1 critical-fixes-only policy. Official OpenCode directory listing is incomplete. Cross-Agent selection on shared connections is unaccepted. These limits are separate from installing the published npm package.