Claude Code background commands: Ctrl+B, auto-cleanup, and the 5GB limit

Claude Code has a built-in way to run bash commands in the background — dev servers, build watchers, long-running test suites — while Claude keeps chatting with you. The feature has four moving parts worth understanding: the Ctrl+B shortcut, unique background task IDs, output-to-file retrieval via the Read tool, and a set of auto-cleanup rules that keep things from running forever. This is the field guide to all four.

The short version

• Press Ctrl+B while a bash command is running to move it to the background. Tmux users press it twice.
• Or just ask: “run the dev server in the background.” Claude Code will use its run_in_background parameter on the Bash tool automatically.
• Each background task gets a unique ID. Output is written to a file Claude can Read. Claude keeps working on new prompts while the task runs.
• Press Ctrl+X Ctrl+K (twice within 3 seconds) to kill all background agents.
• Tasks are auto-cleaned up when Claude Code exits. Auto-terminated if output exceeds 5GB.
• Disable the whole feature with CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1.

How backgrounding actually works

When you run a bash command through Claude Code (either as a tool call Claude made, or via the !bash-mode prefix), the command normally blocks Claude until it finishes. Long-running commands — dev servers, build watchers, log tails — don't fit that model. They need to run indefinitely.

Claude Code's background-task system solves this by running the command asynchronously. The process starts, returns a background task ID immediately, and Claude is free to respond to new prompts. Meanwhile, stdout and stderr are redirected to a file that Claude can read at any time with the Read tool.

Two ways to trigger it:

1. Ask Claude directly— “start the dev server in the background” or “run npm test in the background and watch for failures.” Claude Code will automatically pass the run_in_background parameter to its Bash tool.
2. Press Ctrl+B while a regular Bash tool invocation is running. This moves the already-running command to the background. Tmux users have to press it twice because tmux reserves Ctrl+B as its prefix key.

Output retrieval

Because stdout/stderr go to a file, background tasks never flood Claude's context directly. You ask Claude to read the output when you want it:

You: start the dev server in the background
Claude: [runs `npm run dev` with run_in_background=true]
        Background task started: task_abc123

You: is the server up yet?
Claude: [reads the task's output file]
        Yes — listening on http://localhost:3000

You: any errors in the last 30 seconds?
Claude: [re-reads the file]
        Nothing since startup.

This is genuinely different from what claude -p does in headless mode. Headless mode is single-shot: you launch Claude, it finishes, it exits. Background commands are intra-session — they're about keeping a long-running bash process going inside a live Claude Code session.

The auto-cleanup rules

Three rules keep background tasks from becoming a resource leak:

1. Output cap (hard). If a single background task emits more than 5GB of output, Claude Code auto-terminates it and leaves a note in stderr explaining why. This is a backstop for runaway loggers or commands that accidentally pipe something huge. You won't fill a disk without a warning.
2. Session exit. When you Ctrl+D out of Claude Code, or the session otherwise terminates, all of its background tasks get cleaned up. This is the feature you want in 99% of cases — no zombie dev servers surviving your terminal closing.
3. Manual kill. Ctrl+X Ctrl+K (press twice within 3 seconds to confirm) stops every background task in the current session at once. The double-press is deliberate: single-press ambiguity would make it too easy to nuke a build mid-run.

The escape hatch: disable the feature entirely

If your workflow is hostile to background tasks — maybe you're wiring Claude Code into a CI system that expects every command to block and exit, or you just don't trust the 5GB cap — set the environment variable before launching:

export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1
claude

With this set, run_in_background is ignored and Ctrl+B has no effect. Every bash command blocks Claude until it finishes.

What this feature isn't

The term “background Claude” is ambiguous on purpose — it covers several very different things. Background commands are the narrowest and most concrete:

• Background commands (this post) — bash processes running while Claude chats with you in an interactive session.
• Headless mode — claude -p, non-interactive one-shot runs. Different surface entirely.
• Scheduled tasks — cron, GH Actions schedule, or Claude Code's /loop command.
• Background agents — event-triggered Claude Code sessions that run to completion on a webhook (e.g. a Linear issue).

If someone says “background Claude” and means “Ctrl+B,” they're talking about this page. If they mean “run Claude without me watching,” they're talking about headless or scheduled. If they mean “Claude that wakes up on events and ships PRs,” they're talking about background agents. See the What is Background Claude? field guide for the full taxonomy.

Practical patterns

Dev server that persists across many prompts

You: start the next dev server in the background
Claude: [runs `npm run dev` with run_in_background=true]

(you keep working, Claude helps with code, minutes pass)

You: check the server logs, is there an error?
Claude: [reads the background output file, summarizes]

Test runner in watch mode

You: run vitest in watch mode in the background
Claude: [runs `npx vitest` with run_in_background=true]

You: (after editing a file) any new failures?
Claude: [reads the output file, reports the last run]

Long build while you work on something else

You: start the production webpack build in the background
Claude: [runs `npm run build` with run_in_background=true]

You: add input validation to auth.ts
Claude: [does the validation work while the build runs]

You: is the build done?
Claude: [reads the output — if the build exited,
         you'll see the final status; if still running,
         the most recent output]

Background commands vs. bash-mode (!)

Claude Code also has a !bash-mode prefix that runs commands directly, bypassing Claude's tool-use approval:

! npm test
! git status

Bash mode supports the same Ctrl+B backgrounding. If you're running a dev server and want to background it without asking Claude to do the tool call, ! npm run dev then Ctrl+B is two keystrokes faster. The output still goes to a file Claude can read.

Why this matters for CI and scripted use

If you're wiring Claude Code into GitHub Actions or a shell script, you probably want the CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 env var set. CI expects blocking, deterministic commands. Background tasks in a CI context are almost always a bug — a dev server gets started, the job exits before the task finishes, the next step fails with connection refused. Disabling the feature makes your CI runs behave like every other bash script.

For interactive local sessions, leave it on. It's one of the more genuinely useful quality-of-life features in Claude Code.

Takeaways

• Ctrl+B backgrounds a running bash command. Ctrl+X Ctrl+K (twice) kills them all.
• Or ask Claude: “run it in the background” — the run_in_background parameter handles it.
• Output goes to a file, not Claude's context. 5GB cap. Auto-cleaned on session exit.
• CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 disables the feature for CI and scripted use.
• This is one specific kind of “background claude” — see the taxonomy for the other three.