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

Codex, Claude Code, and Cursor can already edit repositories, run commands, and follow project instructions. The missing piece for most teams is not another agent framework. It is an operating contract that turns three capable tools into specialized teammates.

This article shows how to do that with files and CLIs you already have:

• Shared project instructions in AGENTS.md
• Claude bridge via CLAUDE.md importing @AGENTS.md
• Cursor baseline instructions plus optional .cursor/rules
• Typed handoff markdown between roles
• Non-interactive CLI runs for design, review, and implementation

No custom project management platform is required here. If you later want a shared backlog across agents, pair this with Linear multi-agent project management. Here the coordination medium is git plus markdown.

Product surfaces verified 2026-07-29 against AGENTS.md, OpenAI Codex AGENTS.md guidance, Codex non-interactive mode, Claude Code memory docs, Claude Code CLI reference, and Cursor CLI docs.

The team shape

A reliable starter specialization:

These roles are conventions, not vendor limitations. Each tool can design, review, or implement. Specialization helps because it forces an artifact boundary: one agent writes a plan, another attacks it, a third implements only what survived review.

Shared instructions: one source of truth

Use AGENTS.md as the portable baseline

AGENTS.md is the cross-tool instruction format stewarded under the Agentic AI Foundation. Codex reads it natively. Cursor supports a root AGENTS.md as shared project guidance (alongside .cursor/rules). Keep it short and operational:

# AGENTS.md

## Commands
- Install: `pnpm install`
- Test: `pnpm test`
- Typecheck: `pnpm typecheck`
- Lint: `pnpm lint`

## Patch rules
- One behavior change per branch
- Prefer existing helpers over new dependencies
- Do not edit secrets or `.env*` files
- Do not merge to main

## Multi-agent protocol
- Read `docs/handoffs/` before starting
- Write status back into the active handoff file
- Designer, reviewer, and implementer must be different runs
- Stop for auth, payments, production infra, or data deletion

OpenAI’s Codex docs describe discovery from the project root down to the working directory, with closer files taking precedence, optional AGENTS.override.md, and a default combined size budget (32 KiB unless raised). Keep the root file tight; put package-specific rules in nested AGENTS.md files.

Bridge Claude Code with CLAUDE.md

Claude Code reads CLAUDE.md, not AGENTS.md. Official guidance is to import the shared file:

@AGENTS.md

## Claude Code
- Prefer plan mode before edits on `src/billing/` and auth code
- For review jobs, do not implement unless the handoff status is `implement` or `fixes`

A symlink (ln -s AGENTS.md CLAUDE.md) also works when you need no Claude-specific extras. On Windows, prefer the @AGENTS.md import.

Confirm load with Claude’s /context and check Memory files.

Keep Cursor-specific rules narrow

