Claude Code background tasks: the time limit, and how to view, watch or kill one

Start with what you are looking at

Three different problems get called "background tasks". Find the one on your screen, because each answer lives in a different section.

• A long command stopped by itself, and Claude said why
• Something is still running and you cannot find it, watch it or end it
• It died and you want to know what killed it, or whether it can come back

If what stopped is a Claude Code session rather than a command, this is the wrong page: that is a different mechanism with a different lifecycle. If the thing you are watching is a long unattended run driven by a script, the headless guide covers what happens to background work when that run exits.

What actually happens when a command goes to the background

Claude Code runs the command asynchronously and immediately returns a background task ID, and it can answer new prompts while the command keeps executing. Nothing is paused and nothing is re-run later: the process is live from the moment it is backgrounded.

There are two ways in. You can ask Claude to run something in the background, or press Ctrl+B to move a Bash call that is already running to the background. Inside tmux the keystroke does not arrive, because Ctrl+B is tmux's own prefix key, so tmux users press it twice.

Output is written to a file rather than held in the conversation, and Claude reads that file with the Read tool when it needs the output. Each task carries a unique ID, used for tracking it and for fetching its output.

Commands that go to the background without anyone pressing a key

When a foreground command reaches its timeout without finishing, Claude Code moves it to the background instead of killing it, and the result says so: the line names the timeout in seconds and adds that the command was moved to the background, followed by the task ID and the path of the file the output is going to. The one exception is a command that starts with sleep, which is stopped at its timeout rather than moved.

One trap comes with that move. A cd, pushd, popd or chdir inside a command that moves to the background never carries over, and the result tells you the session working directory has not changed. So a later command that relied on that directory change will not have it.

The timeout being moved is the ordinary Bash timeout, which is two minutes by default, with a ceiling of ten minutes set by the larger of two environment variables. Both of those are separate from the background time limit below, and conflating them is the usual reason someone sets a number that changes nothing.

The time limit, and how to raise it

This is the part people search for, so it is worth being exact. In a session that runs unattended (a -p run, an Agent SDK application, a CI job, or a Claude Code session running in the cloud), background Bash and PowerShell commands have a time limit. In a local session you work in yourself, from a terminal, Claude's own desktop app or the VS Code extension, they have none. The limit requires Claude Code v2.1.285 or later, and before v2.1.288 it applied in every session, which is why older write-ups describe it biting an ordinary terminal.

The clock starts when the command enters the background, not when it was launched. A command Claude starts in the background gets 30 minutes, or the timeout Claude passes with it, up to a maximum of 2 hours. A command that began in the foreground and then moved to the background gets 30 minutes from the move.

There is one narrower case. In a -p run whose prompt you pass as text rather than through --input-format stream-json, both defaults drop to 10 minutes instead of 30, because that kind of run waits for background commands after its result.

Background command "<description>" was stopped after reaching its background time limit

That line is what you will see when the limit fires, and Claude is told why, so it can start the command again with a longer timeout if the work still needs doing. It is a stop, not a crash, and it is not silent.

Raising either number

Two environment variables raise these limits, for Bash and for PowerShell, and the values are milliseconds. Setting BASH_DEFAULT_TIMEOUT_MS above 1800000 replaces the 30-minute default with that value, both for commands Claude starts without a timeout and for commands that moved to the background; in a text-prompt -p run, any value above 600000 replaces the 10-minute default instead. Setting BASH_MAX_TIMEOUT_MS above 7200000 raises the 2-hour maximum to that value, and setting BASH_DEFAULT_TIMEOUT_MS above 7200000 raises the maximum the same way.

Neither variable can shorten anything. A lower value leaves the defaults and the 2-hour maximum exactly where they are, so if you were trying to make a short job time out sooner, these are not the settings for it.

Where the confusion came from

This is a young part of the product, and the two reports that made people look are worth reading beside it. Issue 98273, still open, reports background Bash tasks being killed at a time limit that was undocumented when it was filed — which it was, and that is why a page quoting only the issue would leave you believing the limit is still a mystery. It is also older than the version note that narrowed the limit to unattended sessions, so read it as a description of the rule as it stood, not as the rule now. Issue 104047, closed as not planned, is the display half: the desktop app's sidebar showing a session as finished while its background tasks were still running. The build we checked here, 2.1.311, is past both of the limit's version notes, so on a current install what you get is the documented behaviour described above.

