How to Build a Software Factory with Claude Code and Codex

Published November 13, 2026 · by the AQ team

A software factory built from coding agents is a loop: a task arrives from your tracker, an agent writes a plan a person approves, builders implement it in isolated git worktrees, tests and CI check it, an agent from a different vendor reviews it, and a person merges. The minimum pieces are a task source, a place where each task gets its own branch and worktree, a headless way to run Claude Code and Codex, a test command the agents can run, and a merge gate that checks results before anything lands.

AQ is a platform for running a team software factory, and you build one on it like this: connect GitHub and two agent subscriptions such as Claude Code and Codex, let issues come in through a bot routine or a Linear label, run each task as a crew whose AI coding agents plan, build and test in their own branch, route review to the other vendor, and have your team approve the plan and the merge together.

AQ (aq.dev) is a multiplayer coding harness where Claude Code, Codex and other agent CLIs run on the team's own subscriptions in isolated workspaces, with crews that plan before they build and review that can run on a different vendor than the builder.

This guide builds the loop on AQ, step by step, with the setting to change, the check that proves it works and the failure to watch for at each step. The DIY version further down does the same with claude -p and codex exec in CI, for teams that will not use AQ. For the concept and its history, see the software factory.

Before you start

• A repository with a test command that passes on the default branch. The factory can only verify what your tests cover.
• Two agent subscriptions from different vendors, for example Claude Code and Codex, so review can run on a different model family than the build.
• An AQ account with the repository connected. Sign up at aq.dev, connect GitHub, then connect Claude Code and Codex in Settings, Connections. The Free plan runs agents on your own Mac with the AQ Mac app; the AQ Pro plan adds a cloud machine and sharing with your team.
• One small, real task to push through the loop end to end before you widen it.

Step 1: Intake

Work should enter the factory from the system your team already uses, and each task should become its own work item: a branch, a git worktree and a thread.

Configure. Pick one route to start:

• Linear label. Connect your Linear account in Settings, Connections, Integrations. Labeling an issue ai-task creates a work item and moves the issue to In Progress. The label prepares the workspace, and a person starts the agent in it. To start agents automatically, use a bot routine (next). Details: AQ Docs: Linear.
• A bot routine. Create a bot (+ in the sidebar, then New bot) and give it a routine whose trigger is a Linear label, a GitHub event (a new issue or pull request, a push, a release), a webhook or a schedule. Its instruction says what to do with each event, for example: "For each new issue labeled factory, start a work item on this repository with the issue as the brief, and run it as the Ship crew." A bot starts work items under its Start work items rule. Details: AQ Docs: bots.

Check. Label a test issue, or press Run now on the routine. The work item appears in the sidebar under its project, and for a bot it is listed in the bot's Work panel with the routine that started it.

Failure to watch for. A routine runs as the person who created it, on that person's accounts. If their Linear or GitHub connection is disconnected, the routine moves to Needs setup with a reconnect link and nothing starts. Vague issues are the other common failure: the agent acts on what the issue says, so write acceptance criteria into the issue before it gets the label.

Step 2: Spec and plan

The plan is where a person decides what the builders will do before they start. In AQ that is a crew: a Lead that plans and delegates, and roles (Build, Review, Test, Research) that do the steps.

Configure. In the work item, open the model menu, choose Crews, then the built-in Ship crew (plan, build in slices, independent review, test, pull request). Writing "run this as the Ship crew" in the thread does the same. Keep the crew's plan gate on. The gate holds the roles the Lead delegates to. The Lead's own thread can still edit the worktree, so say in the task that the Lead should plan and delegate and leave the code to the builders. Details: AQ Docs: crews.

Check. The Lead proposes its steps and the thread waits with three choices: Approve, Edit the plan, or Run in one thread instead. Until you approve, the Lead's activity shows no builder rows, because no delegated role that can edit code starts.

Failure to watch for. A plan that restates the issue without naming files, tests or slices is a sign the issue was too vague. Choose Edit the plan and add the missing acceptance criteria before you approve.

Step 3: Build in parallel

Configure. In Settings, Crews, set the role picks: the agent and model each role runs on (a connected subscription, an AQ model, or Auto). A common start is Build on Claude Code and Review on Auto, which prefers a different vendor. The Lead delegates each step either into the shared worktree or into a child work item, nested under the Lead's, with its own worktree. Give separate worktrees to independent slices that touch different files, so builders do not conflict. Steps that touch the same files should run one after another, or in the shared worktree. Which model fits which role is covered in which agent and model for each job.

Check. Each builder appears as a row in the Lead's activity with the agent it runs on. Open a row to watch that builder's thread live, steer it or stop it. Builders in their own worktrees also appear nested under the Lead's work item in the sidebar.

