guide · 03 · production

Claude Code as a background agent on Linear

This is the form of “background Claude” that actually changes how a team ships. Assign an issue, walk away, come back to a pull request. One engineer we know moved three weeks of tickets in two days running this loop.

The loop, in one diagram

[ you assign a Linear issue to @cyrus ]
             │
             ▼
   webhook → agent receives issue payload
             │
             ▼
    git worktree add ../ws-ENG-1234 feature/ENG-1234
             │
             ▼
    claude -p "<issue body + repo context>" \
      --allowedTools ... --max-turns 80 --max-budget-usd 5 \
      --output-format stream-json
             │
             ▼
  stream events → Linear comment (live progress)
             │
             ▼
    git push → open PR → move issue to "In Review"
             │
             ▼
         [ you review ]

Why each step is in the loop

Webhook, not cron

Cron wakes up every N minutes whether you need it or not. Webhooks wake up exactly when you assign an issue, and never otherwise. That's the difference between “running Claude in the background” and “running Claude on demand from Linear.” You want the second.

Git worktree isolation

The single biggest reason DIY cron setups fail: two runs ending up on the same branch. git worktree add gives each run its own filesystem checkout, its own branch, its own package install. Clean up after by removing the worktree. No locks, no races.

Streaming output back to Linear

A background agent is only useful if you can watch it work without SSHing into the box. Claude Code's --output-format stream-json emits events as they happen; pipe those to a Linear comment that you update in place, and your issue tracker becomes the runtime dashboard.

Two-way sync

When the PR lands, the issue should move. When someone comments on the Linear issue with follow-up instructions, the agent should see them and either resume the run or queue a new one. This is the part that takes actual engineering to get right. OAuth tokens, webhook verification, replay protection, state machines.

What you'd build if you built it yourself

Linear OAuth flow + webhook signature verification (replay-safe)
GitHub App installation flow so the agent can open PRs as itself
Worktree lifecycle: create, install deps, run, clean up on success/failure/timeout
A streaming consumer for Claude Code stream-json that rewrites a single Linear comment in place
Budget enforcement across runs (not just per-run), per-team
An approval gate for destructive tool calls mid-run
An audit log that's acceptable to your security team
Slack fallback for when Linear isn't the source of truth

That's a two-month project for a good engineer, and the fun parts are over by week one. Everything after that is webhooks and retries.

Or: use Cyrus

Cyrus is the loop above, already shipped. It's BYOK — bring your own Claude / OpenAI / model keys. And it comes in three flavors: a Community self-hosted plan that is free forever (you run the agent runtime and bring your own Linear OAuth, GitHub App, and Slack App), a paid self-hosted plan(Cyrus's cloud handles the integrations layer, you run the agent runtime on your own machine), or a fully managed cloud plan. The question isn't “do I trust a vendor with my code” — it's “do I want to maintain the webhook handlers myself.”

Linear-native. Assign an issue, get a PR. The agent posts live progress back to the issue as it works.
Worktree isolation by default. Zero branch collisions even with many parallel runs.
Approvals, rich interactions, dropdown selects — the agent can ask you questions mid-run and wait.
Channels — Linear, GitHub, GitLab, and Slack. Same agent, different inboxes.
Multi-model. Claude, Codex, Cursor, Gemini under the same scaffolding.