Linear issue to pull request
This guide takes you from nothing to this loop:
- You add the label
jimothyto a Linear issue. - Jimothy picks it up, moves it to In Progress and comments on it.
- Claude Code (Opus) writes a plan, Claude Code (Sonnet) implements it on a fresh branch in its own git worktree, your tests run, and Codex reviews the diff. Failed tests or a changes requested review send the work back to the implementer, up to twice each.
- You get a notification, look at the change, and click Approve.
- Jimothy pushes the branch and opens a pull request with
gh, then comments the run summary and PR link on the Linear issue and moves it to In Review.
Budget about 20 minutes for setup.
What you need
Section titled “What you need”- Jimothy installed (Installation).
- A local git clone of the repository the work happens in, with an
originremote on GitHub, and a working test command (e.g.npm test). - Claude Code installed and signed in:
npm i -g @anthropic-ai/claude-code, then runclaudeonce. - OpenAI Codex CLI installed and signed in:
npm i -g @openai/codex, thencodex login. (No Codex? You can switch the review step to Claude Code; see step 4.) - The GitHub CLI (
gh) installed. - A Linear workspace where you can create a personal API key.
1. Check the harnesses
Section titled “1. Check the harnesses”- Open Jimothy, click Settings (the gear at the bottom of the sidebar, or ⌘,) and choose the Harnesses tab.
- Click Re-detect.
- Claude Code and OpenAI Codex CLI should have a green dot; select one to see its version. If one says
"claude" not found on PATH, runwhich claudein a terminal and add that directory to Settings → General → Extra PATH entries, save, and re-detect. See Auto-detection.
2. Prepare git and the GitHub CLI
Section titled “2. Prepare git and the GitHub CLI”The final step of the pipeline runs this in the run’s worktree:
git push -u origin HEAD && gh pr create --base {{run.baseBranch}} --head {{run.branch}} \ --title "$FACTORY_ISSUE_KEY: $FACTORY_ISSUE_TITLE" \ --body "Automated by Jimothy run #$FACTORY_RUN_NUMBER. $FACTORY_ISSUE_URL"Jimothy runs git with GIT_TERMINAL_PROMPT=0, so pushing must work without a password prompt. Set that up once:
gh auth login # choose GitHub.com, HTTPS or SSH, and authenticategh auth setup-git # lets git use gh's credentials for HTTPS remotescd ~/code/web-app && git push --dry-run # should not ask for anythingIf you’d rather use a token, put GH_TOKEN=… in Settings → General → Environment variables (a token that can push to the repo and create pull requests).
3. Sign in to Linear
Section titled “3. Sign in to Linear”- In Linear, open Settings → Account → Security & access → Personal API keys and create a key named
Jimothy. Grant Read and Write (write is needed to comment and change states), and access to the team you’ll use. Copy the key (lin_api_…). - In Jimothy, open Settings → Accounts & integrations and click Sign in under Linear.
- Paste the key into API key. Leave Account name empty to name it after you, or call it
Linear (work). - Click Sign in. The account card shows signed in with your name and workspace.
4. Create the pipeline
Section titled “4. Create the pipeline”- Click New pipeline in the ⌘K palette (or, if you’ve made a project, the + on it in the sidebar).
- Under Or start from a template, click Feature: Plan → Build → Review → PR. The pipeline editor opens.
- Click Pipeline settings at the top of the step list.
- In Workspace, keep Git worktree selected and set Local repository to your clone (type the path or click Browse). Check Base branch (
main) and keep the Branch name templatejimothy/{{issue.key | slug}}: issueENG-123becomes branchjimothy/eng-123. - In Variables, set
testCommandto your project’s test command, e.g.npm test,pnpm test --runorpytest -q. - Select the Cross-model review step. Under Harness & model → Model, pick a model from the list or Default (the template’s
gpt-5-codexmay not exist in your Codex). Without Codex, switch Harness to Claude Code and pickopus. - Press ⌘S (or Save).
What the template does
Section titled “What the template does”| # | Step | Type | Harness · model | Key settings |
|---|---|---|---|---|
| 1 | Plan | Agent | Claude Code · opus |
Writes a Markdown plan and must not modify files. Timeout 20 min. |
| 2 | Implement | Agent | Claude Code · sonnet |
Gets the plan as {{steps.plan.output}} and, on a second pass, the reviewer’s feedback. Must commit, referencing the issue key. Timeout 60 min, 1 retry. |
| 3 | Run tests | Shell | — | {{vars.testCommand | raw}}. On failure, loops back to Implement (max 2). Timeout 20 min. |
| 4 | Cross-model review | Agent | OpenAI Codex CLI | Reviews git diff {{run.baseBranch}}...HEAD and ends with VERDICT: APPROVE or VERDICT: CHANGES_REQUESTED. Passes only if the output matches VERDICT:\s*APPROVE; otherwise loops back to Implement (max 2). Timeout 20 min. |
| 5 | Human approval | Approval | — | Approve to push {{run.branch}} and open a pull request for {{issue.key}}. |
| 6 | Open pull request | Shell | — | Push and gh pr create (above). Timeout 5 min. |
The pipeline’s Max concurrent runs is 2, so at most two Linear issues are worked on at once (each in its own worktree). More wait in the queue.
5. Try it by hand first
Section titled “5. Try it by hand first”Before connecting Linear, run the pipeline once on a small, real task so you can sort out tooling problems without an issue involved.
- In the pipeline editor, click Run (or press ⌘N anywhere).
- Enter a Task title such as
Add a /healthz endpoint that returns 200and optionally an Issue key likeTEST-1. - Click Start run.
If the run fails in Setup & run log, fix the workspace (see Troubleshooting). When it reaches Human approval, you can Reject it to stop, or approve and let it open a PR you then close.
6. Add the Linear trigger
Section titled “6. Add the Linear trigger”-
Open the project’s Triggers tab (or All triggers in the ⌘K palette), click Add trigger and choose Linear.
-
Name:
Linear: ENG. Runs pipeline: Feature: Plan → Build → Review → PR. Linear account: the account from step 3. -
Team key: your team’s key, e.g.
ENG. Labels (any of):jimothy(already filled in). -
States: leave empty to match any open issue, or restrict to where hand-offs happen, e.g.
Todo. -
Poll every (seconds):
60is a reasonable start (minimum 15). -
Under Write back to the issue:
- Run starts: Post a status comment on, Move to
In Progress - Succeeds: Post a status comment on, Move to
In Review - Fails: Post a status comment on, Move to Don’t move (or
Todo)
Move to lists your team’s workflow states in board order.
- Run starts: Post a status comment on, Move to
-
Click Preview matching issues. It should say
Connectedand list the issues that would start runs right now. Every issue listed will start a run as soon as you save, so if you see issues you don’t want worked on, remove their label or tighten the filter first. -
Click Save trigger. The trigger card shows live.
Details: Linear trigger, Write-back.
7. Hand off an issue
Section titled “7. Hand off an issue”In Linear, open an issue on that team, make sure its description says what “done” means, and add the label jimothy.
Within one poll interval (click Check now on the trigger to skip the wait) you’ll see:
- a new run on the Dashboard under In progress;
- the issue moved to In Progress with a comment:
👋 Jimothy started run #7 (Feature: Plan → Build → Review → PR).
The issue is now remembered by the trigger and won’t start another run, even though it still has the label. To run it again, click the trigger’s eraser button and Forget it in Processed issues, or set a processed label on the trigger and remove that label from the issue. See Polling & dedup.
8. Watch the run
Section titled “8. Watch the run”Click the run. You’ll see:
- The graph with each step lighting up as it runs; loops appear as amber arcs.
- Setup & run log:
git fetch origin main,git worktree add -b jimothy/eng-123 …, thenWorkspace ready: …/workspaces/run-7-eng-123 (branch jimothy/eng-123). - Plan: select it and open Logs to follow Claude Code’s tool calls (
Read: src/…,Grep: …), thinking and the final result line with cost. Output shows the plan rendered as Markdown. Prompt shows exactly what was sent. - Implement: edits, test runs and a commit in the logs.
- Run tests: your test command’s output.
- Cross-model review: Codex’s commands and its verdict. If it says
VERDICT: CHANGES_REQUESTED, the step fails its verdict and the log shows↺ Cross-model review requested another pass: looping back to "implement" (1/2). Implement runs again with the review in its prompt (the step list showsloop 1), then tests and review run again.
The header’s Cost and Tokens update as steps finish.
9. Approve
Section titled “9. Approve”When the review passes, the run stops at Human approval:
- a desktop notification Approval needed · run #7 (click it to open the run);
- the Dashboard’s Needs your approval card, and the ✋ badge in the sidebar (on Runs, the project and the pipeline) and the tray.
Before approving, look at the change:
- click Open workspace in editor (
</>) in the run header to open the worktree in VS Code or Cursor, or - in a terminal:
cdto the workspace path shown in the run log and rungit log --oneline main..HEADandgit diff main...HEAD.
Then type an optional comment in the banner and click Approve. (Or Reject to fail the run; the comment is recorded.)
10. The pull request
Section titled “10. The pull request”Open pull request pushes jimothy/eng-123 and runs gh pr create. gh prints the PR URL, which Jimothy detects:
- a PR #57 button appears in the run header;
- the run’s success notification and the Linear comment include it:
✅ Jimothy run #7 succeeded (Feature: Plan → Build → Review → PR) in 21m 40s · $1.84Branch: jimothy/eng-123PR #57: https://github.com/acme/web-app/pull/57
✓ Plan✓ Implement✓ Run tests✓ Cross-model review✓ Human approval✓ Open pull request- the issue moves to In Review.
If Linear’s GitHub integration is enabled, the PR also links itself to the issue because the title starts with the issue key.
Where things end up
Section titled “Where things end up”<data folder> e.g. ~/Library/Application Support/Jimothy/factory on macOS├── runs/run_…/│ ├── run.json run record: steps, outputs, prompts, cost, links│ └── logs/ one JSONL log per step attempt└── workspaces/run-7-eng-123/ the git worktree on branch jimothy/eng-123The worktree stays after the run, so you can inspect it or retry. To remove worktrees of successful runs automatically, enable Settings → General → Delete a run’s workspace after it succeeds (branches are kept).
When something fails
Section titled “When something fails”- A step fails: the run page shows the error in red. Fix the cause (a prompt, the test command, a harness setting), then click Retry from here on that step. The run continues in the same worktree with the updated pipeline. See Runs.
- Tests keep failing after two loops: the run fails with
(feedback loop limit of 2 reached), Linear gets a ❌ comment, and the branch stays for you to finish by hand. gh pr createsays there are no commits: the implementer didn’t commit. Make sure the prompt asks it to commit (the template does), or add a shell step before the PR that commits:git add -A && git commit -m "$FACTORY_ISSUE_KEY: $FACTORY_ISSUE_TITLE" || true.git pushfails with a credentials error: redo step 2.- Write-back errors (e.g.
Linear workflow state "In Reveiw" not found) show on the trigger card and as a notification; the run itself is unaffected.
More in Troubleshooting.
Next steps
Section titled “Next steps”- Instant starts: add a Linear webhook so runs start within seconds. See Linear → webhooks.
- Approve from your phone: Approvals from your phone.
- Tune the pipeline: give the reviewer subagents, add a lint step in parallel with tests, or put a
runIfon the PR step. See Step types and Loops & verdicts. - Run issues in an order you choose: set the trigger’s When it finds an issue to Add to a board, and issues wait on a board until you schedule them.
- Jira or GitHub instead: Jira issue to pull request, GitHub issues.