Claude Code: 30-minute background command limit

Claude Code stops a background command after 30 minutes when it runs unattended: a launch with the -p flag, an Agent SDK application, a CI job or a cloud session. If Claude sets a time for the command itself, it will run for no more than 2 hours, while the ordinary terminal, desktop app and VS Code have had no limit since version 2.1.288.

I used to sit in front of the screen all day: give the agent a step, take a look, make a correction, ask it to continue. Phase after phase. The machine may be writing the code, but I was the one driving it. Now I write a plan, split it into phases, hand the implementation to subagents overnight and leave. In 8 hours without me, Claude works through the plan: studies, builds and refines. In the morning, I spend more time accepting the work than redoing it.

But if an overnight run uses -p, runs on a schedule on a server, in CI or in the cloud, a development server and a build running in the background will last 30 minutes. Then Claude Code will stop them, and the overnight work will stumble halfway through. I'll explain who the limit affects, how to raise it and what to do if a command has already stopped. Let's go.

For help using the service, see the Ailoot documentation.

Who the limit affects#

A background command is something Claude starts and leaves running while it is busy with something else. For example, a development server started with npm run dev, or a build that watches files for changes.

The Claude Code documentation says:

In other words, the limit applies when you are not there: a run with -p, an Agent SDK application, a CI job or a cloud session. There is no limit in the terminal, desktop app or VS Code when you work in the session yourself. It was introduced in 2.1.285 and applied everywhere before 2.1.288.

How to tell whether this applies to you:

• You opened Claude Code in the terminal or VS Code, gave it a task and went to bed. There is no limit if the version is 2.1.288 or newer. In versions 2.1.285 through 2.1.287, it applies here too. I explained how to update to the latest version in a separate article.
• Claude Code is launched with claude -p "task" on a schedule, from your own Agent SDK application or in CI. The limit applies.
• The task runs in a cloud session. The limit applies.

When I set agents to work independently, I ask in the prompt: “Write these conditions and the reasons for stopping into the working plan. Check that the process does not depend on a window I will close or on the computer itself.” The 30-minute limit is one of those reasons.

How long can a Claude Code background command run?#

The countdown starts when the command enters the background. There are 2 cases.

Claude starts the command in the background immediately. It gets 30 minutes. If Claude specifies a time when starting it (the timeout parameter), it gets that time, but no more than 2 hours.

The command does not finish while Claude is waiting for it. Claude waits 2 minutes for an ordinary command. If it has not finished, Claude Code does not stop it; it moves it to the background. From that point, it has 30 minutes.

When the time is up, Claude Code stops the command and tells Claude:

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

If the work is unfinished, Claude can run the command again with a longer time.

And one more point about -p. With this kind of run, background commands terminate approximately 5 seconds after Claude's final response. A server started in an overnight run with -p will last only as long as the run itself. The 30-minute limit matters when the run lasts longer: Claude starts a server at the beginning and spends an hour running checks against it.

How to organize overnight work in Claude Code#

I got tired of driving the agent all day, so I replaced that with one orchestrator prompt. I start it in the evening, and Claude works all night, going through the phases in order: writing, checking, fixing and committing on its own.

Groups of subagents write the code, each with its own files so they do not get in each other's way. Another, fresh group accepts the work: code review, security checks and live checks. If they find a problem, it is fixed immediately and the checks run again. The prompt includes the line: “If you run out of context, record the state; the next run will continue.”

In the example described, over 3 days, 8 of 14 phases were completed this way.

There are just 2 points to keep in mind. The orchestrator does not do your thinking for you: first, write a detailed plan with phases, then start the overnight shift. And it consumes a lot of your subscription allowance, so there is little point in setting this up for a small task. Always limit the number of attempts, or the agent will burn through your entire subscription allowance overnight. I explained how to set these spending limits in a separate article.

How to raise the limit#

Option 1: ask Claude. Claude chooses the time for a particular command; you do not set it yourself. But you can write in the task: “Keep the development server in the background for 2 hours.” You cannot get more than 2 hours this way.

Option 2: variables in the settings file. Values are in milliseconds. You cannot lower the limits below 30 minutes and 2 hours; you can only raise them.

• BASH_DEFAULT_TIMEOUT_MS set above 1800000 (30 minutes) changes the 30-minute default. It applies both to commands Claude starts in the background without specifying a time and to commands moved to the background after a timeout. If you set it above 7200000 (2 hours), the ceiling rises too.
• BASH_MAX_TIMEOUT_MS set above 7200000 raises the 2-hour ceiling. It does not change the 30-minute default: a command without its own specified time will still stop after 30 minutes.

BASH_DEFAULT_TIMEOUT_MS has a side effect. The same variable sets how long Claude waits for an ordinary command before moving it to the background. Set it to 1 hour, and Claude will wait 1 hour instead of 2 minutes. That does not get in the way overnight. During the day, you will wait longer for a response when commands take a long time.

If you do not want to work through the details: if you need 3 hours for both ordinary commands and the ceiling, set BASH_DEFAULT_TIMEOUT_MS to 10800000. That is enough; you do not need the second variable.

The settings file is in the .claude folder in your home directory: ~/.claude/settings.json on macOS and Linux, and %USERPROFILE%\.claude\settings.json on Windows. If the file does not exist, create it. A 1-hour limit looks like this:

{
  "env": {
    "BASH_DEFAULT_TIMEOUT_MS": "3600000"
  }
}

If the file already has an env block, add the line to it. A running session picks up the new values when you save the file. Removing a variable takes effect only the next time you start claude.

The file must be on the machine where the agent is running. For the agent to work overnight, the computer must not go to sleep. Alternatively, run Claude Code on a remote server and put the settings there.

If the command has already stopped#

You do not need to do anything manually. Claude Code tells Claude why a command stopped, so first just ask it what happened.

Then proceed step by step:

1. A one-off long run of up to 2 hours. Ask Claude to rerun the command with a longer time.
2. Commands regularly need more than 30 minutes. Set BASH_DEFAULT_TIMEOUT_MS above 1800000 in the settings file, as in the example above. If you need more than 2 hours, also set BASH_MAX_TIMEOUT_MS above 7200000 there.
3. Run the command again. The documentation makes no promises about a command that was already running in the background before the change.
4. Check the result of the next run. If Claude's report again contains the phrase “stopped after reaching its background time limit,” the setting did not apply to that command.

Subagents and routines are what keep the agent working while you are away.

I explained how to run an agent in a loop all night in a separate article. And how to configure Claude Code so it does not break the project overnight is explained here.

Check which step stops your overnight run, and compare the reason with the limits above.

Get to know Ailoot.