Claude Code: 'did not complete within its 120s timeout'

You ask Claude Code to run the test suite. Two minutes later the output stops and you see this:

Command did not complete within its 120s timeout and was moved to the background

Nothing failed. Claude Code gives each shell command two minutes by default, and a command that is still going at the end of that time doesn't get killed: it keeps running in the background while the session carries on. The trouble starts when the agent reads the first two minutes of output as the whole answer, or starts the same build a second time.

This post shows what happens at the limit, how to raise it for a project with slow builds, and what changes in scripts and scheduled runs. Everything here was checked on Claude Code 2.1.316.

What happens at the limit#

We gave a project a test script that prints a line a second for 15 seconds, then all tests passed, and set the default limit to 5 seconds so the effect shows quickly. The tool result Claude got back was:

tick 1
tick 2
tick 3
tick 4
tick 5
Command did not complete within its 5s timeout and was moved to the background (ID: bn0oajbtn). Output is being written to: /private/tmp/claude-501/.../tasks/bn0oajbtn.output. You will be notified when it completes. ... It is running now: do not start a second copy while it runs.

So the command keeps going, its output goes to a file, and Claude is told when it ends. In our run Claude read the file, waited for the completion notice, and reported all tests passed correctly. That is the good path.

Where it goes wrong:

• The agent sums up from the first two minutes ("the build is still compiling, looks fine") and moves on before the result arrives.
• You change a file while the old test run is still going in the background, and its result comes back for code that no longer exists.
• A cd inside the backgrounded command is dropped for the rest of the session. Claude Code says so in the result, but it's easy to miss when reading back.

Check what is still running#

Type /tasks in the session. It lists the shell commands and subagents running in the background. Pick one to see its output so far, and press x to stop it. The footer under the prompt also shows a count such as 1 shell while anything is running.

Press Ctrl+B while a command is running to send it to the background yourself, before the limit. Useful for a dev server you know will never finish.

Raise the limit for slow projects#

The limit is an environment variable, in milliseconds. Put it in the project's .claude/settings.json so everyone working on the repo gets the same value:

{
  "env": {
    "BASH_DEFAULT_TIMEOUT_MS": "600000",
    "BASH_MAX_TIMEOUT_MS": "1200000"
  }
}

• BASH_DEFAULT_TIMEOUT_MS is what a command gets when Claude doesn't ask for a specific time: two minutes out of the box.
• BASH_MAX_TIMEOUT_MS is the most Claude can ask for on one command: ten minutes out of the box. The real ceiling is the larger of the two.

With the default raised to 30 seconds, the same 15-second script ran in the foreground and Claude got the full output, all tests passed included, in one result.

Set the default a little above your slowest normal run (a full test suite, a release build), not to hours. A command that really hangs, such as one waiting for a login in a browser, then still moves out of the way in reasonable time.

You don't set a timeout per command. Claude picks one when it thinks a command needs longer, within the ceiling. If you know a step is slow, say so in your project's CLAUDE.md: "The full test suite takes about 6 minutes. Run it with a 10-minute timeout, not in the background."

Scripts and scheduled runs#

Runs with claude -p behave a little differently:

• A command that moves to the background in a -p run gets 10 minutes there by default. When it reaches that, Claude Code stops it and tells Claude: Background command "…" was stopped after reaching its background time limit.
• An interactive session you work in has no time limit for background commands.
• With CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1, nothing moves to the background. A command that reaches the limit stops instead. We got Exit code 143 and Command timed out after 5s with the five lines of output before it.

If a nightly job runs a long build through Claude Code, raise BASH_DEFAULT_TIMEOUT_MS in that job's environment. Any value above ten minutes also replaces the 10-minute background default for -p runs.

Long output gets cut, too#

A command can finish in time and still lose its middle. Claude reads back about 30,000 characters of a successful command's output (and about 10,000 of a failed one) before it switches to a file path or an excerpt. A noisy build that fails on line 4,000 can hide the error. Two fixes:

• Ask for quieter output: npm test -- --reporter=dot, pytest -q, cargo build 2>&1 | tail -50.
• Raise BASH_MAX_OUTPUT_LENGTH (up to 150,000 characters) if your commands often go over.

Where Joxo fits#

A build that runs for ten minutes is a good time to step away. With Joxo, your agent's question or finished result reaches your phone, and your teammates can see which of your sessions is still running before they start the same work. Setup is one line pasted into your agent.

Frequently asked questions#

What is Claude Code's default command timeout?#

Two minutes for a shell command when Claude doesn't ask for more, and ten minutes at most. Change them with BASH_DEFAULT_TIMEOUT_MS and BASH_MAX_TIMEOUT_MS in the env block of settings.json.

Did my command fail when it moved to the background?#

No. It keeps running, its output goes to a file, and Claude is told when it finishes. Check it with /tasks.

How do I stop a background command in Claude Code?#

Type /tasks, pick the command, and press x. Background commands also stop when you exit Claude Code.

Why did my command stop at the timeout instead of moving to the background?#

Background commands are off: CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 is set, or the session started in bare mode. Commands that start with sleep also stop at the limit.