Run Claude Code in the background.
The field guide to every way Claude Code can work without you watching it — headless mode, scheduled tasks, and full background agents on Linear issues. With the guardrails that make it safe in production.
From -p to full background agent
Claude Code has three distinct “background” surfaces. Most teams start DIY with the first, then graduate to managed infrastructure as the blast radius grows.
Run Claude Code non-interactively with claude -p. Pipe it into scripts, CI jobs, pre-commit hooks. Budget and turn limits keep it bounded.
Cron patterns for recurring Claude Code runs. The /loop command, budget guardrails, and when to graduate beyond cron.
Assign a Linear issue → isolated git worktree → Claude Code session → PR. Cyrus runs this loop with OAuth, webhook verification, and approvals.
DIY scales to about three cron jobs.
Headless mode is lovely for a single engineer's laptop. Scheduled claude -p calls work until one of them melts a repo at 3am. Once you're routing work to Claude Code from Linear, Slack, or GitHub, you need the boring parts solved: isolation, OAuth, webhooks, audit trails, approvals, two-way sync.
That's the Cyrus bet. Same Claude Code under the hood — the scaffolding around it is what gets you to production.
See Cyrus in action →# every 15 minutes, pick up anything new
*/15 * * * * cd ~/repo && \
claude -p "$(linear-cli next-issue)" \
--allowedTools Bash,Edit,Read \
--max-turns 40 \
--max-budget-usd 2 \
--output-format json \
>> ~/logs/claude-`date +\%F`.log- → two runs racing on the same branch
- → no way to approve a risky edit mid-run
- → Linear state never updates
- → secrets in logs
- → the “who ran what” question at standup
What is Background Claude?
What is Background Claude?▾
Background Claude is a field guide to every way Claude Code can work without a human watching it — headless mode (claude -p), scheduled tasks, and full background agents triggered by Linear, GitHub, or Slack. The site documents the patterns, the guardrails, and the cost caps that make it safe in production, and funnels readers to Cyrus for the managed production version of the loop.
What does “running Claude Code in the background” mean?▾
Running Claude Code in the background means running it non-interactively — without the TUI and without a human in the loop for each step. Three surfaces exist: headless mode with claude -p for one-shot scripted calls, scheduled recurring runs via cron or the /loop command, and background agents triggered by issue-tracker events (a Linear issue, a GitHub PR comment) that autonomously open pull requests.
Is Background Claude a tool?▾
No — Background Claude is a documentation site, not a product. The production tool it recommends for managed background agents is Cyrus, which handles the webhook plumbing, git worktree isolation, mid-run approvals, audit trails, and multi-channel routing that a DIY background loop requires.
How do I run Claude Code in the background?▾
Start with claude -p for one-shot headless runs, add --permission-mode dontAsk for CI safety (see permission modes), set --max-turns and --max-budget-usd as circuit breakers (see pricing), and use --output-format stream-json to stream events back to a dashboard or issue tracker. For anything beyond ~3 concurrent tasks, graduate to a managed background-agent stack with git worktree isolation and webhook-driven triggers.
From the blog
Claude Code background commands: Ctrl+B, auto-cleanup, and the 5GB limit
Claude Code can run bash commands in the background — dev servers, build watchers, test runners. A field guide to Ctrl+B, the run_in_background parameter, output retrieval via Read, the Ctrl+X Ctrl+K kill switch, and the 5GB cap nobody mentions.
What is 'Background Claude'? A field guide to the term
Background Claude is the umbrella term for running Claude Code without a human watching it — headless, scheduled, or agent-triggered. The short definition, the three levels, the four properties that set it apart, and where the phrase came from.
Linear CLI + claude -p: the poor-man's background agent in 30 lines of shell
The Linear CLI plus claude -p plus a while loop gives you a real Linear-triggered background agent in 30 lines of bash. A field guide to the loop, and the exact four things it breaks on.
Ready to run Claude in the background?
Cyrus is the Claude Code channels gateway — talk to your Claude Code instance anywhere, anytime, and automate it with guardrails. Setup in minutes.