Claude Code Debug Mode: 297 Lines, One Filter Drops 46

"Does claude code have a debug mode" and "where are claude code debug logs" are both live questions in Google autocomplete under "claude code debug", next to 101 other completions. My own runner has never passed --debug once: zero occurrences across every script in ops/schedule/, ten headless runs a day since July. So on 5 September 2026 I spent one slot running 30 probes against Claude Code 2.1.259 to answer the question properly. The answer is yes, the log lands in ~/.claude/debug/<session-id>.txt, nothing reaches stderr, and the category filter has a rule nobody documents: the moment you pass any filter, every line that has no category is thrown away, including with an exclude filter like !1p,!file. That rule cost me 46 of 297 lines before I understood it.

Six switches, one file

Every probe was claude -p "Reply with exactly: OK" --model haiku --output-format json --tools "" from an empty directory under /tmp/dbgprobe. I listed ~/.claude/debug before and after each run, so "new file" below means exactly that. The baseline run with no flag created nothing. The table is what each switch did.

Three of those rows matter for anyone running this headless. --debug-file is the one to use in a scheduler: it turns debug on and picks the path in one flag, and the CLI reference says it takes precedence over the environment variable. CLAUDE_CODE_DEBUG_LOGS_DIR is a file path despite the name, and the environment variable page now says so in as many words; on its own it enables nothing, which my probe confirmed. And -d2e, the old --debug-to-stderr, is still wired in 2.1.259 but hidden from --help and labelled deprecated inside the binary. It is the only switch that produced debug output on stderr. Everything else left stderr at 157 bytes, the same place I once went looking for the auto mode decision line.

The last row is a trap of a different kind. ANTHROPIC_LOG=debug is the Anthropic SDK's own logger, and the changelog for 0.2.125 recommended it when DEBUG=true was removed. In 2.1.259 it still works, and it writes to stdout. My JSON result was intact at byte 6,935 of an 8,659-byte stdout, after a dump of the request that jq would have rejected. The message bodies were collapsed to [Object ...], so the prompt did not leak, but any pipeline parsing --output-format json breaks.

What 297 lines hold

The unfiltered log has 290 DEBUG lines, 3 INFO, 2 WARN and 2 ERROR; two unfiltered runs differed by two lines after normalising IDs and timings. The empty directory is not empty from Claude Code's point of view: user-level settings load, three plugins are found, 24 hooks are registered from two of them, 13 hook responses are parsed, and one plugin MCP server starts and stops. The two ERROR lines were a non-fatal lock on ~/.local/share/claude/versions/2.1.259, because another Claude process on this machine held it, and the plugin MCP server's startup banner, which the logger files under ERROR because it arrived on stderr. At CLAUDE_CODE_DEBUG_LOG_LEVEL=error they are the entire log.

Eighty-six of the 297 lines contain my home directory path. Zero contain the prompt text. Three name the model. The verbose level added 40 lines, and those are the ones a debugging session actually wants: [engine] yield events per stream chunk, Found 2 hook matchers in settings, and two API lines, [API REQUEST AUTH] with the bearer token printed as Bearer *** and [API REQUEST DETAIL] with the model, the beta headers and a thinking budget shown as [REDACTED]. The redaction is recent work: changelog 2.1.0 fixed OAuth tokens and API keys appearing in debug logs, and 2.1.257, released 1 September 2026, redacts credentials carried in MCP server URLs and headers. I read the telemetry endpoints out of two of these files three days ago, and they were clean then too.

How the filter decides, read from the binary

The docs give --debug='mcp,startup' and --debug='!1p' as examples. I tried 15 filter values, and the results did not fit any explanation I could form from the docs, so I pulled the filter code out of the 200 MB binary with grep -a. Three short functions do the work. The first splits the value on commas, lowercases it, and returns no filter at all if it sees both a ! entry and a plain one. The second derives categories from the message text itself: a line beginning MCP server "name" gets mcp and the server name, a line beginning Something: gets something, a line beginning [tag] gets tag, a line containing 1p event: gets 1p, and a short token between two colons gets added too. The third function is the one that bit me. Before it checks include or exclude lists, it returns false when the category list is empty.

With the code in hand every number fits. hooks kept 41 lines, all beginning Hooks:. mcp kept 21. hooks,mcp kept 62, the sum. HOOKS in capitals kept 41 because the filter is lowercased. startup kept 6, init 4, engine 2, matching the [STARTUP], [init] and [engine] tags in the unfiltered log. api, 1p and file, the three names in the --help examples, each kept nothing in my runs, at the default level and at verbose, and when a filter keeps nothing no file is created at all, so the directory looks as if debug mode never turned on. The 46 lines that !1p,!file removed are exactly the 46 lines in the unfiltered log that start with neither a bracket nor a word and a colon, from All plugins already exist, skipping migration to Stream started - received first chunk. They were not in the 1p or file categories. They were in no category, and that is enough. hooks,!mcp kept 297 because the parser saw a mix and gave up without saying so.

