Connect your AI GUILDUO
Use Guilduo with Codex: MCP Setup and Your First Quest
Use Codex to read a task saved in Guilduo and continue from its goal, progress and human feedback. Start with one read-only check; installation and an Agent record alone do not start work or authorize writes.
Before you connect
- A Google account for Guilduo / Relay Forge and one small saved Quest with a goal and completion criteria.
- Codex CLI 0.159.2 or your installed Windows Desktop, with access to its normal AI subscription or API environment. External AI costs and requirements are separate.
- Remote HTTP MCP and OAuth access to https://mcp.guilduo.com/mcp. This is a public beta guide; setup time is not guaranteed.
- If Guilduo is already connected as an App, keep the App companion route below instead of installing a second MCP connection.
Install from the standard marketplace
Guilduo plugin distribution version: 0.6.0-beta.12.
Targets: Codex CLI 0.159.2 and the installed Windows Desktop. If guilduo-local already supplies an App companion, keep that mode and update it instead of adding the normal MCP package.
codex plugin marketplace add ELRdn/Guilduo --ref main
codex plugin add guilduo-workflows@guilduo-local
codex plugin list --marketplace guilduo-local --jsonRead one Quest and check success
- Complete OAuth in Codex connection settings, then open a fresh chat with the Guilduo Skill available.
- Ask Codex to read its current Agent context, list your Quests and read the exact small Quest you created. Do not authorize a write for this check.
- Compare the returned title, goal and saved state with Guilduo Web. A listed plugin or 56 discovered tools alone does not establish a successful task read.
- For later writes, link an authorized registered Agent in Web Connections, confirm its effective permissions and scope the task explicitly. Recheck the latest state and read back changes.
October 10, 2026 acceptance record and limits
The developer acceptance record dated October 10, 2026 reports Windows CLI 0.159.2 installation and discovery of Skill and hook definitions, plus the owner's App-companion update and cache match. Credential reuse and tool discovery were recorded through process-only direct OAuth.
Using the exact model ID openai/gpt-6-astra and an explicitly selected canonical Skill, the record covers limited updates and readback, no-op behavior, and read-only rereads after stale-write rejection. It also records retrieval of the owner's saved Web answer to a Human request and resumption in the same Agent session.
This summarizes historical developer acceptance; the October 12, 2026 content review did not rerun real-environment tests. It does not establish a Codex-to-Claude handoff or measured time savings. Full Desktop lifecycle, trusted-hook execution, OAuth refresh, revocation and reconnection remain unaccepted. The result does not establish write acceptance through stale App tool schemas or automatic Skill loading by the standard plugin.
Reuse an existing App connection
Use the actual App ID, never a token. Generate from the public source root and keep its output directory. After restart, verify the cache and a new chat contain one enabled guilduo-workflows:guilduo-workflows Skill and one intended connection.
npx tsx tools/prepare-guilduo-plugin.mts --app-id YOUR_REGISTERED_GUILDUO_APP_ID --hooks
codex plugin marketplace add ./.qa-artifacts/guilduo-plugin-hooks
codex plugin add guilduo-workflows@guilduo-localEnable assistance only after explicit permission and binding
Review and trust the exact hooks in the host, obtain continuation permission, then bind the verified exact session, canonical cwd, Quest and Agent. Exclusive receipts keyed by session_id + turn_id limit additional checks to one per original input, including after rebinding. Missing identifiers/recursion state, storage failure and invalid bindings suppress assistance. Installation alone starts no synchronization; see the bundled hooks/README.md.
Verify Agent permissions and saved Human feedback
Installation does not register an Agent. Free allows two registered Agents. Reuse an authorized Agent and supply actingAgentId on every shared-connection call. Read get_current_agent_context for the allowlist and effective scopes; confirm expectedUpdatedAt in fresh discovery. Read back limited updates, skip unchanged content and reread conflicts. update_quest has no dryRun. Resume only after reading the owner’s actual saved Web response to a Human request.
Update, disable, disconnect and remove
Upgrade a Git marketplace, reinstall the same plugin and check its cached version. Unbind stops assistance; the host Stop button interrupts inference. Verify write suppression for Plan, read-only, fork, revoked permission and interruption. Disable in host settings, disconnect OAuth in connection settings and Guilduo Web, then remove the plugin.
codex plugin marketplace upgrade guilduo-local
codex plugin add guilduo-workflows@guilduo-local
# Remove only when no longer needed:
codex plugin remove guilduo-workflows@guilduo-localSources for this article
Edited from the public GitHub documentation. Read the original sources for specification details.
Content reviewed: · Public source revision: 479b211
- docs/guilduo-next-hosts.md
- docs/guilduo-next-hosts.jp.md
- skills/guilduo-workflows/SKILL.md
- PROJECT_SPEC.md
- plugins/guilduo-workflows/README.md
- plugins/guilduo-workflows/hooks/README.md
- docs/acceptance/guilduo-next-hosts-codex.md
- Host acceptance and remaining gates
- Dated final acceptance and remaining gates