Home-directory launches trigger broad discovery, read/edit state loss, and premature compaction on simple fixes

Summary

When Claude Code is started from the user's home directory (~) and given a small local bug-fix task (without specifying the exact repo/file path), it can spiral into broad repo discovery, protected-directory errors, tool selection degradation, read/edit state tracking failures, and premature conversation compaction — all for what should be a trivial one-file edit.

Reproduction

1. Start Claude Code from the home directory (~) rather than from inside a repo.
2. Give it a normal local bug-fix prompt without explicitly naming the exact repo or file path.
3. Example task: "fix the CSP iframe bug in my website project"

Observed Behavior

1. Overly broad discovery from home directory

• Claude treats ~ as a project root and performs broad recursive file discovery.
• Search touches protected macOS locations (Photos, Photo Booth libraries, ~/Library, ~/Music, etc.), producing permission failures and timeouts.
• This burns significant context on irrelevant filesystem traversal.

2. Tool selection degradation after discovery failures

• After glob/grep failures on protected directories, Claude falls back to shell-based discovery (find, ls -R, cat) instead of the dedicated Read/Glob/Grep tools.
• Shell-based file reads (cat, head) do not register in Claude's internal file-state tracking, so subsequent Edit calls fail with:

> "File has not been read yet. Read it first before writing to it."

3. Read/Edit state desync → retry loops

• Claude inspects the target file via shell commands, plans the edit, then gets blocked by its own state tracker.
• It then re-reads with the Read tool, re-plans the edit, and retries — sometimes multiple times.
• Each cycle consumes tokens until the conversation hits compaction threshold.

4. Premature compaction on trivial tasks

• The combination of broad discovery output + retry loops + re-reads inflates token usage enough to trigger conversation compaction.
• After compaction, Claude may lose track of prior work and start over, further compounding the issue.

Expected Behavior

• When launched from a non-repo context like ~, Claude Code should treat it as a launcher context, not a project root.
• Discovery should be constrained to likely code roots (e.g., ~/Desktop/Code, ~/repos, ~/projects), not the entire home tree.
• Protected macOS directories (~/Library, ~/Pictures, ~/Movies, ~/Music, ~/Photo Booth Library) should be excluded from automatic discovery.
• File-state tracking should be consistent regardless of how the file content was obtained, or Claude should always use the Read tool before planning edits.
• A simple one-file fix should complete without compaction.

Control Comparison

| Scenario | Result |
|---|---|
| Claude Code started inside the target repo | Completes normally, single read + edit |
| Claude Code started from ~ with exact file path in prompt | Completes normally |
| Claude Code started from ~ with repo name only (no path) | Triggers the described failure cascade |

Root Cause Analysis

This appears to be an interaction between three independent issues:

1. No launcher-context heuristic for ~: The discovery system assumes cwd = project root. Home directories are fundamentally different — they contain many repos, system files, and protected directories. There's no built-in constraint to treat ~ as a launcher rather than a workspace.

1. Tool selection degradation after failures: When the preferred tools (Glob/Grep) fail on protected directories, the fallback to shell commands (find, cat) creates a state tracking gap. Shell-based reads don't register in the file-state tracker that Edit depends on.

1. Read/Edit state tracking is tool-dependent, not file-dependent: The Edit tool's pre-condition ("file must have been read") checks whether the Read tool was used, not whether Claude has seen the file's contents. This means any path through shell commands → Edit will fail, triggering retry loops.

Workarounds (User-Side)

These mitigate but don't fix the underlying issues:

• Add a CLAUDE.md at ~ declaring it a launcher context with an allowlist of code roots (this is what I currently do).
• Always include the exact repo path in the prompt.
• Start Claude Code from inside the target repo instead of ~.

Impact

• Token/cost waste: 5-10x token consumption on trivial tasks due to broad discovery + retry loops.
• Premature compaction: Loses conversation state on tasks that should never approach context limits.
• Privacy concern (minor): Automatic discovery scans personal media directories and surfaces their contents in tool output, even though they're irrelevant to code tasks.
• Reliability: Simple fixes that should take one read + one edit become multi-cycle retry loops.

Environment

• macOS Sequoia 15.5
• Claude Code launched from ~ (not a git repo)
• Multiple code repos in subdirectories (~/Desktop/Code/, ~/repos/, etc.)

Suggested Remediation

1. Launcher-context detection: If cwd is ~ (or another non-repo directory with many subdirectories), treat it as a launcher context. Constrain automatic discovery to common code roots or prompt the user for the target repo.
2. Protected directory exclusion: Skip ~/Library, ~/Pictures, ~/Movies, ~/Music, and other known non-code macOS directories during automatic discovery.
3. File-state tracking fix: Make the Edit pre-condition check file-content-aware rather than tool-call-aware, or enforce that the Read tool is always used before edit planning (not just before edit execution).
4. Graceful degradation: If discovery from ~ produces too many results or permission errors, stop and ask the user to narrow the scope rather than continuing with degraded tool selection.