Claude Code Background Tasks: Run Long Commands Without Blocking Your Session

Every Claude Code user has lived this moment: Claude kicks off the test suite, or a production build, or npm run dev — and the session just sits there. The command scrolls, Claude waits for it to finish, and you wait for Claude. A tool built to work autonomously ends up blocked on a webpack progress bar.

Background tasks fix exactly this. They're one of Claude Code's most useful features and one of its least understood, because most of the interesting behavior — lifecycle rules, output limits, what happens when you quit — lives in the fine print. This guide covers how backgrounding actually works, what to background, and the cleanup rules that will surprise you if you don't know they exist.

How backgrounding works

When Claude Code runs a command in the background, it executes asynchronously and immediately returns a background task ID. Claude is free to keep working — reading files, editing code, answering your next prompt — while the command runs. The command's stdout and stderr are written to a file, and Claude can check on it at any point by reading that output.

There are two ways to get a command into the background:

• Ask for it. Say "run the dev server in the background" and Claude uses the Bash tool's background mode on its own.
• Press Ctrl+B while a command is running. This moves an already-running Bash command (or agent) to the background mid-flight. If you're inside tmux, press it twice — Ctrl+B is tmux's prefix key.

That second one is the underrated move. You don't have to predict which commands will be slow. When Claude launches something and you realize it's going to take four minutes, one keystroke unblocks the session and the work continues without you.

What belongs in the background

The pattern: anything long-running whose output you need later, not now.

• Dev servers — the classic. Start Vite or Next in the background once, and Claude can check its logs after every change instead of ever blocking on it.
• Builds and full test suites — kick them off, keep working, have Claude read the results when they land.
• Watchers and log tails — a backgrounded tail -f on an error log gives Claude a live feed it can consult on demand.
• Anything you'd otherwise stare at — long installs, migrations, data jobs.

Subagents run in the background too

Backgrounding isn't just for shell commands. Recent versions of Claude Code run subagents in the background by default, and you can force the behavior per agent by adding background: true to the agent's frontmatter. A background subagent works exactly like a backgrounded command from your point of view: it gets an ID, it runs while the main conversation stays responsive, and its results arrive when it finishes.

One detail worth knowing: background subagents get a reduced set of built-in tools compared to foreground ones — the essentials like Read, Grep, Bash, Edit, Write and web tools survive, but interactive tools (like asking you a question) don't. That's by design: a background agent shouldn't stop the world to talk to you. And if a fleet of background agents goes sideways, Ctrl+X Ctrl+K (pressed twice to confirm) stops all of them at once.

Keeping track: /tasks, not Ctrl+T

Once things run in the background, you need a view of what's alive. That's the /tasks command, which lists running shells and subagents. Don't confuse it with Ctrl+T, which toggles Claude's to-do checklist — a plan of record, not a process monitor. If you juggle several sessions on top of background tasks within each, our guide to running multiple Claude Code sessions covers the bigger-picture version of the same problem.

The lifecycle rules nobody reads

Background tasks are not immortal, and the rules governing when they die are worth two minutes of your attention:

• Exit kills them. Background tasks are cleaned up when Claude Code exits. If you background the whole session instead of quitting, its tasks are handed off and keep running.
• There's a 5GB output cap. A task whose output exceeds 5GB is automatically terminated, with a note in stderr explaining why. A chatty dev server left overnight can genuinely hit this.
• Memory pressure reaps idle tasks. On macOS and Linux, if the OS signals memory pressure and your session has been idle for 30+ minutes, Claude Code terminates running background tasks. Set CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP=1 to opt out.
• Subagent-owned commands have a timer. Background commands started by a subagent are terminated after 60 minutes by default, configurable via CLAUDE_SUBAGENT_BG_SHELL_MAX_MS.
• You can turn it all off. CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 disables background task functionality entirely.

The practical takeaway: background tasks are for the lifetime of a working session, not for daemons. If something must survive your laptop's afternoon, run it under a real process manager and let Claude tail its logs instead.

Hygiene: kill what's dead

Every live background task is something the session keeps track of, and long-running shells you no longer need are pure overhead. When a backgrounded build has served its purpose, tell Claude to kill it — or check /tasks yourself and prune. This is the same discipline as context management: the session works best when it's only carrying what still matters.

Backgrounded is not the same as done

Here's the catch that motivates this whole workflow. Before background tasks, you knew when the test suite finished because you were watching it. Now the suite finishes silently in the background, Claude finishes its other work and waits for you — and nothing anywhere makes a sound. Backgrounding moves work out of sight, which is the point, but out of sight cuts both ways: the run that completed eight minutes ago is worth exactly nothing until you notice it.

The fix is the same one we describe in our post on not watching the terminal: make completion push to you instead of you polling for it.

A 60-second starter workflow

1. Start your dev server in the background at the top of the session: "run the dev server in the background and check its logs after each change."
2. When any command turns out to be slow, hit Ctrl+B and keep going.
3. Use /tasks to see what's running; kill anything that's done its job.
4. Set up a notification for when Claude finishes, so backgrounded work gets acted on the minute it lands — not whenever you remember to look.

Background tasks turn Claude Code from a tool that works while you watch into one that works while you don't. Learn the two keystrokes, respect the lifecycle rules, and close the loop with a notification — that's the whole trick.