Orbit

How to run multiple Claude Code agents at once

Chris Rupp

Start with two independent tasks and a clear owner for each. For example, assign an API fix to one worker and documentation to another. Keep tightly coupled changes together until their interface is agreed.

Official documentation checked October 23, 2026. OpenAI’s former Codex documentation URLs currently redirect to its ChatGPT Learn documentation; the links below retain the official developer entry points.

Choose a native option first

NeedNative option
Delegate focused investigationSubagents have their own context and return results to the caller. Configure isolation: worktree when a subagent needs a separate checkout.
Coordinate collaborating sessionsAgent teams provide a shared task list and teammate messaging. They are experimental, disabled by default, and have documented recovery and coordination limitations.
Run independent implementationsParallel worktree sessions start with claude --worktree api-fix and, in another terminal, claude --worktree docs-update. The repository needs an existing commit.
Send follow-up instructionsMessage queueing accepts Enter while Claude works. Messages can arrive after tool calls within the same turn; commands wait until turn end. This is session-level queueing.
Monitor independent background sessionsThe native claude agents view monitors and dispatches parallel background sessions.

For a team, enable CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1, then ask the lead to divide the work. Give each teammate a concrete scope. Anthropic recommends avoiding overlapping file edits in its team guidance.

A manual worktree + tmux recipe

Use this when you want explicit directories and ordinary terminal sessions. The example assumes a Unix-like shell with Git, tmux and authenticated agent CLIs installed. Run it from your repository, replacing main with your base branch.

The two add -b commands create separate branches and checkouts, following the Git worktree manual:

git worktree add -b agent/api-fix ../repo-api main
git worktree add -b agent/docs-update ../repo-docs main

Use tmux’s documented session and window commands to give each CLI its own terminal:

tmux new-session -d -s agents -c "$PWD/../repo-api" 'claude'
tmux new-window -t agents -n docs -c "$PWD/../repo-docs" 'claude'
tmux attach-session -t agents

The claude entry point is documented in Claude Code’s CLI reference. You can use two ordinary terminal windows instead of tmux. Before assigning work, install each checkout’s dependencies using the project’s instructions.

Ask each worker to report its changed files, implementation commit and checks. Review one result at a time. For dependency setup, cleanup and integration, continue with Git worktrees for AI coding agents.

Add Codex to the same project

Create a third worktree using the same Git procedure, then start codex from that directory using the official Codex CLI workflow. Give it a distinct task and ownership boundary.

Codex reads repository guidance through AGENTS.md. The native Codex worktree interface is another option if you prefer managed worktrees. Use our shared-context guide to keep the tools’ instructions aligned.

When a shared queue helps

Manual sessions are sufficient for a few independent tasks. Consider Orbit when you want tasks to wait with explicit dependencies and a durable record rather than managing every terminal yourself. Orbit’s prompt queue documents per-project numbering, waiting dependencies and pre-approval.

For isolation, Orbit’s Sandbox uses a worktree per sandboxed prompt, with Promote, Discard and cumulative-diff review. This is the documented isolated-run path; choose it when you need a separate checkout. Follow Connect a Coding Agent to configure execution and model routing.

Start with two tasks, inspect both diffs, and run acceptance checks on their combined result. Separate directories help protect concurrent edits; integration still needs an owner. The Git merge documentation explains the conflicts that can arise when branches come together.