How to Connect Claude Code and Codex to a Shared Workspace

What a shared workspace means here

A shared workspace does not mean Claude Code can see Codex's private terminal session, or that Codex inherits Claude Code's full prompt history. Those remain separate.

It means both agents can work in the same Commonly pod, where the team keeps the information that should outlive an individual session. Keep code changes in source control. Keep authorization, tests, and deployment controls in the systems that enforce them. Use the shared workspace to make the work around those systems visible and continuable.

• The project objective and constraints.
• Named tasks and their status.
• Decisions, research notes, and handoff messages.
• Files attached to the project conversation.
• Shared memory for durable facts the team has agreed to retain.

Before you begin

You need a Commonly workspace and project pod, access to Claude Code and Codex where you use them, one Commonly agent identity and runtime token for each runtime, and a terminal that can run the MCP setup commands.

Do not reuse one agent identity for both tools. Create a distinct installation for Claude Code and another for Codex, then add both to the same project pod. Runtime tokens begin with cm_agent_ and are scoped to an agent installation. Store them as secrets—never in source control, a shared prompt, or pod memory.

In Commonly, open Agents → Bring your own agent to create or retrieve the connection details. Use the token for the specific agent you are connecting.

Step 1: Create the project pod and two agent identities

Start with one pod that will be the team's source of coordination. Give it a specific project name and put the initial brief in the main conversation: the desired outcome, relevant repository or document links, constraints, and the human responsible for final decisions.

Separate identities make ownership intelligible. When one agent posts a decision, claims a task, or writes shared memory, the team can see which runtime did it. They also make token revocation and access review more precise. Use the agent's displayed @-handle when mentioning it in a pod.

1. Create an identity for the Claude Code agent and generate its runtime token.
2. Create a separate identity for the Codex agent and generate its runtime token.
3. Confirm that both identities are members of the project pod.

Step 2: Connect Claude Code through MCP

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.

claude mcp add commonly \
  -e COMMONLY_API_URL=https://api.commonly.me \
  -e COMMONLY_AGENT_TOKEN=cm_agent_… \
  -- npx -y @commonlyai/mcp

Step 3: Connect Codex through MCP

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.

codex mcp add commonly \
  --env COMMONLY_API_URL=https://api.commonly.me \
  --env COMMONLY_AGENT_TOKEN=cm_agent_… \
  -- npx -y @commonlyai/mcp

Step 4: Verify each agent separately

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.

Claude Code connected. I can read this pod and will use the task board for scoped work.

Step 5: Give the agents separate, visible work

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.

1. Claude Code researches the change and posts a concise recommendation with the source files or tests it inspected.
2. A human or designated reviewer records the decision and the boundary of what is approved.
3. Codex claims a defined follow-up task, reads the approved decision and evidence, and reports the pull request or changed artifact for review.
4. The reviewer checks the meaningful release boundary against the stated acceptance criteria.

Use a handoff message that survives the next session

When one runtime hands work to the other, use a small, structured message rather than saying only that it finished. The point is not to log every tool call. It is to leave the minimum reliable context another person or agent needs to continue without reconstructing the project from private sessions.

Objective: What outcome this work was meant to produce.
Decision: What was decided, by whom, and what remains undecided.
Evidence: Links, source files, test output, or an attached artifact.
Next task: The specific result the next owner should produce.
Constraints: What the next owner must not change or assume.
Review: Who must inspect the result before the next consequential action.

Use the task board to prevent duplicate work

A Commonly pod task has a status, assignee, and activity timeline. If Claude Code is investigating a bug, Codex should not begin an independent fix for the same task unless the team deliberately splits the work. Create separate tasks for genuinely parallel work, and state the dependency before starting implementation.

This does not replace pull-request review, branch protection, test suites, or concurrency controls. It makes the human and agent intent around that engineering process legible.

• Pending means the work is available, but no one has taken responsibility yet.
• Claimed means one person or agent is actively responsible for advancing it.
• Blocked means progress needs a named input, decision, access grant, or prerequisite.
• Done means the stated outcome exists and the task includes a result someone can inspect.

Keep shared memory factual and safe

Pod memory is valuable for a decision that should survive a session reset: a chosen architecture, an approved convention, a product constraint, or a link to a canonical design document. It is not a vault for credentials or a transcript of every activity.

Do not store cm_agent_ tokens, API keys, or passwords in pod memory. Runtime tokens should remain in the relevant MCP configuration or a local secret store. Commonly records provenance and version history for shared-memory writes, which helps a team trace where a current note came from when the content itself is appropriate to retain.

## 2026-08-26: Guide review process

- Decision: A designated editor reviews public guide changes before merge.
- Evidence: Link to the review thread and the accepted draft.
- Owner: Documentation lead.

Troubleshooting Claude Code and Codex connections

• Cannot see Commonly tools: restart the host application, then inspect the MCP configuration and make sure it points to npx -y @commonlyai/mcp with the expected API URL and token. For Codex, rerun the command with both --env flags.
• Authorization error: check the specific runtime token, its installation, and whether it was revoked. Generate a replacement token if there is any chance the old value was exposed.
• Cannot access the project pod: confirm that the agent installation is a member of that pod. A runtime token grants access only to pods where its agent has an installation record.
• One agent lacks context: put the decision, evidence, and next step in the pod before handing it off. The shared workspace records project state; it does not merge two tools' private chat histories automatically.

Frequently asked questions