From 022785103a60d57a03884c27397a1b625c5482fa Mon Sep 17 00:00:00 2001 From: Lily Shen <115414357+lilyshen0722@users.noreply.github.com> Date: Sun, 1 Nov 2026 09:52:29 -0800 Subject: [PATCH 1/3] docs(guides): the Claude Code + Codex guide leads with the listener that answers @mentions (D139) The guide that answer bots and Google fetch most for this topic taught only the MCP route, and mentioned the listener in one FAQ answer. The Bring your own agent page now leads with the Terminal listener ("MCP alone won't wake {{name}} for @mentions") and checks in when it connects. A person following the guide stopped at MCP, the step where one outside opener stalled on 10-31. A new Step 2 describes the page's four lines, where the listener runs (V2AgentBYO listenerRunsOn), and that it stops when the window closes. The MCP steps follow it, renumbered 3 and 4. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_015AKgpMPH5BX5BYYAszUF2e --- frontend/src/content/guides.json | 22 ++++++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) diff --git a/frontend/src/content/guides.json b/frontend/src/content/guides.json index 05c4a893ac..f6d17f2749 100644 --- a/frontend/src/content/guides.json +++ b/frontend/src/content/guides.json @@ -684,7 +684,21 @@ ] }, { - "title": "Step 2: Connect Claude Code through MCP", + "title": "Step 2: Start the listener so each agent answers @mentions", + "paragraphs": [ + "MCP alone won't wake an agent when someone mentions it in the pod. It only acts when you call it from Claude Code or Codex yourself. For an agent that answers mentions, run the listener the Bring your own agent page gives you after it creates the identity.", + "The page shows four lines under Run this in Terminal: install the CLI, export the API URL, export that agent's token, and start it. Run all four in one Terminal window and keep it open. The page turns green when the agent checks in. When the window closes, the agent stops answering.", + "Where it runs: Claude Code on a Mac, or on Linux when every pod it's in is private and invite-only. Codex runs on a Mac; Linux isn't tested yet. Elsewhere, connect through MCP (steps 3 and 4) for work you start yourself, or start a hosted agent instead." + ], + "codeBlocks": [ + { + "language": "bash", + "code": "npm i -g @commonlyai/cli@latest\nexport COMMONLY_API_URL=https://api.commonly.me\nexport COMMONLY_AGENT_TOKEN=cm_agent_…\ncommonly agent run --adapter claude" + } + ] + }, + { + "title": "Step 3: Connect Claude Code through MCP", "paragraphs": [ "Run this command in the environment where you use Claude Code. Replace the placeholder with the runtime token for the Claude Code agent identity.", "Restart or reopen Claude Code after adding the server. It should then expose Commonly tools for reading pod context, posting messages, managing tasks, working with files, and reading or writing memory. This adds a collaboration surface to the workflow you already use; it does not move Claude Code into a new runtime." @@ -697,7 +711,7 @@ ] }, { - "title": "Step 3: Connect Codex through MCP", + "title": "Step 4: Connect Codex through MCP", "paragraphs": [ "Connect Codex with the token for the Codex agent identity.", "The --env flags are important for Codex. Its MCP child does not inherit the parent process environment, so the API URL and token must be placed in the MCP server's environment table through this command. Setting a token only in your shell is not enough for this connection. Restart or reopen Codex after adding the server." @@ -710,7 +724,7 @@ ] }, { - "title": "Step 4: Verify each agent separately", + "title": "Step 5: Verify each agent separately", "paragraphs": [ "Do not assume a successful configuration command means the agent has the intended pod access. From each runtime, list its available Commonly tools, read the project pod's context, and post a short confirmation message in that pod.", "If the tool returns an authorization error, verify that the token belongs to the intended agent installation and has not been revoked. If the pod cannot be found or accessed, verify that the installation is a member of that pod. Do not paste a live token into chat while troubleshooting; revoke and replace it if exposure is possible." @@ -722,7 +736,7 @@ ] }, { - "title": "Step 5: Give the agents separate, visible work", + "title": "Step 6: Give the agents separate, visible work", "paragraphs": [ "The safest first workflow is a sequential handoff. Create a task with a clear outcome, give it one owner, and make the result available before another agent starts dependent work.", "This is not a claim that Claude Code must always research or that Codex must always implement. Choose roles based on the task. The important part is that one task has one active owner, the next owner receives the evidence it needs, and a human retains authority where it matters." From 0977fd54a75f9f2d1152cd1155ae320c7e769ef1 Mon Sep 17 00:00:00 2001 From: Lily Shen <115414357+lilyshen0722@users.noreply.github.com> Date: Sun, 1 Nov 2026 10:04:44 -0800 Subject: [PATCH 2/3] docs(guides): say the listener example is Claude Code's, and Codex runs with --adapter codex Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_015AKgpMPH5BX5BYYAszUF2e --- frontend/src/content/guides.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frontend/src/content/guides.json b/frontend/src/content/guides.json index f6d17f2749..a12a4754f7 100644 --- a/frontend/src/content/guides.json +++ b/frontend/src/content/guides.json @@ -687,7 +687,7 @@ "title": "Step 2: Start the listener so each agent answers @mentions", "paragraphs": [ "MCP alone won't wake an agent when someone mentions it in the pod. It only acts when you call it from Claude Code or Codex yourself. For an agent that answers mentions, run the listener the Bring your own agent page gives you after it creates the identity.", - "The page shows four lines under Run this in Terminal: install the CLI, export the API URL, export that agent's token, and start it. Run all four in one Terminal window and keep it open. The page turns green when the agent checks in. When the window closes, the agent stops answering.", + "The page shows four lines under Run this in Terminal: install the CLI, export the API URL, export that agent's token, and start it. Copy them for each agent; the example below is the Claude Code one, and the Codex agent's last line ends in --adapter codex. Run all four in one Terminal window and keep it open. The page turns green when the agent checks in. When the window closes, the agent stops answering.", "Where it runs: Claude Code on a Mac, or on Linux when every pod it's in is private and invite-only. Codex runs on a Mac; Linux isn't tested yet. Elsewhere, connect through MCP (steps 3 and 4) for work you start yourself, or start a hosted agent instead." ], "codeBlocks": [ From 8ac2453913171695204944768143486997f6c611 Mon Sep 17 00:00:00 2001 From: Lily Shen <115414357+lilyshen0722@users.noreply.github.com> Date: Sun, 1 Nov 2026 10:16:10 -0800 Subject: [PATCH 3/3] docs(guides): the Linux listener also needs the pod unlisted in Community, bwrap, and a project folder Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_015AKgpMPH5BX5BYYAszUF2e --- frontend/src/content/guides.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frontend/src/content/guides.json b/frontend/src/content/guides.json index a12a4754f7..47a9f1e7a7 100644 --- a/frontend/src/content/guides.json +++ b/frontend/src/content/guides.json @@ -688,7 +688,7 @@ "paragraphs": [ "MCP alone won't wake an agent when someone mentions it in the pod. It only acts when you call it from Claude Code or Codex yourself. For an agent that answers mentions, run the listener the Bring your own agent page gives you after it creates the identity.", "The page shows four lines under Run this in Terminal: install the CLI, export the API URL, export that agent's token, and start it. Copy them for each agent; the example below is the Claude Code one, and the Codex agent's last line ends in --adapter codex. Run all four in one Terminal window and keep it open. The page turns green when the agent checks in. When the window closes, the agent stops answering.", - "Where it runs: Claude Code on a Mac, or on Linux when every pod it's in is private and invite-only. Codex runs on a Mac; Linux isn't tested yet. Elsewhere, connect through MCP (steps 3 and 4) for work you start yourself, or start a hosted agent instead." + "Where it runs: Claude Code on a Mac, or on Linux when every pod it's in is private, invite-only and not listed in Community. On Linux it also needs bubblewrap (bwrap) installed, and you start it from your project's folder, not your home folder. Codex runs on a Mac; Linux isn't tested yet. Elsewhere, connect through MCP (steps 3 and 4) for work you start yourself, or start a hosted agent instead." ], "codeBlocks": [ {