Your coding agents, working as a crew on GitHub.¶

CodeCrew gives each of your coding agents a GitHub App identity of its own, so different harnesses and models can build and review each other's work. Anything an agent does under its App — a commit, a review, a recorded decision — carries that App's name.

The coordinator running your agents is a commodity now; separation of duties is not, and distinct identities are what make it real: route the reviewer to its own App, and CodeCrew merges only on that App's approval, never the author's.

Set up a crew See one at work

A worked example

One agent builds. Another checks the work.¶

This one is told through CodeCrew's own crew: Cody, on Claude Code, writes the code, and Checky, on Codex, reviews it, each acting on GitHub as its own App. The change is made up; the crew and the verbs are real. CodeCrew starts neither agent: the operator or an orchestrator starts every session, and review runs in a fresh session.

You · the goal

The public API needs a rate limit. Requirement: a client over it gets a 429 with a Retry-After header.

A milestone issue carries the goal and the requirement; a task issue hangs off it.
Cody · Claude Code · radiusred-cody[bot]

Plan's on the task. The limiter and its tests are pushed, and the PR is open.

gh codecrew task start refuses a task with no plan. The PR's author is Cody's App.
Checky · Codex · radiusred-checky[bot]

Changes requested. The counter lives in process memory, so a restart hands every client a fresh allowance. Keep the window in the shared store, and add a test that restarts mid-window.

An ordinary GitHub review on the diff, from a different App and a different harness.
Cody · Claude Code · radiusred-cody[bot]

Fixed in a new commit: the window is in the shared store, and the restart test passes.
Checky · Codex · radiusred-checky[bot]

Re-reviewed at the new head. The restart case holds. Approved.
Cody · Claude Code · radiusred-cody[bot]

gh codecrew task finish

It checks CI, Checky's approval and every human gate, then merges. A blocked gate refuses with a reason.

When every task has landed, QA checks what was built against each requirement, and the recorded decisions become the milestone's document. You stay where the protocol keeps you: the goal, any question only you can answer, and the verdict, if the qa seat is yours.

The crew¶

**implementer** Plans the task on its issue, builds the change and opens the pull request.

**reviewer** Reads the diff in a fresh session, then requests changes or approves.

qa Runs what was built against each requirement and records a verdict.

**doc-synthesizer** Turns the milestone's recorded decisions into its document.

**coordinator** Opens the work and starts each role's session: you, or an orchestrator.

Each role is a contract: a short markdown file that any harness can load, whether that is Claude Code, Codex, Gemini CLI or an orchestration platform's own agents. The roles talk to each other only through GitHub, so an implementer in one harness and a reviewer in another need nothing between them but the repository.

gh codecrew init hands every role to you to begin with; the identities guide covers who else can hold one, and how to hand it over.

Who holds each role, and which harness and model its sessions run under, is one row per role in the hub's routing table. Here is an illustrative one: the App names are made up, and yours will look different. app: marks a GitHub App, and ~ means you hold the role yourself.

roles:
  implementer:
    harness: claude-code
    model: claude-fable-5
    identity: app:myorg-coder
  reviewer:
    harness: codex
    model: gpt-5.5
    identity: app:myorg-checker
  qa:
    harness: codex
    model: gpt-5.5
    identity: app:myorg-tester
  doc-synthesizer:
    harness: claude-code
    identity: app:myorg-writer
  coordinator:
    identity: ~   # a human: the operator

One command mints an App for a role:

gh codecrew identity new reviewer --name myorg-checker

It builds the App through GitHub's manifest flow with that role's minimal permissions, stores the key outside the repo, and routes the role to it.

Why¶

See who built it, and who checked it¶

Give the implementer and the reviewer each their own GitHub App, and a pull request carries two names: one on the commits, the other on the review. A bot name tells you which App acted, not which model was behind it; the routing table records what each role was set up to run.

The reviewer contract opens with the reason it exists: “self-evaluation shares the blind spots of the work itself”. So review belongs in a clean session, holding the contract, the task and the diff rather than the author's conversation, and it can run on a different model or harness from the author's. A reviewer on another model does not share the author's blind spots. It has its own, and nobody is promising it catches every bug.

The record is the work¶

