[SOLUTION] Complete Claude Code Timeout Configuration Guide - Verified Working

[SOLUTION] Complete Claude Code Timeout Configuration Guide - Working for Many Users

Summary

Problem Addressed: Claude Code 2-minute timeout limitation. This issue provides solutions that have worked for multiple users, though effectiveness may vary by environment.

Environment

• Platform: Anthropic API
• Claude CLI version: Latest (tested on v1.0.x)
• Operating System: macOS (should work on all platforms)
• Terminal: Any terminal

✅ Solution for Claude Code Bash Tool

Problem

Claude Code automatically kills bash commands after exactly 2 minutes, regardless of wrapper scripts or shell environment variables.

Working Solution (Verified by Multiple Users)

Configure timeout in ~/.claude/settings.json under the env section:

{
  "mcpServers": {
    // ... existing configurations
  },
  "env": {
    "BASH_DEFAULT_TIMEOUT_MS": "1800000",    // 30 minutes
    "BASH_MAX_TIMEOUT_MS": "7200000"         // 120 minutes
  },
  "hooks": {
    // ... existing hooks
  }
}

Test Results (Environment-Dependent)

| Test Duration | Default Behavior | With Configuration | Status |
|--------------|------------------|-------------------|--------|
| 30 seconds | ✅ Success | ✅ Success | No change |
| 3 minutes | ❌ Timeout | ✅ Success* | Works for many |
| 30 minutes | ❌ Timeout | ✅ Success* | Works for many |

*Results may vary by system configuration

Test Command: echo "Test start: $(date)" && sleep 180 && echo "Test complete: $(date)"

❌ Failed Approaches (Confirmed Not Working)

1. GNU timeout wrappers: gtimeout 1800 codex exec "task" - Overridden by internal timeout
2. Shell environment variables: export BASH_DEFAULT_TIMEOUT_MS=1800000 - Ignored by Claude Code
3. Codex profile configuration: timeout = 1800 in ~/.codex/config.toml - Different execution context
4. Project-level settings: .claude/settings.local.json - Not recognized for timeout config

🆕 Discovery: Codex Exec Dual-Layer Timeout Architecture

During investigation, I discovered that Codex Exec has a dual-layer timeout system:

Layer 1: Application Timeout (Configurable) ✅

• Control: ~/.codex/config.toml timeout settings
• Limit: Up to ~2.5 minutes tested successfully
• Test: cxl "sleep 150" → SUCCESS (2.5 minutes)

Layer 2: Sandbox Timeout (Hardcoded) ❌

• Limit: Approximately 2-3 minutes (appears hardcoded)
• Error: "sandbox error: command timed out"
• Test: cxmarathon "sleep 300" → FAILED (5 minutes)

💡 Practical Recommendations

For Short-Medium Tasks (< 2.5 minutes)

• Use Codex Exec with configured timeouts in config.toml
• Commands: cxl, cxd, cxf, etc.
• Configure timeout in ~/.codex/config.toml: timeout = 1800

For Long Tasks (> 2.5 minutes)

• Use Claude Code Bash Tool with settings.json env configuration
• Extended timeout capability reported by multiple users
• Test incrementally to verify in your environment

🔬 Root Cause Analysis

The fundamental issue was configuration location:

• ❌ Shell Environment: Variables ignored by Claude Code internal timeout system
• ❌ Wrapper Commands: Overridden by Claude Code's internal process management
• ✅ Claude Code Settings: Direct configuration of internal timeout system via settings.json

Key Insight: Claude Code requires internal configuration rather than external workarounds. The timeout must be set in Claude Code's own settings system.

📊 Potential Benefits

This solution may enable:

• Long-running builds: Multi-hour compilation processes
• Large-scale analysis: Extended codebase processing
• Database operations: Long migrations and transformations
• AI processing: Extended model training and inference
• Package installations: Dependencies that take > 2 minutes to install
• Data processing: Large file operations and transformations

🎯 Step-by-Step Implementation Guide

1. Backup current settings:

``bash
cp ~/.claude/settings.json ~/.claude/settings.json.backup
``

1. Edit settings file:

``bash
# Use your preferred editor
code ~/.claude/settings.json
# or
vim ~/.claude/settings.json
``

1. Add or modify the env section as shown in the solution above

1. Validate JSON syntax:

``bash
python3 -m json.tool ~/.claude/settings.json > /dev/null && echo "✅ Valid JSON" || echo "❌ Invalid JSON"
``

1. Restart Claude Code completely: Full application restart required for settings to take effect

1. Test with incremental timeouts: Start with 5-10 minutes, then increase as needed

🔍 Troubleshooting

Settings Not Taking Effect

• Ensure JSON syntax is valid
• Complete Claude Code restart (not just session restart)
• Check that env section is at the correct level in JSON structure
• Verify file permissions allow reading

Performance Considerations

• Start with conservative timeout values (10-30 minutes)
• Monitor system resources during long-running commands
• Consider using timeout command within scripts for additional safety

Related Issues

This solution builds on discussions in:

• #1635: "There is no way to override the 2 minute timeout for shell commands" (environment variables suggested by @wolffiex)
• #1717: "increasing timeout environmental variable" (mixed results - works for some users)
• #1539: "Claude doesn't know how to extend timeouts" (environment variable configuration suggested)

Testing and Verification

• Tested on: Claude Code latest version, macOS
• User Reports: Multiple users report success, some report continued issues
• Recommendation: Test incrementally in your specific environment

---

Status: ✅ Works for many users - test in your environment
Impact: May resolve timeout limitation for development workflows requiring extended execution times

This solution has helped multiple users but effectiveness may depend on your specific system configuration. Please test and report your results.