← All guides

Workflow

Claude Code Background Tasks: How to Run Commands Without Blocking

By Neo Zino - builder of ClockedCode·Updated August 22, 2026·10 min read

How Claude Code backgrounds a slow command, the three ways to trigger it, how long a background task survives, and why /bg isn't the command that does this.

Made with DispatchSEO

Claude Code can run a slow build, test suite, or dev server in the background so you keep working instead of staring at a spinner, and the mechanism has nothing to do with the /bg command several existing writeups point you to for it. Press Ctrl+B while a command is running, ask Claude to background it directly, or just leave it - a command that outruns its timeout gets moved there automatically. Whichever way it starts, the command keeps running off to the side, gets a task ID, and writes its output to a file Claude can read on request.

TL;DR: Backgrounding a command (Ctrl+B, a prompt, or an auto-timeout move) and backgrounding a session (/background, alias /bg) are two different features that share the word "background." /tasks lists and stops what's running in the current session. How long a task survives depends on who owns it: a subagent's foreground command dies with that subagent's final response, everything else runs until exit, a 5GB output cap, a 60-minute subagent ceiling, or a 30-minute idle memory-pressure reap - and about 5 seconds after the result under claude -p.

What a Background Task Actually Is in Claude Code

A background task is a single Bash command Claude Code has moved off the main thread of the conversation. It runs asynchronously: Claude gets the task ID back immediately and can keep answering prompts, running other tools, or starting more background work while that command is still going. The output isn't streamed into the conversation as it happens - it's written to a file, and Claude retrieves it with the Read tool when it (or you) actually needs to see it.

That's the whole feature. It exists for exactly the kind of command that used to make you wait: pnpm build, a pytest run with coverage, docker compose up, terraform apply, a dev server you want left running for the rest of the session.

/bg Backgrounds Your Whole Session, Not a Single Command

Here's where several existing guides for this exact query get it backwards. Search "claude code background tasks" and you'll find at least one walkthrough built entirely around /bg as the command that runs a task in the background. It isn't. Per Claude Code's own commands reference, /bg is listed as nothing more than an alias for /background, and /background's job is to detach the entire current session so it keeps running as a background agent while your terminal frees up. Pass it a prompt - /bg run the test suite and fix any failures - and that instruction executes after the handoff, in the new background session, not as a backgrounded Bash call in the one you're sitting in.

The confusion is understandable: both features use the word "background," both keep something running while you do something else, and /background even carries over any Bash commands you'd already sent to the background with Ctrl+B when it detaches. But they solve different problems. Backgrounding a command frees up the conversation for one slow shell call. Backgrounding a session frees up your terminal for the whole conversation, monitored afterward from claude agents. If you only wanted the first one, /bg is the wrong door.

Three Ways to Move a Command to the Background

The three routes all land in the same place - a running command, a task ID, output going to a file - so pick whichever fits how you're already working. Ctrl+B is fastest when you're watching a command run and decide mid-way that you don't want to wait on it. Prompting Claude works when you already know a step is going to be slow before it starts. The auto-timeout move is the safety net for everything else: Claude Code would rather hand you a running background task than kill a process that just needed a few more minutes.

Commands Claude Code Refuses to Auto-Background

The timeout-triggered move has three exceptions, and Claude Code stops these at the timeout instead of backgrounding them:

• Anything starting with sleep - a deliberate pause, not stalled work.
• Anything with git anywhere in it - git operations that hang usually mean something's actually wrong (an auth prompt, a lock file, a network stall), not that they just need more wall-clock time. If you genuinely need a long-running git operation to survive past a session, a worktree keeps it isolated from whatever else you're doing in the meantime.
• Compound commands Claude Code can't fully parse into simple ones - it won't guess at backgrounding something it can't reason about safely.

Ctrl+B and a direct prompt aren't restricted the same way - those are explicit, so Claude Code trusts you to know a git clone is going to take a while. The restriction is specifically on the automatic move.

How Long a Backgrounded Command Keeps Running

Each of those caps has an env var if the default doesn't fit how you work:

One catch before you rely on a backgrounded command's side effects: if it runs cd, pushd, popd, or chdir, that directory change never carries over once the command moves to the background. Claude Code says so explicitly in the result rather than silently acting on a cd that never actually happened in the main session.

