--- name: claude-transcript-bloat-fix description: >- Diagnose and fix the "Killed" / "Killed: 9" crash on the claude CLI caused by bloated session transcripts. Use when claude exits with SIGKILL on startup or on --continue/--resume, on either Linux or macOS, and OS memory looks healthy. Runs a script that archives large old .jsonl transcripts and raises the Node heap limit. --- # Claude CLI transcript bloat fix ## When to use Trigger on any of these: - `claude` prints `Killed` (Linux) or `Killed: 9` (macOS) and exits. - `claude --continue` / `claude --resume` dies before the UI appears. - Same crash reproduces on multiple machines (same user, synced `~/.claude`). - `free -h` / `vm_stat` shows plenty of free RAM — not a system OOM. ## Why it happens `claude` loads the session JSONL into memory and expands it into V8 objects. A 30–40 MB transcript expands to 3–5 GB of heap and either hits Node's default `--max-old-space-size` (~4 GB) or triggers OS memory pressure (Linux OOM killer, macOS Jetsam). Both print a bare `Killed` line with no stack — that's the signature. This is a CLI-side problem, not a server/API problem. It reproduces across machines because the transcripts travel with `~/.claude/projects`. ## Diagnose in 10 seconds ```bash du -sh ~/.claude/projects find ~/.claude/projects -type f -name '*.jsonl' -size +5M -exec du -h {} + | sort -rh | head -10 ``` If you see any single `.jsonl` above ~5 MB — especially 20 MB+ — that's the cause. ## Fix Run the script: ```bash ~/.claude/scripts/fix-claude-bloat.sh ``` Defaults: archive any `.jsonl` >5 MB older than 2 days into `~/.claude/projects-archive/` (preserving structure), and append `NODE_OPTIONS=--max-old-space-size=8192` to the user's shell rc if not already set. Options: ```bash fix-claude-bloat.sh --dry-run # preview only fix-claude-bloat.sh --size 10 --age 7 # only files >10MB older than 7d fix-claude-bloat.sh --heap 12288 # raise heap limit to 12 GB ``` Then open a new shell (or `source ~/.bashrc` / `~/.zshrc`) and retry `claude`. ## Notes - Archive is reversible: `mv ~/.claude/projects-archive/ ~/.claude/projects/` restores a session for `--resume`. - The `--age` guard avoids moving the transcript of a session you're currently in. Default 2 days is conservative; raise it if you're actively working in a long-running session. - On macOS the script writes to `~/.bash_profile` (or `~/.zshrc` for zsh users) instead of `~/.bashrc`, because login shells on macOS don't read `.bashrc`. - Idempotent — safe to re-run on a cron or whenever kills recur.