Breaking the 2-Minute Barrier: Solving Long-Running Command Timeouts in Claude Code

This article is based on and reposted from a post on my personal blog.

I'm K@zuki., and I haven't yet translated the articles I wrote in English back into Japanese.

Have you ever had an experience where a test execution or build stopped midway due to a timeout while using Claude Code?
Claude Code has a default timeout of 2 minutes.
In this article, I'll introduce three ways to bypass this limit.

TL;DR

• The default timeout for Claude Code is 2 minutes (120 seconds).
• It can be extended up to 10 minutes (600 seconds).
• Configuration methods:
  • Individual specification
  • Environment variables
  • settings.json

Why are timeouts necessary?

Claude Code is an interactive AI tool, but there's a possibility that a running command could fall into an infinite loop or stop responding.
The default 2-minute limit is long enough for many commands, but it's completely insufficient in cases like the following:

• Running large-scale tests
• Time-consuming builds
• Large-scale migrations
• Batch processing with large amounts of data

I often encounter this when running large-scale tests.

Method 1: Specifying a timeout for individual commands

The simplest way is to specify the timeout individually for commands that run for a long time.

docker compose run --rm -it app bin/rspec # timeout 600000ms

Specify the time in milliseconds using timeout either before or after the command executed by the Bash tool.
The maximum value is 600000ms (10 minutes).

While it doesn't strictly have to be in milliseconds, writing it in the format timeout xms when executing a command seems to change the timeout more consistently.

Method 2: Changing the overall default via environment variables

If you frequently run long-running commands, you can change the default timeout using an environment variable.

export BASH_DEFAULT_TIMEOUT_MS=300000

This sets the default timeout for all Bash commands to 5 minutes.

https://docs.anthropic.com/en/docs/claude-code/settings

Method 3: Setting environment variables in settings.json

It also seems possible to set the environment variable mentioned in Method 2 in the Claude Code configuration file.
*Note: I haven't verified this operation personally; this is based on the description in the official documentation.

{
  "env": {
    "BASH_DEFAULT_TIMEOUT_MS": "300000"
  }
}

With this setting, the timeout will be automatically set to 5 minutes every time you start Claude Code.

https://docs.anthropic.com/en/docs/claude-code/settings

Points to Note

• If you set the timeout too long, it may take longer to detect problematic commands.
• Since 10 minutes is the maximum value, consider splitting processes that take longer than that.
• Unlike execution in CI/CD pipelines, it is designed for interactive use.

Shortening the Timeout

Conversely, it is also possible to shorten the timeout.

sleep 5 # timeout 1000ms

By writing it this way, you can also make the timeout shorter.

Summary

Claude Code's timeout settings are an important factor that significantly impacts development efficiency.
If the default 2 minutes is insufficient, use the methods introduced in this article to adjust it appropriately.
In particular, settings via environment variables or settings.json are recommended because once they are configured, you don't have to worry about them again.

I hope you all have a comfortable development life with Claude Code!