What the limit is not

The limit on a background command is not the wait at the end of a print-mode run. That one is separate: after its final turn, a -p run can stay open for background work, and unless a background command from the main conversation is still running, Claude Code stops whatever is left after 10 minutes of continuous idle waiting. The headless guide covers that ceiling and the variable that moves it.

Seeing one, watching it, and ending it

Run /tasks. It shows and manages the current session's background work, including subagents that have already finished, and the same view answers to /bashes. Stopping a task there is the supported way to end one by hand; underneath, the stop takes the task's ID.

Stopping has a consequence worth knowing before you do it. After you stop a task from /tasks, or from a connected client such as the desktop app, Claude moves on instead of waiting for it — and if a subagent started that command, it is that subagent which moves on. Meanwhile a command the main conversation started keeps running after a final response until it exits, is stopped, or reaches the time limit, which is why a dev server started an hour ago is still there.

Reading the output of a task you are not stopping is easier than it used to be. The old way, a separate tool for retrieving a background task's output, was removed in v2.1.277; the documented route now is that Claude reads the task's output file with the Read tool.

The keys that look like this feature and are not

Two keystrokes get confused with Ctrl+B. Ctrl+T toggles Claude's to-do checklist, and Anthropic says outright that this is not the background-task view. Ctrl+X Ctrl+K stops every running background subagent in the session, and you press it twice within three seconds to confirm.

Watching rather than polling

If what you want is to be told when something changes, that is the Monitor tool rather than a background command: Claude watches a log, a CI job or a directory and interjects when an event arrives, while you keep using the same session. Every watch has a deadline — 5 minutes by default, at most 30, and at most 10 in a non-interactive run given a single prompt with -p — and a watch a subagent started stops when that subagent is stopped from /tasks.

Everything that stops a background task

Four of these stop a background task. The other two look like stops and are not. The time limit you came here for is not on this list at all, because it has its own section above.

One thing that is not on that list is worth naming because it looks like it belongs: with CLAUDE_AUTO_BACKGROUND_TASKS set to 1, a subagent moves to the background after about two minutes of running. That is a task being created, not stopped.

Turning backgrounding off entirely

If you would rather nothing went to the background at all, set CLAUDE_CODE_DISABLE_BACKGROUND_TASKS to 1. That removes the option from the Bash, PowerShell and subagent tools, turns off Ctrl+B and background runs of forked skills, and stops Claude Code moving long subagents, long MCP calls and timed-out shell commands to the background on its own — so a command that reaches its timeout is stopped instead of moved. Starting in bare mode does the same. Monitor watches and MCP tasks still run in the background either way, so this is not a blanket off switch for every asynchronous thing.

What is lost when one dies

The honest answer is the work since the command started. Anthropic describes a command that reaches its limit as stopped, and nothing in the reference offers a resume, so treat it as stopped rather than suspended. What survives is the output file, which holds whatever the command had printed by then, and the fact that Claude knows why the command stopped.

The recovery is a restart with more room. Claude can start the command again with a longer timeout, and if the default itself is too short for the job, raise it with BASH_DEFAULT_TIMEOUT_MS or lift the 2-hour maximum with BASH_MAX_TIMEOUT_MS. A job whose state lives outside its own process (a build cache, a resumable download, a test runner that reuses its last run) will pick up cheaper than one that starts from nothing.

One detail is worth carrying into the restart. If the command had changed directory partway, that change never applied to the session, so the retry needs the directory set explicitly rather than inherited.

Four things this page is not about

The word "background" covers several different units in Claude Code, and mixing them up is the usual reason a search for this ends in the wrong page.

• A background subagent is a worker with its own context window, and /tasks lists it too. The subagents guide covers what those are and how they differ.
• A background session is a whole conversation running in the background, reached with claude agents or by backgrounding the terminal. The parallel agents guide covers that unit.
• Keeping a session alive after you disconnect is neither of these, it is a terminal problem. The tmux guide covers it, including the Ctrl+B collision that stops this page's own keystroke from working.
• A headless run is where the time limit actually bites hardest, because -p is an unattended session. The headless guide covers what else that run does at exit.

Omniscio and background tasks