Failure to watch for. Merge conflicts between builders. The Lead merges each builder's branch into its own; a conflict comes back with the files involved so the builder that owns them can fix it. If conflicts repeat, the plan's slices overlap: split the next plan by file or module, or run the overlapping steps one after another.

Step 4: Verify

Configure. Make the project runnable in every fresh worktree: an admin sets the repository's setup command (install dependencies, generate code) in the repository settings, and AQ runs it when it prepares each work item. Put the test command in the task or in AGENTS.md so every agent runs the same one. Keep CI on your pull requests as usual.

Check. Each crew member ends with a report: what it claimed, the files it touched, the commands it ran with their exit codes, and the tests. Look for your test command with exit 0. Once the pull request is open, its card in the thread shows the CI checks. For user-facing changes, open the work item's Preview panel to see the running app.

Failure to watch for. A report that claims tests pass without listing the test command. Treat a missing command as untested. A setup command that fails in fresh worktrees is the other one: the work item's Log tab shows each preparation step and its output.

Step 5: Independent review

Routing review to another vendor (Codex reviewing Claude Code's work, or Claude Code reviewing Codex's) puts a model trained by a different team on the diff, which is less likely to share the builder's blind spots.

Configure. Leave the Review role on Auto, which prefers another vendor and account than the builder's, or set it explicitly to your Codex subscription when builds run on Claude Code. You can also start a review on any diff from the Review button in the Changes panel. Details: AQ Docs: Changes.

Check. Findings come back as comments pinned to the diff lines they are about. When the Lead finishes, the crew summary reports time and cost per role and what the review found.

Failure to watch for. A review that ran on the same vendor as the author. AQ says so in words ("Runs on the same vendor as the author"). It usually means only one vendor's subscription is connected, so go back to Settings, Connections.

Step 6: Merge

Configure. Nothing to configure. Commit, Open PR and Merge sit in the Changes panel, and the pull request card in the thread carries Merge too. Merge squashes on GitHub.

Check. Push one more commit to the branch after the review finishes, then press Merge. AQ refuses, with the reason in words, because the review is older than the head commit. It also refuses while checks are pending or failing, or while the head commit is unknown. Press Re-review, wait for green checks, and merge.

Failure to watch for. Merging from GitHub directly skips these checks. Keep your GitHub branch protection rules as well, so the same bar holds whichever button a person presses.

Step 7: Drive it from outside

The same loop can be started and watched from scripts, CI and other agents. API keys, the REST API, webhooks and the MCP server are available on every plan, Free included.

Configure. Create a key in Settings, Connections, API keys, with only the scopes it needs. From a script, create a work item, then start a thread in it. The example runs it as the Ship crew with the Lead on your own Claude Code subscription: source is required and says who pays (native for your connected subscription, aq for AQ credits), native_harness names the CLI, and crew_id picks the crew. Every POST needs an Idempotency-Key:

curl -fsS -X POST https://aq.dev/v1/workspaces \
  -H "Authorization: Bearer $AQ_API_KEY" \
  -H "Idempotency-Key: factory-issue-123" \
  -H "Content-Type: application/json" \
  -d '{"title":"Fix slug generation","repo_id":"your-repo-id"}'

curl -fsS -X POST "https://aq.dev/v1/workspaces/$WORKSPACE_ID/agent" \
  -H "Authorization: Bearer $AQ_API_KEY" \
  -H "Idempotency-Key: factory-issue-123-run" \
  -H "Content-Type: application/json" \
  -d '{"message":"Do the task in issue #123. Run npm test before you finish.","source":"native","native_harness":"claude","crew_id":"builtin:ship"}'

From Claude Code or Codex, add AQ's MCP server, so the agent you already use can list, create and run work items:

# Claude Code (approve the browser sign-in it opens)
claude mcp add --transport http aq https://aq.dev/mcp

# Codex, headless, with an AQ API key in the environment
codex mcp add aq --url https://aq.dev/mcp --bearer-token-env-var AQ_API_KEY

To react to the loop, register a webhook at /v1/webhooks for events such as workspace.pr_opened, workspace.pr_merged and workspace.agent_idle. Details: AQ Docs: API and AQ Docs: MCP.

Check. GET /v1/me returns your user and the key's scopes, and the MCP server's tool list appears in your client. A work item created through the API shows up in the sidebar like any other.

Failure to watch for. Generating a new idempotency key on each retry. Reuse the same key for the same logical action, or a retry after a timeout creates a duplicate work item. Verify webhook signatures against the raw request body.

Step 8: Cost control

• Subscriptions first. Threads on Claude Code, Codex and other connected subscriptions run on each person's own plan, and AQ adds no markup.
• AQ models priced up front. AQ's built-in agent runs on AQ models at published per-token prices, with $10 of AQ credits included per Pro seat each month. See pricing.
• Bot caps. In Bot settings, a monthly cap covers the AQ credits its routines spend, and an optional ceiling stops a single run. At the cap, the next run is skipped and you are told once.