Checking On and Stopping Background Work with /tasks

Run /tasks inside the session to see everything currently backgrounded - shell commands and subagents alike, including ones that have already finished - and to stop one directly from that same list. This is the command several page-one results skip past on their way to explaining /bg, which is a shame, because /tasks is the one you'll actually reach for day to day: it's how you find out whether the build you backgrounded twenty minutes ago is done, still running, or died with an error you haven't seen yet.

If you'd rather watch a command's output scroll in real time instead of checking on it later, shell mode's ! prefix (! pnpm test) runs it directly with live output in the conversation, and still supports Ctrl+B if it turns out to be slower than expected.

Background Tasks in Headless (-p) Runs

Scripted and CI usage (claude -p) has its own exit behavior worth planning around if you're piping Claude Code into a build script. A background shell Claude started - a dev server, a watch build - is terminated about five seconds after Claude's final result and stdin closes; that grace period exists so a task that finishes right after the result can still deliver its output before the process exits. Before v2.1.163, a background process that never exited on its own could hold the whole claude -p invocation open indefinitely.

Background subagents and workflows get treated differently: claude -p waits for them to actually finish, since their result is part of the final output, capped at ten minutes by default (CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS, or 0 for no cap). claude -p also rejects the --bg flag outright, with an error naming the conflict: in headless mode there's no terminal to detach from, so session-level backgrounding doesn't apply.

When Background Tasks Aren't the Right Call

• You need to watch output scroll live. A backgrounded command's output goes to a file for Claude to read later, not to the conversation as it happens. Shell mode's ! prefix gives you real-time output instead, with Ctrl+B available if it turns out to run long.
• The command changes directory and later steps depend on that. cd/pushd/popd inside a backgrounded command doesn't carry over - plan around that instead of finding out mid-session.
• You actually want to free up your terminal, not one command. That's /background (or its alias /bg), not this feature - see the split above.
• The command is git, or starts with sleep. Those never auto-background on timeout; if they need to run long, background them explicitly with Ctrl+B or a prompt instead of waiting on the automatic move.

FAQ

What is a background task in Claude Code?

A Bash command Claude Code runs asynchronously, off to the side, so the session can keep responding to new prompts while a build, test run, or dev server keeps going. It gets a task ID, and its output is written to a file Claude reads on request.

Is /bg the command for running something in the background?

No. /bg is a bare alias for /background, which detaches the whole conversation to run as a background agent - a different feature from backgrounding one command. To background a single command, press Ctrl+B while it's running, ask Claude to run it in the background, or let it time out and get moved automatically.

How do I run a command in the background in Claude Code?

Press Ctrl+B while a Bash command is running (twice in tmux), ask Claude directly to run it in the background, or do nothing - a command that outruns its timeout gets moved to the background automatically instead of killed, unless it's a sleep command, contains git anywhere, or is a compound command Claude Code can't fully parse.

How do I check what's running in the background?

Run /tasks inside the session. It lists everything currently backgrounded, including subagents that have already finished, and lets you stop a task from the same view.

How long do background tasks run before Claude Code stops them?

It depends on who owns the command. One started by a subagent running in the foreground ends the moment that subagent gives its final response. Otherwise it keeps running until you exit (or background the session), until 5GB of output accumulates, until a subagent-owned command hits its 60-minute cap, or until 30 minutes of idle plus OS memory pressure reaps it on macOS and Linux. Under claude -p, a background shell is killed about 5 seconds after Claude's final result.

Can I disable background tasks entirely?

Yes. Set the CLAUDE_CODE_DISABLE_BACKGROUND_TASKS environment variable to 1 and Claude Code stops backgrounding commands altogether - a command that hits its timeout is killed instead of moved.

Run it in the background, not through /bg

The feature works well once it's the right one: background a slow command with Ctrl+B or a prompt, keep working, and pull it up with /tasks when you want to check on it. Save /bg for the times you actually want to hand off the whole conversation and walk away from the terminal. It pairs well with a permissive permissions setup, too, since a command running unattended in the background is exactly when you don't want a permission prompt stalling it. The ClockedCode cheat sheet keeps /tasks, /bg, and the rest of Claude Code's commands on one page if you'd rather not keep re-deriving which is which.