Omniscio is the desktop app we make for running many Claude Code sessions at once. There is no Omniscio feature for this: the app has no control that lists, watches or kills a Claude Code background task, and this page is not selling one.

There is one real consequence, and it is a limit rather than a feature. Every session Omniscio starts is a print-mode run, because the app launches Claude Code with -p and speaks to it in stream-json on both stdin and stdout. Print mode is an unattended session, so the background time limit applies to every command a session backgrounds, and it is the 30-minute default rather than the 10-minute one, because the prompt arrives through --input-format stream-json instead of as text. In practice: a dev server or a long test run started inside an Omniscio session has a ceiling that the same command in your own terminal would not have, and BASH_DEFAULT_TIMEOUT_MS and BASH_MAX_TIMEOUT_MS are the two settings that move it.

Two things in the app sit near this subject without being it. Settings has a Hide background check-ins toggle, which collapses the short status line a session posts after its own background job wakes it; that is a display choice and it changes nothing about the job. And the app asks whether a session still owns live background work before letting it leave the board — a refusal to archive a session mid-job, which is bookkeeping rather than a task manager.

If you are comparing ways to run several sessions at once, the features page lists what the app does and the download page has the installers.

Sources

Every number, message and behaviour on this page rests on one of these. The date beside each one is the day we read it.

• Tools reference, for the background commands section, the time limit and its version notes, the two variables that raise it, the foreground-move behaviour, the output cap, the Monitor deadline, and the removal of the output-retrieval tool. Read October 27, 2026.
• Interactive mode, for how backgrounding works, the two ways in, the output file, cleanup at exit, the memory-pressure stop and its off switch, the off switch for background tasks, and the keybinding table. Read October 27, 2026.
• Commands, for /tasks, its /bashes alias, and what it lists. Read October 27, 2026.
• Environment variables, for BASH_DEFAULT_TIMEOUT_MS, BASH_MAX_TIMEOUT_MS, CLAUDE_CODE_DISABLE_BACKGROUND_TASKS, CLAUDE_AUTO_BACKGROUND_TASKS and CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP. Read October 27, 2026.
• Run Claude Code programmatically, for the wait at the end of a print-mode run, its 10-minute ceiling and the variable that moves it. Read October 27, 2026.
• GitHub issue 98273, open, for the report that background Bash tasks are killed at a time limit that was undocumented when it was filed. Read October 27, 2026.
• GitHub issue 104047, closed as not planned, for the report that the desktop app's sidebar shows a session as finished while its background tasks are still running. Read October 27, 2026.
• One capture run on this machine on October 27, 2026: claude --version, which printed 2.1.311 (Claude Code) — above v2.1.288, so the time limit applies only to unattended sessions on the build we checked.

Anthropic's own reference carries two version notes across the limit — 2.1.285 for when it appeared and 2.1.288 for when it narrowed to unattended sessions — so a copy of this page from a few months back is worth re-reading against the live page.

Common questions

Why did my background task stop on its own?

Read the line Claude was given. If it says the command was stopped after reaching its background time limit, that is the documented limit: 30 minutes from the moment the command entered the background, or the timeout Claude passed with it, up to a maximum of 2 hours, and only in a session that runs unattended. If it says output passed 5GB, the output cap stopped it. If the session had been idle on macOS or Linux, memory pressure can stop it too, and the debug log says why.

How do I see the background tasks running in my session?

Run /tasks. It lists the current session's background work, including subagents that have already finished, and it is also available as /bashes. Ctrl+T is not this view: it toggles Claude's to-do checklist, and Anthropic says so explicitly. Each background task also has its own output file, and Claude reads that file when it needs the output.

How do I kill a background task?

Open /tasks and stop it there, or stop it from a connected client such as the desktop app. Claude moves on instead of waiting for it. If a subagent started the command, stopping it is what lets that subagent move on. Ctrl+X Ctrl+K is a different key: it stops every running background subagent in the session, and you press it twice within three seconds to confirm.

Can I raise the time limit on a background command?

Yes, with two environment variables, and only upwards. Set BASH_DEFAULT_TIMEOUT_MS above 1800000 to replace the 30-minute default, and set BASH_MAX_TIMEOUT_MS above 7200000 to raise the 2-hour maximum. Both take milliseconds, and neither can shorten a limit, so a lower value leaves the defaults and the 2-hour maximum in place.