Make Claude stop using heredoc to save tokens - Add this to CLAUDE.md if you're on Windows.
I noticed that Claude Code kept failing certain commands because of tool failures, when editing or writing new files. Session analysis found that this is because it uses it's command line/bash tool to do things that it actually already has built-in tools for! If you add this section to your global CLAUDE.md file, it allows CLAUDE to save nearly 80% of the tokens of those tasks.
## Shell
- **Backslashes are unreliable in Bash tool commands.** The Bash tool strips one level of
backslash escaping from the command string before the shell ever parses it: `\\` arrives
as `\`, `\\\\` as `\\`. Single quotes and quoted heredocs (`<<'EOF'`) do **not** protect
against it — the collapse happens upstream of bash, so it is not a shell, `.bashrc`, or
Git Bash issue. Everything else passes through intact: `$VAR`, backticks, tabs, and
quotes are all fine. (Measured 2026-09-05; the PowerShell tool preserves the identical
payload byte-for-byte, which is what isolates it to the Bash tool.)
- **The failure is silent.** The command succeeds and the output looks plausible, so a
corrupted `"\n"` written into generated source surfaces much later as an
unrelated-looking syntax or runtime error.
- **Use Write for new files or full rewrites, Edit for targeted changes, Read for
reading.** They handle content verbatim. This is the default for anything file-shaped.
- For shell work that genuinely needs backslashes (Windows paths, regex, JSON payloads),
use the **PowerShell** tool — it preserves them exactly.
- Do not use heredocs (`cat <<'EOF' > file`) to create or modify files — not because
heredocs are special, but because they are the usual way backslash-bearing content
reaches Bash.
- Same for multi-line strings passed to other commands (commit messages, JSON payloads):
write the content to a file with Write, then point the command at that file.
- Last resort inside Bash: double every backslash (emit `2N` to get `N`). Verified to
work, but silent when wrong — never for content that lands in a file.
Posted Sep 6, 2026, 12:36 AM UTC
13