What is Background Claude?

Background Claude is the field guide to every way Claude Code can work without a human watching it. Headless mode. Scheduled recurring runs. Full background agents that pick up a Linear issue and open a PR when they're done. The site documents the patterns, the guardrails, and the cost caps every team learns the hard way — so you don't have to.

The term

“Background Claude” is shorthand for the category of usage where Claude Code runs without a persistent terminal, without a human in the loop for every decision, and (usually) without interactive confirmation. Three surfaces fit under the umbrella:

1. Headless mode — claude -p "<prompt>" for one-shot non-interactive runs. The foundation every other pattern builds on.
2. Scheduled tasks — cron, GitHub Actions schedule, or Claude Code's native /loop command. Recurring runs on a timer.
3. Background agents — event-driven runs triggered by Linear issues, GitHub PR comments, or Slack messages. Open a PR when done. The most production-shaped of the three.

Who this site is for

Engineers who have already used Claude Code interactively and now want it to run while they're asleep, offline, or busy with something else. Specifically:

• You've been wiring shell loops around claude -p and hitting the same failure modes (worktree fights, runaway costs, no audit trail).
• You want Claude Code in CI — on every PR, on a nightly schedule, or triggered by an issue — without rebuilding webhooks and worker queues from scratch.
• You're evaluating whether to self-host the background-agent stack or adopt a managed version, and want an honest read on the DIY vs managed tradeoffs.

What you'll find here

Structured by the three surfaces above:

• Three guides that walk through headless, scheduled, and background-agent patterns end to end.
• A CLI reference covering every Claude Code flag and command, grouped by intent.
• A DIY vs Cyrus comparison with 14 honest rows.
• A blog of deep-dive posts on specific flags, formats, and techniques — stream-json, --bare mode, permission modes, git worktree, pricing, Linear CLI, and more.

Who runs this site

Background Claude is published by the team behind Cyrus, the Claude Code channels gateway. Cyrus runs Claude Code (or Codex, Cursor, Gemini) in isolated git worktrees per issue, supports Linear, GitHub, GitLab, and Slack as triggers, and handles mid-run approvals and audit trails — the production version of the DIY loops this site documents. Community self-hosted is free forever. The site exists because every team trying to run Claude Code in the background learns the same lessons in the same order, and we'd rather those lessons be written down.

A plain-English taxonomy

If you're new to the term, here's the short version:

• Interactive Claude: you in a terminal, pressing enter to approve each tool call.
• Background Claude, level 1 (headless): one claude -p call from a script. You wait for it to finish. Still single-shot.
• Background Claude, level 2 (scheduled): the same call on a cron. Runs while you're asleep. Starts accumulating state you have to manage.
• Background Claude, level 3 (agent): event-triggered, per-task git isolation, results posted back to the triggering system. The thing every team ends up building, eventually.

Start here

• Brand-new to headless runs? Start at /headless.
• Already running claude -p in scripts? Jump to --bare mode and pricing.
• Wiring Claude Code into Linear or GitHub? Start at /linear and Linear CLI + claude -p.
• Just want the flags? Everything's in the CLI reference.