Cursor can use root AGENTS.md for shared conventions. Use .cursor/rules/*.mdc only for Cursor-only needs such as glob-scoped rules. Do not maintain three divergent encyclopedias.

The handoff file is the teammate conversation

Create a directory:

mkdir -p docs/handoffs

Use one file per unit of work:

docs/handoffs/2026-07-29-pricing-section.md

# Handoff: pricing section

- ID: pricing-section
- Status: design
- Owner now: codex
- Next owner: claude
- Branch: codex/design-pricing-section
- Worktree: ../app-pricing-section

## Goal
Implement the marketing pricing section using existing Section/PlanCard patterns.

## Non-goals
Billing, coupons, seat math.

## Design
(Codex fills this)

## Review
(Claude fills this)

## Implementation notes
(Cursor fills this)

## Verification
- Command: `pnpm test:e2e --grep "pricing"`
- Last result:

## Decision log
- 2026-07-29 Codex: drafted component boundaries

Status values that work well (with loops, not a one-way slide):

1. design
2. design-review — blocking findings return to design; clean review advances to implement
3. implement
4. impl-review — blocking findings go to fixes; clean review sets done
5. fixes — implementer resolves findings, then returns to impl-review
6. done
7. blocked-human

Not every task visits fixes. Clean impl-review can go straight to done.

Every CLI run starts by reading the file and ends by updating status, owner, and decision log. That is the entire orchestration layer.

Example: after one design → review cycle

Illustrative handoff excerpt after Codex designed and Claude reviewed:

- Status: implement
- Owner now: cursor
- Next owner: claude

## Design
Files: `PricingSection.tsx` (new), reuse `PlanCard.tsx`
CTA must call `trackCta()` from `src/lib/analytics.ts`
Mobile: stacked below `md`, three columns from `md` up
Plan IDs: `starter`, `pro`, `business`
Test: `pnpm test:e2e --grep "pricing"`

## Review
Blocking: none remaining (breakpoint + plan IDs resolved in Design above)
Non-blocking:
- Extract plan constants later if CMS arrives.

## Decision log
- 2026-07-29 Codex: initial component boundaries
- 2026-07-29 Claude: requested breakpoint + explicit plan IDs
- 2026-07-29 Codex: updated Design; Claude cleared blocking items → implement

That artifact is what Cursor should obey. Chat history is optional. The file is mandatory.

Install and invoke each CLI

Exact install paths change; use each vendor’s current install docs. What matters is the non-interactive invocation pattern.

Codex: design pass

Codex non-interactive mode is codex exec. By default it runs in a read-only sandbox. A design job that updates the handoff file needs workspace write permission:

cd ../app-pricing-section
codex exec --sandbox workspace-write "$(cat <<'EOF'
Read AGENTS.md and docs/handoffs/2026-07-29-pricing-section.md.
Status is design. Produce the Design section only:
- proposed files
- component/API boundaries
- test plan
- risks
- open questions
Do not implement application code.
Set status to design-review and next owner to claude.
Append a Decision log entry.
EOF
)"

Use interactive codex only when you want to steer the design live. For scripts and sequenced runs, prefer codex exec.

Claude Code: review pass

Claude Code print mode can review and update the handoff file, but only if your permission settings allow writes in that worktree. Keep the scope narrow:

cd ../app-pricing-section
claude -p --permission-mode acceptEdits --max-turns 30 --max-budget-usd 5 --output-format text "$(cat <<'EOF'
Read AGENTS.md / CLAUDE.md and docs/handoffs/2026-07-29-pricing-section.md.
You are the reviewer. Do not implement application code.
Challenge the Design section for missing edge cases, local-architecture mismatches, weak tests, and security issues.
Write findings into the Review section as Blocking vs Non-blocking.
If blocking findings exist, set status to design and next owner to codex.
Otherwise set status to implement and next owner to cursor.
Append a Decision log entry.
EOF
)"

If your Claude permission mode cannot write files non-interactively, run the review read-only and have a human or script paste the Review section into the handoff file. Prefer --permission-mode acceptEdits (or a settings allowlist) for handoff-file updates in a disposable worktree. Do not reach for --dangerously-skip-permissions on a real checkout.

Useful Claude Code controls for scripted runs (see CLI reference):

• -p / --print for non-interactive completion
• --max-turns to bound loops
• --max-budget-usd to bound spend
• --output-format json|text|stream-json for automation
• --permission-mode acceptEdits when the review must write the handoff file in a scoped worktree

Do not casually use --dangerously-skip-permissions on production checkouts.

Cursor: implementation pass

Cursor CLI (agent). Prefer the same dedicated worktree as the handoff file records — do not implement from the main checkout:

cd ../app-pricing-section
agent -p --trust --sandbox enabled --output-format text "$(cat <<'EOF'
Read AGENTS.md and docs/handoffs/2026-07-29-pricing-section.md.
Status must be implement or fixes.
Implement only the approved Design, respecting Review blocking resolutions.
Keep the patch small. Add or update tests from the Verification section.
Run the verification command and record the result in the handoff file.
Set status to impl-review and next owner to claude.
Do not merge.
EOF
)"

Important Cursor CLI flags:

• -p / --print — non-interactive; already has access to write and shell tools
• --force / --yolo — auto-approve shell commands unless denied; use only in disposable sandboxes, not as the default for writing code
• --sandbox enabled|disabled — sandbox mode for the run; prefer enabled when implementing with --trust
• --trust — trust workspace in automation
• -w / --worktree [name] — isolated checkout under ~/.cursor/worktrees/<repo>/ (different path from a manual git worktree add; if you use it, update the handoff Branch/Worktree fields to match)
• --mode plan or --mode ask — planning or read-only
• --output-format text|json|stream-json

For review-only Cursor runs, prefer ask/plan modes or an explicit “do not edit” instruction. Prefer manual git worktree add so the path in the handoff matches the implementer checkout.

See also Cursor’s headless CLI guidance for scripted workflows.

Instruction-file map (avoid duplicate truth)

If a rule matters to every agent, it belongs in AGENTS.md. If it only matters to one vendor feature, keep it local. Duplicating the same policy in three files guarantees drift.

Full pipeline example

Assume a clean repo and an empty feature.

1. Create an isolated worktree

git fetch origin main
git worktree add -b feat/pricing-section ../app-pricing-section origin/main
cd ../app-pricing-section
mkdir -p docs/handoffs

Seed the handoff file with Goal, Non-goals, and Verification. Commit the scaffold if your team wants the contract visible in PRs.

2. Codex designs

Codex writes the Design section: files, interfaces, tests, risks. Status becomes design-review.

Real design output should look like this shape:

## Design
Files:
- `src/components/marketing/PricingSection.tsx` (new)
- `src/components/marketing/PlanCard.tsx` (reuse)
- `tests/e2e/marketing-pricing.spec.ts` (new)

Boundaries:
- PricingSection owns layout and plan list
- PlanCard remains presentational
- CTA links use existing `trackCta()` helper

Test plan:
- three plans visible
- CTA hrefs resolve
- analytics helper called once per click

Risks:
- hardcoding plan IDs out of sync with CMS

3. Claude reviews the design

The review prompt requires Blocking/Non-blocking findings, so vague designs come back blocked. Example:

Blocking:
1. No mobile layout decision for stacked plan cards.
2. Design does not state the verification command (add it under Design and Verification).
Non-blocking:
- Consider extracting plan data constant.

Status returns to design or advances to implement only after blocking items are resolved into Design.

4. Cursor implements

Cursor implements only the approved design. It runs:

pnpm test:e2e --grep "pricing"

It records the result, opens or prepares a PR, and sets impl-review.

5. Claude reviews the implementation

Second Claude run reviews the diff against the handoff, not against a freshly invented ideal. Blocking findings send status to fixes with owner cursor. Clean review sets done for human merge.

6. Human merges

Protected branches stay human-owned. Agents can be fast juniors. They should not be release managers.

Shell orchestration without a platform

A simple sequencer is enough:

#!/usr/bin/env bash
set -euo pipefail
ROOT="${1:?worktree path}"
HANDOFF="${2:?handoff file}"
cd "$ROOT"

status() {
  # Prefer the metadata Status field near the top of the handoff file.
  awk '/^- Status:/{print $3; exit}' "$HANDOFF"
}

case "$(status)" in
  design)
    codex exec --sandbox workspace-write "Read AGENTS.md and $HANDOFF. Fill Design only, then set status=design-review and next owner=claude. Do not implement application code."
    ;;
  design-review|impl-review)
    claude -p --permission-mode acceptEdits --max-turns 30 --max-budget-usd 5 --output-format text "Review $HANDOFF per AGENTS.md. Update Review + status only. Do not implement application code."
    ;;
  implement|fixes)
    agent -p --trust --sandbox enabled --output-format text "Status must be implement or fixes. Implement or fix per $HANDOFF and AGENTS.md. Update handoff. Do not merge."
    ;;
  done|blocked-human)
    echo "No agent action for $(status)"
    ;;
  *)
    echo "Unknown status in $HANDOFF" >&2
    exit 1
    ;;
esac

This is deliberately boring. Boring orchestration is debuggable. Keep sandboxes and permission modes as tight as the stage allows: design and review should not need broad system access.

Failure modes

Non-interactive flags that auto-approve edits or permissions are convenience tools for sandboxes and tightly scoped worktrees. They are not a production access-control model.

What not to automate yet

• Merging to protected branches
• Production deploys
• Secret rotation
• Schema migrations without a human-reviewed plan
• Any workflow where the handoff file itself comes from an untrusted external submitter without sanitization

Practical starting kit

1. Add root AGENTS.md with commands, patch rules, and multi-agent protocol.
2. Add CLAUDE.md containing @AGENTS.md.
3. Add docs/handoffs/_template.md.
4. Pick one small feature.
5. Run design → review → implement → review once by hand.
6. Only then wrap the statuses in a shell sequencer.

If you need the same agents to pull tasks from a shared company backlog, add Linear MCP and the claim/review status model from Linear multi-agent project management. The markdown handoff still remains useful as the per-issue technical notebook.

The standard is the contract

Codex, Claude Code, and Cursor already overlap in capability. They become a team when you stop asking them to “work together” in the abstract and instead force a visible contract:

• shared instructions
• explicit role per run
• handoff markdown with status
• isolated worktrees
• bounded CLI invocations
• human ownership of merge and release

That is enough to run a serious local agent team with today’s tools—and enough to notice quickly when the team is improvising instead of engineering.