Timeout Configuration

Overview

The autospec CLI supports configurable timeouts for configured agent command execution to prevent indefinite hangs in automated workflows. When a command exceeds the configured timeout, it is automatically terminated and returns exit code 5.

Quick Start

Set Timeout via Environment Variable

# Set 10-minute timeout for all commands
export AUTOSPEC_TIMEOUT=600

# Run commands with timeout
autospec prep "Add user authentication"
autospec plan
autospec implement

Set Timeout via Configuration File

Local config (project-specific):

mkdir -p .autospec
cat > .autospec/config.yml << EOF
timeout: 600
EOF

Global config (all projects):

mkdir -p ~/.config/autospec
cat > ~/.config/autospec/config.yml << EOF
timeout: 1800
EOF

Configuration Details

Valid Timeout Values

Value	Meaning	Common Use Cases
0	No timeout	Development, interactive use, debugging
30	30 seconds	Quick commands, testing timeout behavior
300	5 minutes	Most workflow commands
600	10 minutes	Complex planning/implementation
1800	30 minutes	Large features
2400	40 minutes (default)	Full workflows
3600	1 hour	Very complex tasks
86400	24 hours	Extremely long-running operations
604800	7 days (maximum)	Extended background processing

Configuration Priority

Configuration sources are applied in this order (highest to lowest priority):

1. Environment Variable: AUTOSPEC_TIMEOUT
2. Local Config: .autospec/config.yml (current directory)
3. Global Config: ~/.config/autospec/config.yml (home directory)
4. Default: 2400 (40 minutes)

Example: Multiple Configuration Sources

# Global config: 30 minutes
echo 'timeout: 1800' > ~/.config/autospec/config.yml

# Local config: 10 minutes (overrides global)
echo 'timeout: 600' > .autospec/config.yml

# Environment variable: 5 minutes (overrides all)
export AUTOSPEC_TIMEOUT=300

# Result: timeout = 300 seconds

Usage Examples

Basic Usage

# Default: no timeout
autospec prep "feature"

# With 5-minute timeout
AUTOSPEC_TIMEOUT=300 autospec prep "feature"

# With 30-minute timeout
AUTOSPEC_TIMEOUT=1800 autospec implement

Different Timeouts per Command

#!/bin/bash
# Quick commands: 5 minutes
AUTOSPEC_TIMEOUT=300 autospec specify "Add user profile feature"

# Planning: 10 minutes
AUTOSPEC_TIMEOUT=600 autospec plan

# Implementation: 30 minutes
AUTOSPEC_TIMEOUT=1800 autospec implement

CI/CD Pipeline

#!/bin/bash
set -e

# Prevent indefinite hangs in CI
export AUTOSPEC_TIMEOUT=600  # 10 minutes max

autospec prep "feature description"
exit_code=$?

if [ $exit_code -eq 5 ]; then
    echo "ERROR: Command timed out after 10 minutes"
    echo "Consider:"
    echo "  1. Breaking the feature into smaller pieces"
    echo "  2. Increasing the timeout for this specific feature"
    echo "  3. Investigating why the command is taking so long"
    exit 1
fi

Retry with Increased Timeout

#!/bin/bash
timeout=300

for attempt in 1 2 3; do
    echo "Attempt $attempt with ${timeout}s timeout"

    AUTOSPEC_TIMEOUT=$timeout autospec prep "complex feature"
    exit_code=$?

    if [ $exit_code -eq 5 ]; then
        echo "Timed out. Doubling timeout and retrying..."
        timeout=$((timeout * 2))
    elif [ $exit_code -eq 0 ]; then
        echo "Success!"
        exit 0
    else
        echo "Failed with exit code $exit_code"
        exit $exit_code
    fi
done

echo "All retries exhausted"
exit 1

Timeout Behavior

What Happens When a Timeout Occurs

1. Process Termination: On Linux and macOS, headless agents run in their own process group. The whole group (the agent plus any tool, MCP, or background processes it started) receives SIGTERM, then SIGKILL if it has not exited within 3 seconds. On other platforms only the agent process is killed.
2. Reaped Before Return: autospec returns only after the process group is gone, so no agent descendant can keep modifying the workspace afterwards. The same cleanup runs when you interrupt autospec with Ctrl+C or SIGTERM, and after a headless agent exits normally.
3. Error Return: A TimeoutError is returned with details
4. Exit Code 5: The CLI exits with code 5 (specific to timeouts)
5. Helpful Message: Error message includes:
   • Timeout duration
   • Command that timed out
   • Suggestions for increasing the timeout

Example Timeout Output

Error: command timed out after 5m0s: claude /autospec.implement (hint: increase timeout in config)

To increase the timeout, set AUTOSPEC_TIMEOUT environment variable or update config.yml:
  export AUTOSPEC_TIMEOUT=600  # 10 minutes
  or edit .autospec/config.yml and set "timeout: 600"

Verification and Testing

Check Current Timeout Configuration

# View all configuration including timeout
autospec config show

# Check environment variable
echo $AUTOSPEC_TIMEOUT

# Check local config
cat .autospec/config.yml

