Offer

Cloud Mac Dual AI Agent Architecture: Claude Code + Codex CLI Isolation (worktree, tmux, MCP)

AI engineering dual AI agent architecture · cloud mac
2026-06-03 ~13 min read

Primary topic: cloud mac dual AI agent architecture. This is an isolation setup guide for running Claude Code and Codex CLI on one rented Mac—worktree + tmux + one MCP Server—not a CLI install tutorial.

Includes a copy-paste Cloud Mac dual-agent acceptance checklist with three measurable pass/fail metrics.

Key takeaways

  1. Claude Code and Codex CLI can share one host, but never share one working directory—use git worktree for hard isolation.
  2. Three layers: config (HOME) → worktree (repo) → tmux (session); one MCP Server, paths aligned to worktrees.
  3. Typical split: Claude Code for long sessions and multi-file work; Codex for scripted batches or OpenAI-aligned tasks.
  4. 16GB fits “one long + one short” session; two parallel long sessions → prefer 24GB and watch memory_pressure.
  5. Acceptance: tools/call ≥95%, memory_pressure yellow ≤2h continuous, zero cross-worktree writes.
Cloud Mac dual AI agent architecture: Claude Code and Codex CLI isolation setup
Cover: dual-agent isolation on a rented Mac—not a CLI install guide.

1. Why a cloud mac dual AI agent architecture?

In the first half of 2026, kvmboot tickets about cloud mac moved from “can we SSH?” to “how many agents on one box?” When you implement a cloud mac dual AI agent architecture, the usual backdrop is:

  • One engineer lives in Claude Code (Hooks, long context, Anthropic models); another prefers Codex CLI or OpenAI docs and eval scripts.
  • In one sprint, Claude Code refactors across modules while Codex tweaks config and runs generators on another branch—on a laptop, lid-close kills both; on a cloud mac, the laptop is only a remote control.
  • Cost-wise, rent a mac (24GB Mac mini M4) often beats “laptop 24/7 + duplicate API spend”; machine cost is fixed, tokens scale with usage.

This follows earlier posts: decide whether agents belong in the cloud (Claude Code on cloud Mac), then where the MCP Server lives (MCP deployment guide). Dual agents on one host is the third layer: two CLIs that must not hurt each other.

Official references: Claude Code, OpenAI Codex CLI, git worktree.

New to tmux / worktree / MCP? Remember one line: two agents = two repo copies + two terminal windows + one MCP service. Below we unpack directories, absolute paths, and measurable acceptance.

2. Five failure modes (highest-frequency tickets)

When “dual agents configured but broken,” we bucket issues into five types—hit any two and pause feature work until isolation is rebuilt.

  1. Shared directory, fighting .git/index: Claude Code edits on main while Codex git checkouts the same tree—“where did my changes go?” That is a filesystem race, not model failure.
  2. MCP paths still on the laptop: MCP config points at a local repo; after SSH to the cloud mac both agents fail in different ways—debug time doubles.
  3. tmux session mixing: two agents in one window; you think Codex edits module A while Claude Code’s shell from the last round is still active.
  4. API keys / quotas in one HOME: ~/.claude and Codex creds polluted by a stray export—wrong model, wrong bill.
  5. Two long sessions on 16GB: parallel two-hour agents push memory_pressure yellow; latency spikes look like “MCP is broken.”

The fix is never “smarter model”—it is boundaries: repo, session, and config. Next: roles, then a copy-paste layout.

3. Claude Code vs Codex: role matrix (avoid paying twice)

Dual agents are not two identical stacks. Stable teams usually split like this:

Dimension Claude Code Codex CLI
Strengths Long sessions, multi-file refactors, Hooks, deep MCP Git integration Fast small tasks, scripted batches, OpenAI stack alignment
Poor fit Parallel writes in the same directory as another agent Full codesign / Xcode pipeline alone (still needs macOS toolchain)
Typical slot tmux window cc-main, worktree feature/refactor window codex-hotfix, worktree hotfix/config
Cost mindset Token-metered; set budget alerts on long runs Also token-metered; watch script loops

If both agents do “understand the whole repo + large edits,” you pay double tokens without double throughput—keep one long-session agent, use the other for narrow tasks. Matches AI Coding / Personal AI / Agent stack: many agents, not many runners on the same tree. For ECC/Hooks on the Claude side, see Everything Claude Code (ECC)—amplification for Claude Code, not a Codex replacement.

4. Three-layer isolation topology

Visual anchor for the cloud mac dual AI agent architecture: two agent chains converge on a single MCP Server.

Cloud Mac dual AI agent three-layer isolation diagram Claude Code connects to worktree A and tmux A; Codex CLI to worktree B and tmux B; both share one MCP Server Cloud Mac dual AI agent architecture · three-layer isolation Local SSH client (remote control) Claude Code Codex CLI worktree A worktree B tmux · cc tmux · codex MCP Server (single source) Git tools · cloud Mac absolute paths Config → repo → session → tools
Topology: Claude Code → worktree A → tmux A; Codex CLI → worktree B → tmux B; one MCP Server on the cloud Mac.

5. Isolation setup: directories, worktree, tmux

5.1 Config layer: separate HOME roots

