Codex on Linear: assign an issue, get a tested pull request

To put Codex on your Linear issues, connect Linear and GitHub to SHIP, add an OpenAI API key, and set harness: codex in ship.yml. Then assign the issue to SHIP. SHIP plans the change and Codex builds it in an isolated sandbox. Your CI runs as a gate, and the Reviewer and QA check the change on a preview. The pull request waits for you to merge. In the SWE-in-a-team benchmark, a Codex builder on gpt-5.6-sol resolved all 20 tickets at $3.83 per resolved ticket.

See what a mission adds to a Codex task

Linear can already hand an issue to Codex. When you assign an issue to Codex or mention @Codex, Codex starts a cloud chat against a repository that Linear suggests from the issue. When it finishes, Codex posts a summary and a link to the completed chat, so you can create a pull request (Codex in Linear). That setup needs a paid ChatGPT plan, GitHub connected in Codex, and a Codex environment for the repository.

A SHIP mission takes the same issue further before anything reaches you. Each stage leaves something you can check, in the order the SHIP introduction gives:

A failed gate sends the work back to the Builder with the feedback, and the mission continues. Across the 260 missions in SWE-in-a-team, the loop corrected 40 of the 46 runs it objected to without a person.

Connect Linear and GitHub

You make both connections once, during onboarding at letsship.ai:

1. On the Connect step, click Connect Linear and complete Linear's OAuth flow. The grant makes SHIP an agent in your workspace that people can assign and mention (Connect Linear).
2. Click Connect GitHub and install the SHIP GitHub App on the repositories it may work in (Connect GitHub).
3. On the Project step, choose Linear, select the team, and pick the repository. A project covers one Linear team and one repository.

Check one thing in your CI before the first mission. SHIP learns about CI through check_suite.completed, so your workflows must run on pull_request events. A workflow that runs only on pushes to the default branch gives SHIP no result to gate on.

Add an OpenAI key

On the Connect your AI providers step, add an OpenAI API key. SHIP uses OpenAI for the codex harness, and it checks the key with a live call when you save it (LLM credentials). A typo or a key from the wrong account fails at that point, not on your first mission.

The key never enters the sandbox where Codex runs. SHIP starts the container with a placeholder and puts the real credential on each request outside the container. If SHIP does not replace the placeholder, OpenAI gets the placeholder and rejects the call.

Every role that you do not configure runs on the default claude-code harness. If you put Codex on some roles only, keep an Anthropic credential for the others. The docs call this a mixed agent team. Choose it before the first mission, so that a key you did not add does not stop a mission at the review gate.

Put Codex on each role

With no ship.yml, every role runs claude-code on Opus. To run the whole mission on Codex with one OpenAI credential, add this file at the repository root:

# yaml-language-server: $schema=https://letsship.ai/schema/ship.yml.json
version: 1

deployments: {} # add a preview entry here to test against a live environment

agents:
  planner:
    harness: codex
  builder:
    harness: codex
    model: gpt-5.6-sol
  reviewer:
    harness: codex
  qa:
    harness: codex

The aliases codex and gpt follow the newest model of their family, and a versioned model id such as gpt-5.6-sol stays exactly where you put it (Schema). The effort field maps to the native effort control of the harness. The deployments key is required even when it is empty.

For the Builder, SWE-in-a-team measured three OpenAI models on codex, 20 tickets each, one run per ticket. The Planner, the Reviewer and QA stayed on claude-code with claude-opus-4.8, so the table compares builders only. Cost is API-equivalent at list price, recomputed from the per-run data.

Luna had the lowest cost per resolved ticket and also resolved the fewest. On the tickets they missed, Terra and Luna could not turn CI feedback into a build that passed. They repeated the same failure until SHIP's oscillation limit stopped the mission. A mission that stops at the limit leaves the pull request open for a person to take over or redirect.

To try Codex on one mission without a change to the file, set an override for that mission:

ship mission override set SHIP-412 --role builder --harness codex --model gpt-5.6-sol

The override changes only the role that --role names, and ship.yml stays as it is (Command reference). To keep Claude Code on the builder and have Codex read the diff instead, put Codex on the reviewer.

Give Codex your AGENTS.md

Codex reads AGENTS.md, and SHIP uses the same file (Coding agents). SHIP gives the AGENTS.md at your repository root to the Planner, the Reviewer and QA. The Builder does not get it from SHIP, so point the Builder's prompt at the file:

agents:
  builder:
    harness: codex
    prompt: AGENTS.md

SHIP appends the file after its own charter for the Builder, so your conventions add to the role and never replace it. SHIP reads prompt files from your main branch, so a change applies to missions that start after it merges (Agent prompts). Rules for one role only go in .ship/agents/<role>.md.

Assign the issue to SHIP

Write the issue the way you would for a colleague: what you want, and how you will know it is done. QA verifies against acceptance criteria written as checkboxes, so make that part specific.

Export bookings as CSV for a date range

Accounting needs the bookings between two dates as a spreadsheet.

- [ ] GET /api/export?type=bookings returns CSV and requires a signed-in session
- [ ] Optional from and to parameters keep only bookings whose class starts inside the range, both ends inclusive
- [ ] Columns, in order: Starts, Class, Member, Email, Status

Then assign the issue to SHIP. The mission replies in Linear's agent session and posts its plan, review verdict and QA verdict there. The pull request it opens links back to the issue.

A mention of @SHIP on an issue also starts a mission. Only a mention from Linear's own composer counts. A comment that a program posts through Linear's API does not start a mission, so a script should call the CLI or the API instead.

Control the mission from the issue

Reply on the issue to change course. The agents take the instruction and continue on the mission's open pull request. If you ask for a change to what one stage produced, SHIP runs that stage again and does not restart the mission.

Three mentions control the mission itself. @SHIP pause holds the next dispatch, @SHIP resume releases it, and @SHIP stop ends the mission and leaves the pull request open. The console has the same three controls as buttons.

To read the plan before Codex writes any code, put a checkpoint on the Planner:

agents:
  planner:
    checkpoint: true

The mission then holds after the plan and says so on the issue. The Builder and the Reviewer can hold too, and the Builder checkpoint holds after CI. QA cannot hold, because the pull request at the end is already that gate (Human in the loop).

A stuck mission stops by itself. After two rounds in which a gate fails the same way, the console shows Needs attention and the Linear issue moves to In Review. SHIP posts the reason with the last round's feedback, and a reply sends the agents back (Retry limits).

Read the verdicts, proof and cost

When the mission finishes, the issue has the plan, the review verdict and the QA verdict. The mission's artifacts hold what QA checked, such as the trace of a test session or a screenshot of the change. With no preview configured, QA builds and serves the app itself, or tests a browser extension or an API, whichever qaSurface detects or you set.

SHIP prices each call from the list price of the model that served it, not from what the harness reports. It records the cost per mission and per stage. A single mission stops at $5 by default. A mission also pauses at 2 credits, or 6 agent-hours, until a member of your organization approves more (LLM credentials).

The same numbers are available outside the console:

ship status SHIP-412 --json

For every stage attempt, GET /v1/missions/{issueId}/provenance returns the harness, model, provider, token usage, cost and duration (Missions API).

SHIP marks the pull request ready once review and QA pass and stops there. The merge is yours unless you turn on auto-merge for the project or the mission. The Claude Code version of this guide is Claude Code on Linear.