# Check global config
cat ~/.config/autospec/config.yml

Test Timeout Behavior

# Test with very short timeout (should timeout quickly)
AUTOSPEC_TIMEOUT=1 autospec specify "test feature"

# Expected: Times out after ~1 second with exit code 5
echo "Exit code: $?"  # Should be 5

Disable Timeout Temporarily

# Disable timeout for debugging
AUTOSPEC_TIMEOUT=0 autospec prep "feature"

# Or unset the environment variable
unset AUTOSPEC_TIMEOUT
autospec prep "feature"

Best Practices

1. Start Conservative

Begin with a reasonable timeout (e.g., 10 minutes) and adjust based on actual command duration:

# Track how long commands actually take
time autospec prep "feature"

# Set timeout to 2x the typical duration
# If commands typically take 5 minutes, set timeout to 10 minutes
export AUTOSPEC_TIMEOUT=600

2. Use Different Timeouts for Different Environments

Development (generous or no timeout):

# ~/.bashrc or ~/.zshrc
export AUTOSPEC_TIMEOUT=0  # No timeout for interactive work

CI/CD (strict timeout):

# .github/workflows/ci.yml or similar
env:
  AUTOSPEC_TIMEOUT: 600  # 10 minutes max

3. Document Project-Specific Timeouts

In your project README:

## Autospec Configuration

This project's workflows typically complete in:
- Specify: 2-3 minutes
- Plan: 5-8 minutes
- Tasks: 2-3 minutes
- Implement: 15-20 minutes

**Recommended timeout**: 1800 seconds (30 minutes)

```bash
echo 'timeout: 1800' > .autospec/config.yml

### 4. Monitor and Adjust

Keep track of timeout occurrences:

```bash
# In CI/CD, log timeout information
autospec prep "feature" 2>&1 | tee autospec.log
if [ $? -eq 5 ]; then
    echo "TIMEOUT OCCURRED" >> timeout-incidents.log
    date >> timeout-incidents.log
fi

Exit Codes

The autospec CLI uses standardized exit codes:

Code	Meaning	Action
0	Success	Continue workflow
1	Validation failed	Retry possible
2	Retry limit exhausted	Manual intervention needed
3	Invalid arguments	Fix command syntax
4	Missing dependencies	Install required tools
5	Command timeout	Increase timeout or investigate

Handling Timeout Exit Code in Scripts

autospec prep "feature"
case $? in
    0)
        echo "Success"
        ;;
    5)
        echo "Command timed out - increase timeout or break into smaller tasks"
        ;;
    *)
        echo "Other error occurred"
        ;;
esac

Troubleshooting

Issue: Commands timeout unexpectedly

Symptoms: Exit code 5, error message about timeout

Solutions:

1. Increase timeout:

   export AUTOSPEC_TIMEOUT=1800  # Try 30 minutes
   

2. Check what’s taking so long:
   • Large feature descriptions may take longer to process
   • Complex planning phases need more time
   • Implementation of large features can be time-consuming
3. Break down the work:
   • Split large features into smaller, focused tasks
   • Implement incrementally

Issue: Timeout not being respected

Symptoms: Commands run longer than configured timeout

Diagnostics:

# 1. Verify timeout is set
autospec config show | grep timeout

# 2. Check environment variable
echo $AUTOSPEC_TIMEOUT

# 3. Verify binary version
autospec version

Solutions:

• Ensure AUTOSPEC_TIMEOUT environment variable is set correctly (all caps)
• Check that config file YAML is valid
• Reload shell session or restart terminal

Issue: Want no timeout for development

Solution:

# Method 1: Set to 0
export AUTOSPEC_TIMEOUT=0

# Method 2: Unset the variable
unset AUTOSPEC_TIMEOUT

# Method 3: Update config
echo 'timeout: 0' > .autospec/config.yml

Advanced Configuration

Per-Command Timeouts

While the CLI doesn’t support per-command timeouts directly, you can work around this:

#!/bin/bash
run_with_timeout() {
    local timeout=$1
    shift
    AUTOSPEC_TIMEOUT=$timeout "$@"
}

# Different timeouts for different commands
run_with_timeout 300 autospec specify "feature"    # 5 min
run_with_timeout 600 autospec plan                 # 10 min
run_with_timeout 1800 autospec implement           # 30 min

Conditional Timeouts

#!/bin/bash
if [ "$CI" = "true" ]; then
    # Strict timeout in CI
    export AUTOSPEC_TIMEOUT=600
else
    # No timeout in development
    export AUTOSPEC_TIMEOUT=0
fi

Dynamic Timeout Based on Feature Size

#!/bin/bash
feature_description="$1"
word_count=$(echo "$feature_description" | wc -w)

# Longer descriptions get more time
if [ $word_count -gt 50 ]; then
    timeout=1800  # 30 minutes
elif [ $word_count -gt 20 ]; then
    timeout=900   # 15 minutes
else
    timeout=300   # 5 minutes
fi

AUTOSPEC_TIMEOUT=$timeout autospec prep "$feature_description"

See Also

• Troubleshooting Guide
• CLAUDE.md - Development documentation
• Configuration Reference