claudish/ai_docs/TIMEOUT_CONFIGURATION_CLARIFICATION.md

Timeout Configuration Clarification

Summary

Claudish does not have a hard-coded 10-minute timeout configuration. The timeout is controlled by Claude Code's Anthropic TypeScript SDK (generated by Stainless), not by Claudish.

What Was the Issue?

Users were seeing references to a "10-minute timeout" and assuming it was a hard-coded limit in Claudish that they needed to work around or configure. This created confusion about what Claudish controls vs. what Claude Code controls.

Investigation Results

✅ No timeout configurations found in Claudish source code:

1. No CLI timeout flags: No --timeout option or timeout-related CLI arguments
2. No server timeout config: No idleTimeout, server.timeout, or similar configurations
3. No fetch timeout: No AbortController, AbortSignal, or timeout parameters in fetch calls
4. No hard-coded values: No magic numbers like 600000 (10 minutes in ms) or 600 (10 minutes in seconds)

✅ What claudish DOES have:

1. TypeScript timer types: NodeJS.Timeout - TypeScript type definitions for interval timers (not timeout configurations)
2. Short UI delays: 200ms delays for stdin detachment in interactive prompts
3. Adaptive ping mechanism: Keeps streaming connections alive during long operations (this prevents network-level timeouts, not API-level timeouts)

✅ What controls the timeout:

The x-stainless-timeout: 600 (10 minutes) header is set by Claude Code's Anthropic SDK, which:

• Is generated by Stainless (a code generation tool)
• Uses the standard Anthropic TypeScript SDK
• Configures a 600-second (10 minute) timeout per API call
• Is not configurable by the proxy (Claudish)

Understanding the Timeout

Per-API-Call vs. Session Timeout

• Per API call: 10 minutes (set by Claude Code SDK)

  • Each conversation turn = 1 API call
  • Claude Code → Proxy → OpenRouter/Anthropic → Response
  • Each call can stream for up to 10 minutes

• Total session: Can run for hours

  • Multiple API calls over time (20-30+ calls)
  • Each call respects the 10-minute limit
  • Example: 2-hour session with 15 API calls

Example Session

Session: 2 hours total
├── API Call 1: 8 minutes (generate plan)
├── API Call 2: 3 minutes (write code)
├── API Call 3: 9 minutes (run tests)
├── API Call 4: 5 minutes (fix issues)
└── ...many more calls

What Was Changed

Documentation Updates

Updated these files to clarify timeout is set by Claude Code SDK:

1. ai_docs/MONITOR_MODE_COMPLETE.md - Updated "Timeout Configuration" section
2. ai_docs/MONITOR_MODE_FINDINGS.md - Added note about x-stainless-* headers
3. ai_docs/PROTOCOL_SPECIFICATION.md - Updated timeout references with clarification
4. ai_docs/CLAUDE_CODE_PROTOCOL_COMPLETE.md - Context already clear

Code Verification

Verified no timeout configurations exist in:

• src/cli.ts - CLI argument parsing
• src/config.ts - Configuration management
• src/proxy-server.ts - Server implementation
• src/index.ts - Main entry point
• All other source files

Server Configuration

Claudish uses @hono/node-server which:

• Uses Node.js standard http.Server
• Does not set explicit timeout values
• Relies on Node.js defaults (no timeout or timeout = 0 = no timeout)
• Handles long-running streaming connections appropriately

Network-Level Timeouts

The proxy includes an adaptive ping mechanism that:

• Sends periodic pings every second if no content for >1 second
• Prevents network-level (TCP) timeouts
• Keeps connection alive during encrypted reasoning or quiet periods
• Is different from the 10-minute API timeout (this is at network layer)

Recommendations

For Users

Don't try to configure timeout - It's not necessary:

• The 10-minute timeout is per API call, not per session
• Long-running tasks automatically make multiple API calls
• The proxy handles network-level keep-alive

For Developers

If implementing a proxy:

• Do not set explicit timeouts unless you have a specific reason
• Let the client's SDK control request timeout
• Handle network-level timeouts with pings if needed
• Document what timeout values mean and where they come from

References

• Protocol Specification: ai_docs/PROTOCOL_SPECIFICATION.md
• Timeout findings: ai_docs/MONITOR_MODE_FINDINGS.md:55
• Monitor mode documentation: ai_docs/MONITOR_MODE_COMPLETE.md:353
• Stainless SDK: https://stainless.com/

Verification

Run this to verify no timeout configs exist:

# Check for CLI timeout flags
grep -r "--timeout" src/ --include="*.ts"

# Check for server timeout configs
grep -r "idleTimeout\|server.*timeout" src/ --include="*.ts"

# Check for fetch timeouts
grep -r "fetch.*timeout\|AbortController" src/ --include="*.ts"

Expected result: No matches (except TypeScript types and short UI delays)

Conclusion

Claudish is timeout-agnostic. It does not control, configure, or enforce the 10-minute timeout. This is entirely controlled by Claude Code's SDK. The proxy's job is to pass the timeout header through without modification and handle streaming appropriately.