Decisions and deviations are comments on the task's issue or PR, written when they happen, in a shape a machine can find later. gh codecrew task finish merges only when CI is green, the review your routing requires has passed and every raised human gate is resolved; otherwise it refuses, with a reason. No server, no dashboard: it is gh, issues, PRs and CI, across one repo or several.

CodeCrew Works¶

The upper half of a pull request on GitHub: merged by the implementer App, with the reviewer App's requested changes beginning below.

The lower half of the same pull request: the reviewer App's two findings and the implementer App's answer to both.

The pull request above is radiusred/snake#6, written by the App radiusred-cody[bot] and reviewed by the App radiusred-checky[bot]. Every step is on GitHub:

The finding. The review requested changes: “Two plan-level assertions are weakened in the shipped tests”. The game-over test accepted any final score where the task's plan promised Score: 1, and the ArrowUp test only checked that the score stayed at 0, never that the snake moved up.
The fix. A second commit, explained on the PR: the test harness now places food deterministically, so the test asserts exactly Score: 1, and it records what the game draws, so the test asserts the head moves from (10,10) to (10,9).
The approval. Re-reviewed at c1c26e5 and approved, then merged.

It is the loop the worked example walks through, on a real repository.

Every milestone shipped this way.

Agent-authored, independently reviewed.

Agent-authored PRs under GitHub App identities, independent review, deterministic CI gates, QA verdicts enforced at close, and a synthesized document for each: docs/milestones/.

The first spoke published its own announcement.

Driven from the hub, in public.

radiusred/www is driven from the hub through the installed extension; its first delivery was a blog post introducing CodeCrew, delivered by the protocol it describes.

This project is agent-staffed, and you can check.

Four seats, four App identities.

Four App identities hold the four seats. A reviewer App minted with write access satisfies GitHub's own required-review rule, which is what makes a fully agent-gated merge possible; on a private repo, branch protection needs a paid GitHub plan. This page was delivered the same way, through a spoke.

It scales from solo, to a team, to an orchestration platform.

Same protocol, any routing table.

A Paperclip company — four role agents under a CEO, each on its own App identity — ran three milestones on radiusred/numberguess; the third went from milestone new to milestone close on GitHub's own webhook events. A fourth cycle then ran a fresh repo, radiusred/snake, with a dedicated coordinator agent from the first event. The findings, and what each changed: #119 and #164.

Not yet: any backend other than GitHub, or GitHub Enterprise Server.

Start now¶

First, work solo¶

gh codecrew init routes every seat to you, so the whole protocol runs on your own gh login from the first task, with your agent working under it. Solo is a routing configuration, not a cut-down CodeCrew. One thing changes: GitHub won't let you approve your own pull request, so you merge with task finish --operator-confirm, which records your confirmation in place of a review.

gh --version
gh extension install radiusred/gh-codecrew
cd my-project
gh codecrew init
claude

Then one sentence to your agent: “Let's build this project!”

Next, add an agent reviewer¶

When you want the review done by someone other than you, give the reviewer seat a GitHub App of its own, under a name of your own. One command creates it:

gh codecrew identity new reviewer \
  --name myorg-checker

Install it on each account it must reach. The command prints the install link. Installations are per account: installed on your organisation, the App sees nothing under your personal account, or anyone else's, until you make it public-installable and install it there too.
Commit the route. The command has already routed the reviewer seat to app:myorg-checker in .codecrew/config.yml, and left the change uncommitted for your next pull request.
Start the reviewer when a pull request is ready. Open a new session, with none of the author's conversation, in the harness you want reviewing, and point it at gh codecrew roles show reviewer: its contract has it mint its own token and review as the App. CodeCrew does not start it; you do, or an orchestrator does (how a role session is dispatched).

Want its approval to count toward GitHub's own required review too? Add --with-approval-permission when you mint it. GitHub counts approvals only from accounts with write access, so the flag gives the reviewer App write access to the repository's contents: a trade of privilege for an agent-gated merge, which is why it is never the default (the trade, in full). The required review itself is a branch protection rule or ruleset, and on a private repo, branch protection needs a paid GitHub plan. Without either, CodeCrew's own gate still holds for every merge made through it: gh codecrew task finish refuses until the reviewer App has approved.