On the cloud mac, give each agent a logical config root (same Unix user is fine if env files differ at launch):

  • Claude Code: e.g. CLAUDE_CONFIG_DIR=/Users/agent/.claude-cc for Hooks and MCP stdio JSON.
  • Codex CLI: credentials and config.toml in their own folder—do not mix with Claude settings.json.

SSH and Keychain boundaries: reuse Mac mini hosting onboarding checklist.

5.2 Repo layer: worktree farm (non-negotiable)

Main repo read-only or fetch only; each agent binds one absolute worktree path:

# On the cloud Mac — example paths
/opt/worktrees/my-app-cc-refactor    # Claude Code only
/opt/worktrees/my-app-codex-hotfix   # Codex CLI only

git worktree add /opt/worktrees/my-app-cc-refactor feature/refactor
git worktree add /opt/worktrees/my-app-codex-hotfix hotfix/config

Full farm layout and short-lease proof: remote Mac worktree short lease. Always cd into the agent’s worktree before start—bake it into tmux scripts.

5.3 Session layer: one tmux window per agent

Minimal layout:

tmux new-session -s agents -n cc -c /opt/worktrees/my-app-cc-refactor
tmux new-window -t agents -n codex -c /opt/worktrees/my-app-codex-hotfix

From your laptop: tmux attach -t agents. Lid-close only drops the local client—sessions on the cloud mac keep running. Third path via launchd: launchd + MCP + Codex/Claude FAQ—still bind a dedicated worktree, not the interactive agent directory.

6. MCP with dual agents: one Server, two Client paths

Dual agents ≠ two random MCP installs. Stable pattern:

  • Run one MCP Git Server (or tool set) on the cloud mac; --repository points at the worktree parent—or one Server per worktree/port; pick one and document it.
  • Both Claude Code and Codex configs must use absolute paths on the SSH host—same rule as MCP Server colocated with repos.
  • Forbidden: Claude on VPS MCP, Codex on local stdio—“two worlds” when debugging.

Acceptance test: in each tmux window ask “last three commits on this branch”; logs must show tools/call with branch names matching each worktree.

7. 16GB vs 24GB: parallelism and memory pressure

Dual agents underestimate unified memory on Apple Silicon (especially with indexing / language services):

  • 16GB: “one long + one short” or one agent + read-only MCP queries; two Xcode or Docker stacks will saturate.
  • 24GB: two interactive long sessions, or one agent + simulator/build scripts; still monitor per memory pressure and swap guide.

Do not lock region and term on day one—APAC / US East and 16GB/24GB for RTT, then stress memory_pressure during a daily lease.

8. Cloud Mac dual-agent acceptance checklist

Turn a 48-hour daily lease into a repeatable standard: timeline for process, table for pass/fail. Save redacted logs on the host for “we actually ran this.”

Metric Pass threshold How to measure (on cloud Mac)
tools/call success rate ≥ 95% Within 48h, each agent path issues ≥20 repo MCP calls; success = correct branch/commit info returned
memory_pressure yellow duration continuous ≤ 2h while sleep 300; do memory_pressure; done while both long sessions run; watch 16GB closely
worktree cross-writes = 0 No cd between A/B trees; audit with git -C /path status — zero “wrong tree” edits

8.1 48-hour timeline (copy-paste)

  1. Hours 0–2 · Setup: SSH; worktrees A/B; tmux scripts with fixed cd; MCP --repository uses cloud-mac absolute paths.
  2. Hours 2–8 · Isolation: Claude Code only in A (refactor); Codex only in B (small commits); cross-cd count must stay 0.
  3. Hours 8–16 · MCP: both windows ask “last three commits”; tally tools/call success rate.
  4. Hours 16–32 · Resilience: laptop lid closed / offline ≥8h; tmux attach confirms processes alive.
  5. Hours 32–48 · Decision: all three metrics; memory-only fail → try 24GB or 2×16GB; full pass → weekly/monthly Mac mini hosting.

Pass: all three metrics + acceptable RTT (region guide). Fail first check: shared directory, MCP path not on cloud mac—then models.

9. FAQ

9.1 Can Claude Code and Codex share one worktree?

Only if strictly serial (one fully exits before the other). Interactive parallel on one tree—never. Data loss tickets are almost always “thought serial, was parallel.”

9.2 Do dual agents need two cloud Macs?

Two long sessions each running Xcode builds: 2×16GB often beats 1×24GB. One long + one short: one 24GB is usually enough.

9.3 Must Codex run on macOS?

Codex CLI is not macOS-only, but codesign, notarization, and Xcode mean same cloud mac as Claude Code beats Linux Codex + Mac Claude for delivery chains.

10. Conclusion

A cloud mac dual AI agent architecture is small multi-tenancy: Claude Code + Codex CLI each get worktree + tmux; one MCP Server. Align the team on the topology diagram; replace “feels fine” with three metrics—then lock monthly RAM and rent a mac term.

Engineering advice

Minimum-cost path to validate this architecture

To run the Cloud Mac dual-agent acceptance checklist, the smallest stack is usually: one 16GB cloud mac + 48-hour daily lease + two worktrees + one MCP Git Server. If all three metrics pass, upgrade to 24GB monthly (two parallel long sessions) or 2×16GB (separate Xcode builds). That beats buying a month upfront or fighting lid-close on a laptop.

Plans and SSH steps: Mac mini hosting checklist · M4 specs and lease terms · Configuration tiers