Check. The crew summary shows cost per role for each task, and each bot run records what it cost. Compare a week of runs against your budget before you add more triggers.

Failure to watch for. A schedule or webhook that fires far more often than you expected. An interval routine runs at most every 5 minutes and a bot runs up to 3 routines at once, but each webhook call or new issue can still start a task. Start with a manual trigger, then a daily schedule, and widen after a week.

The DIY version: claude -p and codex exec

The same loop works without AQ if you assemble it yourself. Claude Code runs non-interactively with -p (Claude Code headless docs), and Codex with codex exec (Codex non-interactive docs). A minimal version:

1. Intake: a GitHub Actions workflow on issues: labeled, or a cron schedule.
2. Plan: claude -p "Write a plan for issue #N as a checklist. Do not edit files." --allowedTools "Read,Grep,Glob", posted as an issue comment; a person replies to approve. You enforce the gate yourself, for example by having the next job run only on an approval comment from a maintainer.
3. Build: one branch and git worktree add per task, then claude -p "Implement the approved plan. Run npm test before you finish." --allowedTools "Read,Edit,Write,Bash(npm test)" --output-format json. Claude Code exits non-zero when the run fails.
4. Verify: your normal CI on the pull request.
5. Review: codex exec --sandbox read-only -o review.md "Review the diff against main ...", or codex review --base main, posted as a pull request comment.
6. Merge: GitHub branch protection with required checks and a required human review.

In GitHub Actions, Anthropic publishes anthropics/claude-code-action@v1 (it takes ANTHROPIC_API_KEY, or a CLAUDE_CODE_OAUTH_TOKEN from claude setup-token; docs) and OpenAI publishes openai/codex-action@v1 (docs). What you build and maintain yourself is everything between the commands: worktree setup and cleanup, the plan gate, routing review to the other vendor, keeping the review bound to the commit it reviewed, and a place where teammates can watch a run and step in.

What we ran outside AQ

We ran the build and review steps of the DIY version on November 13, 2026 with Claude Code 2.1.323 and Codex CLI 0.167.2, in a throwaway repository with one function (slugify) and one test. The task: strip accents, drop punctuation, collapse repeated spaces and dashes, trim dashes, and add a test for each rule.

• Build: claude -p "Do the task in TASK.md. Run npm test before you finish. Do not commit." --allowedTools "Read,Edit,Write,Bash(npm test)" --output-format json finished in about 15 seconds over 6 turns. The JSON result reported "subtype": "success", and npm test afterwards showed 6 passing tests and 0 failing. Its summary also listed edge cases it did not handle ("v2.0" becomes "v20"; letters outside a to z, such as Cyrillic, are dropped), which is the kind of note a reviewer should read.
• Review, first attempt: codex exec --sandbox read-only and codex review --uncommitted both failed to run shell commands on the test machine with bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted, because Codex's sandbox could not start on that machine. Codex reported "Review blocked" and declined to call the change approved. Check that your reviewer fails closed like this before you trust it in CI.
• Review, second attempt: we piped the task and git diff into codex exec --sandbox read-only -o review.md -, so it needed no shell. It answered "No findings".

What we ran on AQ

We ran step 5 on AQ for real, against a draft of this page. From an AQ thread running Claude Code with Opus, we delegated a review to the Review role on Auto, in the shared worktree, with a written spec: check every AQ claim against AQ's public docs and check the API examples against the published API specification (/v1/openapi.json). What AQ recorded for that delegation:

• Routing: the Review role on Auto ran on a different vendor and account than the author. AQ's record of the review says "Independent of Opus (latest): a different vendor and account".
• Time: 6 minutes 8 seconds from start to report.
• Report: 5 findings, each with the line it is about, the evidence and a fix, plus the commands it ran to check them.
• What it caught included three delegation targets where AQ has two (the shared worktree, or a child work item with its own worktree), and a Linear bullet that said a bot starts the agent after the ai-task label, when the label only prepares the work item and a person starts the agent.

We fixed the findings before publishing. We did not run steps 1 to 4 and 6 on AQ for this guide, and the page has no AQ screenshots.

Where AQ fits

AQ is a platform for running a team software factory, and you build one on it like this: connect GitHub and two agent subscriptions such as Claude Code and Codex, let issues come in through a bot routine or a Linear label, run each task as a crew whose AI coding agents plan, build and test in their own branch, route review to the other vendor, and have your team approve the plan and the merge together.

Where to go next

• The software factory: what the pattern is and when it pays off.
• Which agent and model for each job: role picks for Lead, Build, Review and Test.
• Crews, bots, the API and MCP in AQ Docs.