Startup crashes with misleading fd error when project has many session files

Bug description

Claude Code crashes on startup when a project has accumulated a large number of session history files (.jsonl) in ~/.claude/projects/<project>/. The error message incorrectly attributes the failure to low file descriptor limits.

Error message shown

error: An unknown error occurred, possibly due to low max file descriptors (Unexpected)

Current limit: 256

To fix this, try running:

  ulimit -n 2147483646

Actual cause

The file descriptor limit is not the problem. Claude Code reads all .jsonl session files in the project directory at startup. When a project accumulates enough sessions (~100+ files, ~100+ MB), the startup parser fails.

Reproduction

1. Use Claude Code in a project over many sessions (we had 149 sessions, 135 MB total in .jsonl files)
2. Attempt to launch claude in that project directory
3. Startup crashes with the fd error above
4. The suggested ulimit -n 2147483646 fix does not work (and exceeds the macOS kernel cap anyway)

Diagnostic proof

• ulimit -n was already set to 1,048,576 — well above 256. The error message was wrong.
• Launching Claude Code from a clean temp directory (/tmp/claude-test) worked fine.
• Moving the 149 .jsonl files out of ~/.claude/projects/<project>/ immediately fixed the startup crash.
• Three separate projects (145, 149, and 101 sessions) all had this issue.

Environment

• macOS (Darwin 25.3.0)
• Claude Code installed via npm global (~/.npm-global/bin/claude)
• Node.js v22.14.0

Expected behavior

1. Startup should not choke on session history. Either lazy-load sessions, cap what's read at startup, or implement built-in session retention/pruning.
2. There should be a built-in config option for session retention (e.g., maxSessionAge, maxSessionCount).
3. The error message should be accurate. If the failure is an OOM or parse timeout from large session state, say that — not "low max file descriptors."

Workaround

Manually pruning old .jsonl files from ~/.claude/projects/<project>/ resolves the issue. A cron job with find ~/.claude/projects -name '*.jsonl' -mtime +30 -delete prevents recurrence.