[BUG] @-mention in CLAUDE.md silently reads referenced file at startup, causing TUI deadlock when file is binary (especially in Docker)

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

What's Wrong?

An @-mention reference in CLAUDE.md (e.g., @bin/tailwindcss) causes Claude Code to read the referenced file during TUI startup. When the referenced file is a large binary (116MB standalone Tailwind CSS binary in this case), this causes the TUI to deadlock — the Ink renderer's write buffer fills up faster than the PTY can consume, blocking the Node.js event loop and making the entire interface permanently unresponsive.

The issue is especially severe inside Docker containers, where PTY buffer sizes are more constrained, but it could affect any environment where a large binary is @-mentioned.

Root cause

The @ symbol in CLAUDE.md is interpreted as a file reference (the same @-mention feature used in the chat input). During startup, Claude Code resolves and reads the file contents. When the file is a large binary, this triggers:

1. A 116MB read() syscall (confirmed via strace: read(28, "\177ELF...", 121014727) = 121014727)
2. The Ink TUI renderer attempting to process/render with this data in memory
3. A PTY write buffer deadlock: High write ratio: blit=0, write=3358 (100.0% writes) — 100% full-screen rewrites with 0% incremental blits
4. The TUI becomes completely unresponsive — no keyboard input, no Ctrl+C, requires force-kill

Why this is a bug (not user error)

1. No documentation states that @ in CLAUDE.md triggers file resolution. Users naturally write @path/to/file as shorthand in documentation.
2. Silent failure — no error, no warning, no timeout. The process appears frozen with no indication of what's wrong.
3. The file reference should not read binary files at startup regardless — it should check file type/size first.
4. Environment-dependent — works fine on the WSL host (larger PTY buffers) but deadlocks in Docker, making it extremely difficult to diagnose.

What Should Happen?

1. @-mentions in CLAUDE.md should either not resolve file references at startup, or:
2. Skip binary files (check magic bytes / MIME type)
3. Enforce a size limit (e.g., skip files > 1MB)
4. At minimum, log a warning: "Skipping @bin/tailwindcss: file is 116MB binary"

Error Messages/Logs

Steps to Reproduce

1. Create a project with a large binary file (e.g., standalone Tailwind CSS, ~116MB):

``
mkdir -p bin
curl -sSLo bin/tailwindcss https://github.com/tailwindlabs/tailwindcss/releases/latest/download/tailwindcss-linux-x64
chmod +x bin/tailwindcss
``

1. Add an @-mention to CLAUDE.md:

```markdown
## Tools

• Tailwind CSS CLI - CSS compilation (standalone binary) @bin/tailwindcss

```

1. Run Claude Code inside a Docker container:

``bash
docker run -it -v $(pwd):/app -w /app node:20 bash
npm install -g @anthropic-ai/claude-code
claude
``

1. Observe: TUI renders briefly, then becomes completely unresponsive.

1. Fix: Change @bin/tailwindcss to ` bin/tailwindcss ` — Claude Code works immediately.

Claude Model

None

Is this a regression?

Yes, this worked in a previous version

Last Working Version

_No response_

Claude Code Version

2.1.34

Platform

Anthropic API

Operating System

Ubuntu/Debian Linux

Terminal/Shell

VS Code integrated terminal

Additional Information

_No response_