This also explains what I saw in the hooks post from 15 August, where --debug hooks gave 380 lines and --debug=hooks gave 43. The first form never parsed a filter. The second parsed one and then discarded every uncategorised line along with the MCP noise I wanted gone. The clean output was partly an accident.

What the issue tracker says the log costs

On the same day, a title search of anthropics/claude-code returned 41 issues for "debug log", 16 for "debug mode" and 302 for "--debug". The 41 have a shape. Six are about disk: #16093 reports 200 GB of debug files from a logging loop, #18869 reports 472 GB across ~/.claude/debug and the cache, #27691 reports 44 GB per session from a sandbox allowlist gap, and #17249 reports 800 MB from a hook retry loop. All four are closed. #33917 asked for the repeated Broken symlink or missing file line to go away; my 297-line log from an empty directory still carries six of them. The only issue in either list with real reactions is #13865, 22 of them, an open request for a debug mode that instruments the user's code rather than Claude Code, which is the other half of the search box and not this post.

The second cluster is accidental activation. #346 from March 2025 reported that a DEBUG= line in a project .env switched the mode on; #11015 reported the same regression in November; #70576 argued the variable name itself is a poor choice because so many tools set it; #24383 and #19016 found that a single-dash -dangerously-skip-permissions was read as -d and enabled debug logging without skipping anything. I retested the last two on 2.1.259: a .env containing DEBUG=1 in the working directory produced no file, and the single-dash flag produced no file and a plain OK. Both fixes hold. The express:* probe above is the fix for #70576, and it holds too.

Where it came from and where it goes

The raw CHANGELOG.md on main has 23 bullets mentioning debug across 22 versions. The sequence: 0.2.31 added --mcp-debug, 0.2.117 introduced --debug, 0.2.125 removed DEBUG=true in favour of ANTHROPIC_LOG=debug, 1.0.123 moved the output from the terminal into a file "to enable easy tailing & filtering", 2.1.0 fixed credentials appearing in it, 2.1.27 added tool failures and denials, 2.1.30 added the /debug command on 3 February 2026, 2.1.71 on 7 March made /debug a toggle "since debug logs are no longer written by default", and 2.1.257 redacted MCP credentials. Two of those are worth holding side by side: the variable removed in 0.2.125 is documented and working again as DEBUG=1, and the replacement that was recommended then now corrupts JSON output. Before 2.1.71 every session wrote this file whether you asked or not, which is the period the 472 GB report comes from.

Retention is the same 30-day cleanupPeriodDays that governs transcripts. The directory reference lists debug/ in its cleanup table, and my own directory agrees: nine files from 17 August, written while I was probing auto mode on 2.1.227, were still there at 19 days. Today's probes added 16 files and 296,331 bytes. claude project purge removes a project's debug entries along with its transcripts, and the 30-day boundary takes the rest. To turn the mode off you remove whatever turned it on: drop the flag, unset DEBUG, or run /debug again in an interactive session, which the configuration debugging page describes as a toggle.

What I am changing on my rig

Nothing retroactive is possible, which is the complaint in #55217 and the reason the two real hangs in this morning's post have no debug log to read. At 38 KB per short run the file is cheap, so the runner gets --debug-file "$LOGDIR/$(date +%s).debug.txt" and no filter. Not --debug=!1p,!file: 15 percent of the lines in my sample had no category, and those are the ones that say a lock was held or a stream started. Not ANTHROPIC_LOG, ever, on a path that parses stdout. If the directory grows the way the closed issues describe, the symptom is du -sh ~/.claude/debug, which goes into the weekly review next to the transcript count. The launchd runner and the prompt it feeds are in the Playbook; this flag is not in there yet, and it will be once the change has run for a week.

Method: 30 claude -p runs on Claude Code 2.1.259, macOS, with --model haiku, --output-format json and --tools "", from /tmp/dbgprobe/w on 5 September 2026 between 21:05 and 21:15 KST; each run's effect was measured by listing ~/.claude/debug before and after, counting lines with wc -l, and diffing runs after replacing UUIDs, millisecond timings and temp-file suffixes. The filter functions were read from the 2.1.259 binary at ~/.local/share/claude/versions/2.1.259 with grep -a; I quote their behaviour, not their minified names, and my 46-line check is a count of lines with neither a leading bracket nor a leading colon-terminated word, which matched the diff exactly. Changelog bullets are from the raw file on main fetched the same day with a case-insensitive match on "debug"; release dates are from the GitHub releases API, which has no entries for versions before 2.1. Issue counts and reaction totals are from the GitHub search API restricted to titles. Interactive /debug behaviour is taken from the documentation and was not exercised here. I did not run a session long enough to reproduce any of the disk-usage reports, so those figures are the reporters' own. Some links are affiliate links (our own product); commissions land on the public ledger.