Advanced8 min readAI for Business

Make Codex, Claude Code, and Cursor work as one CLI team

Coordinate interchangeable drafting, implementation and review roles across Codex, Claude Code and Cursor using shared instructions, isolated workspaces and a checked file handoff.

What you should be able to do

These three agents do not need a shared brain. They need a shared contract: one instruction file, typed handoff markdown, isolated worktrees, and CLI commands that can run design, review, and implementation as separate jobs.

Saved only in this browser.
In this article

A file handoff can make a coding agent’s unfinished work inspectable by the next run. It needs more than a summary: the next worker must know which revision it received, what it may change, which checks ran, and who owns the next action.

This guide describes a local design, review and implementation workflow. Codex, Claude Code and Cursor are example clients, not a ranking of their abilities. Start with two roles if that is enough. The complete three-client workflow has not been executed here; commands below were checked against vendor documentation on 28 September 2026 and still need acceptance testing with your installed versions and permissions.

The team shape

RoleExample clientArtifact
DesignerCodexProposed interfaces, files, constraints and test plan
ReviewerClaude CodeFindings against the exact design or candidate revision
ImplementerCursorScoped patch, actual checks and unresolved limitations
DispatcherOne local coordinatorExclusive current owner and next-stage decision

Roles can move between clients. A separate reviewer should challenge the contract and inspect evidence; a different brand is not proof of independent review. Use a separate context and avoid giving the reviewer the author’s verdict as an expected answer.

Approve the repository, account/provider data path and tool access before any client reads it. Use a synthetic or public project while those decisions are unresolved. Repository instructions are context; sandbox and permission settings enforce access boundaries.

Shared instructions: one source of truth

Keep shared commands and scope in AGENTS.md. Codex’s instruction guidance explains directory discovery and overrides. Inspect the effective instructions from the actual worktree instead of assuming only the root file applies.

Claude Code supports an import in CLAUDE.md:

@AGENTS.md

Check the Claude memory documentation and the loaded context. Cursor supports project rules; keep client-specific rules separate from the shared contract. Merge this guidance into existing files rather than overwriting them.

## Task protocol
- Read the assigned handoff and its current revision before work.
- Execute only the stage assigned by the dispatcher.
- One active writer in this task's worktree.
- Preserve unrelated changes and approved interfaces.
- Record exact checks, results and checks not run.
- Review current candidate bytes before advancing to done.
- Follow existing task, merge and release authority.

Fill command entries from the repository itself. A sample pnpm test is not evidence that a project has that script, or that it verifies the changed behavior.

A shared AGENTS.md contract is paired with separate Codex directory discovery, Claude Code import and Cursor effective-context checks; the handoff records the exact candidate revision and one active writer.
Check each client’s effective context instead of assuming a universal import. The article’s proposed three-client workflow still needs acceptance testing with the installed versions and permissions. Open the full-size diagram.

The handoff file is the teammate conversation

Create docs/handoffs/<task-id>.md in a dedicated worktree. This illustrative contract keeps review evidence separate from the author’s claim of completion:

# Handoff: pricing section
- ID: pricing-section
- Status: design
- Owner run: designer-17
- Next role: design-review
- Branch / absolute worktree:
- Base commit:
- Candidate commit:
- Reviewed commit:
- Design revision or hash:

## Goal and exclusions
Three pricing plans using existing components. No billing or price changes.

## Design
Files, interfaces, CTA behavior, responsive layout, test cases.

## Review
Reviewed revision, blocking findings, non-blocking suggestions, limits.

## Implementation notes
Changed behavior and deviations requiring a decision.

## Verification
Exact command, exit status, relevant result, environment, missing checks.

## Decision log
Timestamp, worker run, transition and reason.

For code review, bind approval to the candidate code commit. Store review evidence outside that immutable candidate, such as a PR review or separate evidence record referencing its SHA. A documentation-only update to the handoff should not be confused with an unreviewed application change; the repository must define the scope of its review gate explicitly.

State transitions are design → design-review → implement → impl-review → done. A blocking design finding returns to design; an implementation finding goes to fixes, then back to impl-review. blocked records an unresolved dependency and the responsible decision maker. A process crash leaves the task unfinished even if the last text says “looks good.”

One illustrative cycle

The designer proposes three cards and a CTA. The reviewer notices that the design does not specify whether clicks use the existing analytics helper. The design is amended to require one analytics event per activation and an existing route for each approved plan.

