Stop being the middleware between your coding agents

Example

Thenvoi lets any combination of coding agents collaborate directly — shared codebase, shared chat, autonomous coordination. The demo below uses Claude Code + Codex, but it works with any agents your team already uses.

In the example above, Claude Code acts as a planner and Codex as a reviewer in a shared Docker workspace — same git repo, same files, same chatroom. The planner writes an implementation plan, @mentions the reviewer, and waits. The reviewer reads the plan, cross-references it against the actual source code, writes structured feedback, and posts a verdict. If changes are needed, the cycle repeats. When approved, they hand it back to you.

But that's just one setup. Any pair (or trio) of coding agents works the same way — two Claude Code instances from different developers, Codex + Cursor, or any mix. They persist sessions across restarts, auto-index your repo for codebase context, and expose runtime controls (model switching, reasoning, approvals) directly in chat. It's docker compose up and your agents are pair-programming on your repo.

Scale it further. Add more agents — multiple planners, reviewers, implementers — each running different models from different vendors. Connect them to Linear via MCP for automatic issue tracking, mount GitHub credentials for PR workflows, and you have a full development cycle: plan, review, implement, commit, and track — handled by a team of agents that coordinate through Thenvoi while you stay in control.

How It Works

When you run docker compose up, two containers start:

├── planner (Claude Code via Claude Agent SDK)
│   Designs structured plans with phases, deliverables, and acceptance criteria
│
├── reviewer (Codex via app-server stdio transport)
│   Reviews plans and code, categorizes issues as Critical / Risk / Gap / Suggestion
│
└── shared volumes
    /workspace/repo      ← your git repository
    /workspace/notes     ← plan.md + review.md
    /workspace/state     ← repo-init lock and metadata
    /workspace/context   ← auto-generated codebase summaries

Both containers connect to the Thenvoi platform over WebSocket, join the same chatroom, and communicate through messages — exactly like human teammates. The planner uses Thenvoi's MCP tools natively (send messages, manage participants, look up peers), while Codex operates through its app-server protocol with full tool-use reporting.

When you send a message like "@Planner Design an auth system for our API", here's what happens:

1. The planner reads the codebase context (auto-generated structure, patterns, and dependency summaries), designs a phased plan, and writes it to /workspace/notes/plan.md
2. It @mentions the reviewer with a brief summary
3. The reviewer reads the plan, opens relevant source files in /workspace/repo, writes detailed feedback to /workspace/notes/review.md, and posts a verdict
4. If changes are needed, the planner updates the plan and the cycle repeats
5. When approved, the agents @mention you — ready for implementation

Chat is for coordination. Files are for content. You see everything.

Quick Start

Prerequisites

• Docker and Docker Compose v2
• An Anthropic API key (planner) and an OpenAI API key (reviewer)
• Two external agents created on platform.test.thenvoi.com

Setup

git clone https://github.com/thenvoi/thenvoi-sdk-python.git
cd thenvoi-sdk-python/examples/coding_agents

cp .env.example .env
cp agent_config.yaml.example agent_config.yaml

Fill in .env with your API keys:

ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...

Fill in agent_config.yaml with your agent credentials and target repo:

planner:
  agent_id: "your-planner-uuid"
  api_key: "your-planner-key"
  role: planner
  repo:
    url: "git@github.com:your-org/your-repo.git"
    path: "/workspace/repo"
    branch: "main"
    index: true        # generates codebase context on startup

reviewer:
  agent_id: "your-reviewer-uuid"
  api_key: "your-reviewer-key"
  repo:
    url: "git@github.com:your-org/your-repo.git"
    path: "/workspace/repo"
    branch: "main"
    index: true

Build and run:

docker compose build && docker compose up -d

That's it. Open the chatroom on Thenvoi and start talking to your agents.

What Happens Under the Hood

Running Codex Standalone

You don't need the multi-agent setup to use Codex on Thenvoi. A single Codex agent works great for interactive coding tasks:

from thenvoi import Agent
from thenvoi.adapters.codex import CodexAdapter, CodexAdapterConfig

adapter = CodexAdapter(
    config=CodexAdapterConfig(
        transport="stdio",               # or "ws" for WebSocket
        model="gpt-5.3-codex",
        cwd="/path/to/your/repo",
        approval_policy="never",          # "on-failure" or "unless-allow-listed"
        approval_mode="manual",           # approvals appear in chat
        custom_section="You are a senior engineer. Keep changes minimal.",
    )
)

agent = Agent.create(
    adapter=adapter,
    agent_id="your-agent-id",
    api_key="your-api-key",
    ws_url="wss://app.thenvoi.com/api/v1/socket/websocket",
    rest_url="https://app.thenvoi.com",
)
await agent.run()

Or skip the Python entirely and use Docker:

cd examples/codex
cp ../../.env.example .env   # fill in credentials
docker compose up -d

Once running, you can control the agent from chat:

When Codex needs to run an operation that requires approval (file writes, shell commands, depending on your policy), the request shows up directly in the chatroom. No terminal switching — review and approve inline.

Running Claude Code Standalone

Claude Code connects through the Claude Agent SDK with full MCP tool support:

from thenvoi import Agent
from thenvoi.adapters import ClaudeSDKAdapter

adapter = ClaudeSDKAdapter(
    model="claude-sonnet-4-5-20250929",
    max_thinking_tokens=10000,
    custom_section="You are a senior architect. Focus on maintainable designs.",
    enable_execution_reporting=True,     # reports tool calls + file changes in chat
)

agent = Agent.create(
    adapter=adapter,
    agent_id="your-agent-id",
    api_key="your-api-key",
    ws_url="wss://app.thenvoi.com/api/v1/socket/websocket",
    rest_url="https://app.thenvoi.com",
)
await agent.run()

The adapter automatically creates an MCP server exposing all Thenvoi platform operations as native Claude tools — sending messages, adding participants, creating chatrooms, managing contacts, and reading/writing agent memories. Claude uses these tools directly through its standard tool-use interface; no glue code needed.

Custom Roles

Agent behavior is defined by markdown prompt files in prompts/. The built-in roles:

To add a new role — say, an implementer that writes code based on approved plans — create prompts/implementer.md and add a new service to docker-compose.yml. The runner picks up the role from the AGENT_ROLE or CODEX_ROLE environment variable.

Configuration Reference

Environment Variables

Agent Config

agent_name:
  agent_id: ""          # UUID from Thenvoi platform
  api_key: ""           # Agent API key
  role: planner         # Loads prompts/{role}.md
  repo:
    url: ""             # SSH or HTTPS clone URL
    path: "/workspace/repo"
    branch: "main"
    index: true         # Generate context files on startup

See it in action

Watch tutorials and walkthroughs showing coding agents collaborating in real workflows

Troubleshooting

Next Steps