Claude Desktop PTY/fd leak — bug report draft (2026-05)

상태: Draft. 운영자 검토 후 [email protected] 또는 claude-code GitHub issues  에 그대로 전송 가능한 self-contained 리포트.

Backlog: B-claudeapp-fd-leak-anthropic-report · Tracking: B-claude-desktop-pty-leak-track · Mitigation: B-axe-pty-max-launchd

관련 분석: Claude.app /dev/ptmx fd leak (known-gaps)

1. Summary

Claude Desktop on macOS leaks file descriptors to /dev/ptmx, accumulating fd usage over weeks of normal operation until the system-wide kern.tty.ptmx_max limit is reached. After that, new terminal/PTY spawns fail with forkpty: Device not configured (ENXIO), affecting all macOS users on the host (not just Claude.app itself). The only known fix is to quit and restart Claude Desktop, which reclaims all leaked fds.

2. Environment

• OS: macOS (Darwin 25.3.0 at time of reproduction)
• App: Claude Desktop — /Applications/Claude.app/Contents/MacOS/Claude
• Hardware: Apple Silicon mac mini
• Uptime at failure: 43+ days continuous operation (observed 2026-05-26)
• PTY limit: kern.tty.ptmx_max = 511 (macOS default; sysctl raise to 2047 is rejected by kernel)

3. Symptom

3.1 Failure mode

• New terminal spawns (Terminal.app, iTerm2, Claude Code subprocess forkpty()) are denied with ENXIO.
• Error string: forkpty: Device not configured
• Scope: system-wide — not limited to Claude.app. All users on the host lose the ability to allocate new PTYs until the leak is cleared.

3.2 Reproduction

1. Use Claude Desktop normally on a macOS host (open many chats, close them, leave the app running).
2. After 1–2 weeks of continuous uptime, monitor PTY fd consumption:

   sudo lsof /dev/ptmx | grep -i Claude | wc -l

   Count grows steadily over time.
3. When the total lsof /dev/ptmx count reaches kern.tty.ptmx_max (default 511), forkpty: Device not configured starts to fire on every new PTY allocation attempt.

3.3 Diagnosis commands

# Per-process PTY fd occupancy (sorted)
sudo lsof /dev/ptmx | awk '{print $1}' | sort | uniq -c | sort -rn
 
# Kernel PTY ceiling
sysctl kern.tty.ptmx_max
 
# Detailed fd list for Claude.app PID
ps aux | grep -i Claude
sudo lsof -p <claude-pid> | grep /dev/ptmx | wc -l

3.4 Observed data (2026-05-26, operator host)

• Claude.app PID held fds 43, 44, 46, 88, 89, 92, 94, 98, 99, 102+ against /dev/ptmx.
• Reaping userspace zsh zombies (82 accumulated, all Claude Code subprocesses) did not release the ptmx fds — confirming the leak is in Claude.app proper, not in spawned shells.

4. Workarounds (current)

5. Suspected root cause

• Claude.app spawns PTY-backed subprocesses (IPC helpers, terminal-like surfaces) without releasing the master fd when the subprocess exits or the chat is closed.
• Reaping orphaned userspace zsh zombies (Claude Code subprocesses) does not free the /dev/ptmx fds — strongly suggests the leak is in the Claude.app process holding the master end open after the slave has gone away.
• Pattern is consistent with missing close() on the master fd in a subprocess lifecycle path.

6. Impact

• Affected users: macOS users running Claude Desktop with long uptime (1–2 weeks+) and any non-trivial chat volume.
• Blast radius: system-wide PTY denial — all terminal applications on the host are blocked from spawning new sessions, not just Claude.app.
• Detectability: silent until the limit is hit; the failure surfaces in unrelated apps (Terminal.app, iTerm2) and is hard to attribute to Claude.app without running lsof /dev/ptmx.

7. Requested fix

1. Audit Claude.app’s PTY subprocess lifecycle — ensure master fds are close()d when the slave end exits or the owning chat/IPC channel is torn down.
2. Guarantee close-on-exit semantics for all spawned PTYs.
3. Add a self-check in the production build: if Claude.app’s own /dev/ptmx fd count exceeds a threshold (e.g. 100), emit a telemetry event so this regression is caught automatically in future releases.

8. Attachments / references

• Operator known-gaps entry: Claude.app /dev/ptmx fd leak
• Related operator backlog items:
  • B-claude-desktop-pty-leak-track — tracking the recurrence
  • B-axe-pty-max-launchd — host-side mitigation attempt
  • B-claudeapp-fd-leak-anthropic-report — this report

9. Submission channels

• Email: [email protected]
• GitHub: https://github.com/anthropics/claude-code/issues  — cross-post recommended since the symptom also surfaces from Claude Code’s subprocess forkpty() paths.

10. Status

운영자가 검토 후 위 채널 중 하나로 제출. 회신 수령 시 본 페이지 §10 표를 갱신하고 /ops/known-gaps 의 해당 항목에 진행 상황 한 줄 추가.