Integrations
Run Codex on Linear issues with a self-hosted worker
This guide pairs Linear with the Codex CLI. DevIntern is the orchestrator: a self-hosted worker that polls a Linear IssueFilter, runs Codex on each ready issue on your machine, and opens a pull request. Below is one issue traced end to end, the exact config for this pairing, and the Codex settings that matter for unattended runs.
Looking for the general setup? See the Linear integration overview or the Codex harness overview .
Your backlog is in Linear. Your agent is in a terminal.
Codex can implement a well-written issue, but someone still has to start it, wait, and open the pull request. DevIntern runs that loop as a background agent on the issues your filter marks ready, and moves them through your Linear workflow states as it goes.
One Linear issue, start to finish
Here is what happens to ENG-42 once it lands in Todo for the ENG team, using the config further down this page.
- Linear issue
- Worker on your machine
- Codex
- Pull request on your repo host
- Review comment
- New commit
-
1. The worker picks it up
The worker polls on poll_interval, re-runs your IssueFilter only when something changed, and claims ENG-42 once for that change.
[poll:linear] 📌 picking up ENG-42 -
2. Context and a feasibility check
DevIntern fetches the description, labels, comments, and attachments. Files on uploads.linear.app are downloaded with your API key; Figma or Google Docs links are passed to Codex as links. The feasibility check runs through Codex's read-only mode, and a vague issue gets a comment with questions instead of code.
-
3. Codex implements in a worktree
The issue moves to your inProgressStatus and Codex runs headless in a disposable worktree with your Codex login.
-
4. Pull request and Linear update
DevIntern commits, pushes, opens the pull request, moves the issue to prStatus, and posts an implementation comment. The issue is recorded as actioned so it is not implemented twice.
-
5. Feedback and retries
Requested changes on the pull request come back as new Codex commits. If a run cannot finish, the issue returns to todoStatus with an "Implementation Incomplete" comment and waits until someone edits or comments on it.
The full config for Linear and Codex
Install DevIntern and create the worker with the quick start, then use these three files. Read the quick start.
Workspace .env
TASK_TRACKER=linear
LINEAR_API_KEY=lin_api_xxxxxxxxxxxx
AGENT_HARNESS=codex
# Optional: a Codex model ID and reasoning effort
# AGENT_MODEL=your-codex-model-id
AGENT_EFFORT=medium
# Optional: Codex's own sandbox (--sandbox workspace-write)
AGENT_SANDBOX=native Create the key under Personal API keys in Linear's API settings. It starts with lin_api_, is shown only once, and inherits your Linear account permissions.
.devintern-code/settings.json
{
"linear": {
"projects": {
"ENG": {
"inProgressStatus": "In Progress",
"todoStatus": "Backlog",
"prStatus": "In Review"
}
}
}
} The key is the team key from identifiers (ENG in ENG-42). State names are matched case-insensitively.
workspace.toml
[defaults]
tracker = "linear"
task_query = '{"state":{"name":{"eq":"Todo"}},"team":{"key":{"eq":"ENG"}}}'
worker_task_args = "--create-pr"
poll_interval = 60 task_query is a Linear IssueFilter as JSON, the same syntax as devintern --query. Try one issue by hand first: devintern ENG-42 --create-pr (identifiers and full issue URLs both work).
Codex settings for unattended runs
DevIntern finds the codex binary on your PATH and runs it with the login or key that CLI already has.
Model and effort
AGENT_MODEL passes a Codex or OpenAI model ID to every spawn; see the Codex CLI docs for accepted values. AGENT_EFFORT accepts low, medium, or high.
Native sandbox
With AGENT_SANDBOX=native, DevIntern runs Codex with its built-in --sandbox workspace-write. Nothing to install, and Codex understands its own sandbox errors, so it retries sensibly. Run devintern sandbox to check what your next run will use.
Custom binary path in a failover chain
CODEX_CLI_PATH applies only when Codex is the active harness, so a path override cannot leak onto the fallback agent.
AGENT_HARNESS=codex,claude-code
CODEX_CLI_PATH=/opt/codex/bin/codexCommon problems with this pairing
"Missing required Linear environment variables"- LINEAR_API_KEY is not set in the .env the worker reads. Restart the worker after editing .env.
"Invalid Linear IssueFilter JSON"- Wrap the JSON in single quotes and validate it against the IssueFilter schema in the Linear GraphQL explorer.
"Workflow state \"In Progress\" not found for team"- The state name in settings.json does not exist for that team. The error lists the available states; also confirm the key is the team key from the identifier.
"Codex CLI not found"- Install the Codex CLI and make sure codex is on the worker's PATH, or set CODEX_CLI_PATH. devintern doctor checks this.
The issue matches the filter but is not picked up- Check the [poll:linear] lines in the worker log. An issue that already has a PR is skipped until you edit it, move it back to a ready state, or change its labels.
Linear's own coding sessions
Linear offers coding sessions that run Claude Code or Codex in Linear's cloud, on Linear-chosen models, billed through AI credits on Linear plans. It is a convenient hosted option if you want everything inside Linear.
DevIntern is the self-hosted route: Codex runs on your machine with your own login, and the same worker can also serve Jira, GitHub Issues, Azure DevOps, Trello, Asana, or Markdown.
FAQ
- Can I use my existing Codex login?
- Yes. DevIntern runs the Codex CLI the way you have it set up, so it uses whatever login or key that CLI already has.
- Can it estimate Linear issues too?
- Yes. Linear has a native estimate field, so devintern ENG-42 --estimate sets the estimate and posts a comment with the reasoning, risks, and unclear areas.
- Can I filter by text instead of JSON?
- For batch runs, yes: devintern --query "login bug" --create-pr matches issue titles. The first 50 matching issues are processed in order.
Try it from your terminal
Interactive use is free. Run one ticket by hand, then turn on the worker when you want it to pick up tickets unattended.
Related: Linear integration overview , Codex harness overview , Worker docs , Jira and Claude Code , Self-hosted vs hosted coding agents