Bash Timeouts Polished

Configure timeout and output limits for bash command execution within Claude Code to prevent hanging commands while accommodating complex operations.

When to Use This Setting

Apply this setting when you need to:

• Prevent long-running build, test, or deployment commands from blocking Claude Code sessions indefinitely
• Increase default timeout limits for projects with complex compilation or data processing pipelines
• Control maximum output capture to prevent memory issues from verbose command output

Consider alternatives when:

• You only run quick, interactive commands that complete within the default 2-minute timeout
• Your workflow relies exclusively on IDE-integrated terminals rather than Claude Code bash execution

Quick Start

Configuration

Copy
name: bash-timeouts-polished
type: setting
category: environment

Example Application

Copy
claude setting:apply bash-timeouts-polished

Example Output

Setting applied successfully. Configuration changes:
- BASH_DEFAULT_TIMEOUT_MS: 120000 (2 minutes)
- BASH_MAX_TIMEOUT_MS: 600000 (10 minutes)
- BASH_MAX_OUTPUT_LENGTH: 100000 characters

Core Concepts

Timeout Management Overview

Aspect	Details
Default Timeout	120,000 ms (2 minutes)
Maximum Timeout	600,000 ms (10 minutes)
Output Limit	100,000 characters captured
Exceeded Behavior	Command terminated, partial output returned
Override	Per-command timeout parameter available

Timeout Architecture

┌──────────────────────────────────────┐
│        Bash Execution Pipeline       │
│                                      │
│  Command ──> Process ──> Output      │
│     │           │          │         │
│  ┌──┴───┐  ┌───┴────┐  ┌──┴──────┐  │
│  │Timer │  │Watchdog│  │Truncator│  │
│  │Start │  │Monitor │  │(100K)   │  │
│  └──┬───┘  └───┬────┘  └──┬──────┘  │
│     │          │           │         │
│  timeout?   hang?      overflow?     │
│     │          │           │         │
│  SIGTERM    SIGKILL    truncate      │
└──────────────────────────────────────┘

Configuration

Parameter	Type	Default	Description
BASH_DEFAULT_TIMEOUT_MS	string	"120000"	Default timeout for commands in milliseconds
BASH_MAX_TIMEOUT_MS	string	"600000"	Maximum allowable timeout per command
BASH_MAX_OUTPUT_LENGTH	string	"100000"	Maximum characters captured from stdout/stderr
BASH_KILL_SIGNAL	string	"SIGTERM"	Signal sent when timeout is reached
BASH_GRACE_PERIOD_MS	string	"5000"	Time between SIGTERM and forced SIGKILL

Best Practices

1. Profile Your Build Times First - Measure how long your typical build, test, and deployment commands take before setting timeouts. Set the default timeout to 150% of your longest routine command to provide a comfortable margin without allowing truly hung processes.

2. Use Per-Command Timeouts for Known Long Operations - Rather than increasing the global default, use the per-command timeout parameter for specific long operations like full test suites or Docker builds. This keeps the safety net tight for most commands.

3. Set Output Limits Based on Test Verbosity - If your test framework produces verbose output, increase BASH_MAX_OUTPUT_LENGTH accordingly. Truncated test output loses failure details at the end, which are typically the most diagnostic lines.

4. Monitor for Silent Timeouts - Commands that are terminated by timeout may not produce an error message. Check for timeout-related failures in your workflow and add explicit progress indicators to long-running scripts.

5. Balance Safety with Usability - Extremely short timeouts interrupt legitimate operations and frustrate developers. Extremely long timeouts defeat the purpose of the safety net. A 2-minute default with 10-minute maximum works well for most development workflows.

Common Issues

1. Build commands consistently timing out - Your project may have longer build times than the default allows. Increase BASH_DEFAULT_TIMEOUT_MS incrementally (try 180000 or 300000) rather than jumping to the maximum value.

2. Output truncated losing important error details - Error messages typically appear at the end of output, which gets truncated first. Increase BASH_MAX_OUTPUT_LENGTH or redirect verbose output to a file and read the file separately.

3. Zombie processes after timeout - Some commands spawn child processes that survive SIGTERM. Set BASH_KILL_SIGNAL to SIGKILL for commands known to resist graceful termination, though this prevents cleanup handlers from running.