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](https://stainless.com/) (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:

```bash
# 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.