The implementer produces candidate C1 and records the repository’s actual browser-check result. The reviewer finds that keyboard activation emits two events. The implementer fixes it in C2. Review of C1 does not approve C2; the affected check and required review run again. The final evidence names C2, the observed results and any unavailable browser coverage. These identifiers are illustrative, not real commits or executed results.

Install and invoke each CLI

Install only through your approved vendor path, then record --version, relevant --help, account settings and sandbox policy. A documented command is a starting point, not proof that your pinned release supports it.

Codex non-interactive mode uses codex exec. This design example grants workspace writes so it can edit the handoff:

codex exec --sandbox workspace-write "Read AGENTS.md and docs/handoffs/pricing-section.md. Perform only the assigned design stage. Record files, interfaces, tests and unresolved decisions. Update the handoff; do not implement application code."

Workspace-write is broader than permission to edit one Markdown file. The prompt expresses scope but does not enforce file-level isolation. If the reviewer must be unable to alter code, provide a read-only candidate snapshot and a separate writable output location, using supported environment controls.

Claude Code’s CLI reference documents print mode, turn budgets, output formats and permission modes. A review invocation can return findings without granting automatic edit permission:

claude -p --max-turns 30 --output-format text "Read the assigned handoff and candidate diff. Return blocking and non-blocking findings with the reviewed revision and evidence. Do not edit application code."

The configured permissions still determine what tools can do. Route the returned review through the dispatcher into the evidence record. If you enable acceptEdits for direct handoff updates, understand that it permits more than that single file; do not present it as a handoff-only write sandbox. Turn limits do not replace elapsed-time and cost controls for a scheduled run.

Cursor’s headless guide and parameter reference document non-interactive operation. In an already approved isolated workspace:

agent -p --trust --sandbox enabled --output-format text "Read AGENTS.md and docs/handoffs/pricing-section.md. The dispatcher assigned implement or fixes. Apply only that scope, run the specified checks, record actual results and return for review. Do not merge."

--trust accepts workspace trust; inspect repository instructions and configuration before using it. Sandbox support and effective filesystem/network rules must be verified in your environment. Do not add a broad bypass flag because a denied action made the run inconvenient.

These snippets use a conservative no-merge implementation stage. A later, separately authorized merge stage can follow the repository’s configured review and protection rules. Merge does not itself grant authority for a production deployment.

Shell orchestration without a platform

Start by advancing one stage manually. Before adding a launcher, define what survives interruption:

Launcher responsibilityRequired behavior
Exclusive executionOne dispatcher and one active writer for this worktree; reject a second launch
Input validationKnown task ID, allowed state, expected worktree and matching revision
Stage selectionFixed executable and arguments from trusted configuration; never execute a command copied from handoff text
Process lifetimeBound time, turns and cost as supported; record termination and unfinished work
OutputPreserve exit status and review artifact; do not infer success from persuasive prose
TransitionValidate stage evidence before advancing; write state atomically
RecoveryInspect old process and working tree before clearing a reservation or rerunning

A local atomic directory creation can reject a second launcher on one filesystem, but is not a distributed lease or a fence against a previously launched child. A robust launcher must retain ownership until its child has exited, including on interruption. For that reason, a few lines that read Markdown status and launch a client are not offered here as a complete concurrency controller.

Keep the first implementation small: one process, one task, one stage at a time. Record a run ID and expected state before invocation; afterward inspect the actual diff and result before releasing ownership. If you need multiple machines or automatic recovery, use an explicit durable reservation design such as the one discussed in Linear project coordination.

Failure modes

Rehearse these cases with a synthetic task before unattended use:

  • Two launch attempts target the same task. The second cannot start a writer.
  • A review approves an old revision. The current candidate remains unapproved.
  • A client exits halfway through tests. The handoff records interruption and missing results.
  • A repository document asks for a secret upload. Configured access and egress rules prevent it.
  • A reviewer attempts an application edit. The chosen read-only environment denies it.
  • A task reaches its declared cycle budget. It returns a concise unresolved decision rather than inventing completion.

Routine reversible fixes within authorized scope need not stop merely because they concern auth, billing or a schema. New credentials, expanded permissions, changed data flows, destructive live changes and production release require the authority appropriate to those actions. The handoff should identify the exact unresolved boundary and preserve useful work already completed.

The downloadable contract provides the fields and acceptance rehearsal. It is ready to adapt, not evidence that the clients, permissions or workflow have already passed those checks.

Read next

Continue through the same learning path with the next practical articles.