Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
feat(learn): write per-project learnings to CLAUDE.local.md by default (#1115)
Focused Instabilityced75e4718b5
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 769aca4cc..cc38c2d36 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -14,6 +14,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0### Features+* **learn:** write per-project learnings to the personal, gitignored `CLAUDE.local.md` by default instead of the team-shared `CLAUDE.md`, matching Claude Code's memory convention so machine-specific paths and tool-discovery byproducts no longer pollute the shared file. Adds a `--target` flag to override the destination (e.g. `--target CLAUDE.md` to opt back into the shared file, or any custom path), and auto-migrates a stale learned-patterns block out of an existing `CLAUDE.md` into `CLAUDE.local.md` with a warning ([#1072](https://github.com/chopratejas/headroom/issues/1072)).* **proxy:** measure and surface rolling and current token throughput metrics (active/wall-clock input, compression, effective forward, and streamed generation) in `headroom perf` CLI and the dashboard ([#959](https://github.com/chopratejas/headroom/issues/959)).* **vibe:** add Mistral Vibe CLI support with `headroom wrap vibe`.* **proxy:** per-project savings breakdown on the dashboard for all wrapped agents — Claude Code, Codex, aider, Copilot, and Cursor ([#802](https://github.com/chopratejas/headroom/issues/802)). `headroom wrap claude`/`codex` tag requests with an `X-Headroom-Project` header (launch-directory name); `wrap aider`/`copilot`/`cursor` — whose clients cannot send custom headers — use a `/p/<name>` base-URL prefix the proxy strips. Savings are aggregated per project (persisted, schema v3 with transparent v2 migration), exposed as `savings.per_project` in `/stats` and `projects` in `/stats-history`, and shown in a Per-Project Savings dashboard table.diff --git a/docs/content/docs/failure-learning.mdx b/docs/content/docs/failure-learning.mdxindex 072dd8929..2dd1f0be2 100644--- a/docs/content/docs/failure-learning.mdx+++ b/docs/content/docs/failure-learning.mdx@@ -11,7 +11,7 @@ description: Offline failure analysis for coding agents. Analyzes past sessions,# See recommendations for current project (dry-run, no changes)headroom learn-# Write recommendations to CLAUDE.md and MEMORY.md+# Write recommendations to CLAUDE.local.md and MEMORY.mdheadroom learn --apply# Analyze a specific project@@ -19,6 +19,9 @@ headroom learn --project ~/my-project --apply# Analyze all projectsheadroom learn --all --apply++# Write to the team-shared CLAUDE.md instead of CLAUDE.local.md+headroom learn --apply --target CLAUDE.md```## Success Correlation@@ -84,10 +87,22 @@ Files that need `offset`/`limit` with Read.| Pattern | Destination | Why ||---------|-------------|-----|-| Environment, paths, search scope, commands, large files | **CLAUDE.md** | Stable project facts, version-controllable |+| Environment, paths, search scope, commands, large files | **CLAUDE.local.md** | Personal facts (machine-specific paths), gitignored by default || Missing paths, retry patterns, permissions | **MEMORY.md** | May change, agent-specific |-CLAUDE.md lives in your project directory. MEMORY.md lives in `~/.claude/projects/*/memory/`.+`CLAUDE.local.md` lives in your project directory. It is the **personal** local+memory file in Claude Code's [memory convention](https://docs.claude.com/en/docs/claude-code/memory)+— meant to be gitignored — so machine-specific learnings (absolute paths,+tool-discovery byproducts) don't pollute the team-shared `CLAUDE.md`. Make sure+`CLAUDE.local.md` is listed in your `.gitignore`. Pass `--target CLAUDE.md` to+opt into the shared file instead, or `--target <path>` for any custom location.+MEMORY.md lives in `~/.claude/projects/*/memory/`.++If an older Headroom version already wrote a learned-patterns block into your+team-shared `CLAUDE.md`, the next `headroom learn --apply` moves it into+`CLAUDE.local.md` and prints a warning so you can review the diff before+committing. If `CLAUDE.md` contained nothing but the Headroom block, it is+removed entirely.## Marker-Based Updates@@ -122,6 +137,8 @@ Options:--project PATH Project directory to analyze (default: current directory)--all Analyze all discovered projects--apply Write recommendations (default: dry-run)+ --target TEXT Context file to write to, Claude Code only (default:+ CLAUDE.local.md). Relative to project root, or absolute.--agent TEXT Agent to analyze (e.g. claude, codex, gemini)--model TEXT LLM model to use for analysis--workers INT Number of parallel workersdiff --git a/headroom/cli/learn.py b/headroom/cli/learn.pyindex 6d5a19981..d1e707ca7 100644--- a/headroom/cli/learn.py+++ b/headroom/cli/learn.py@@ -77,6 +77,14 @@ Use 'auto' (default) to scan all detected agents."""default=False,help="Write recommendations to context/memory files (default: dry-run).",)+ "--target",+ type=str,+ default=None,+ help="Override the context file learnings are written to (Claude Code only). "+ "Path is relative to the project root, or absolute. Defaults to CLAUDE.local.md "+ "(personal, gitignored). Pass CLAUDE.md to write to the team-shared file instead.",+)@click.option("--agent",type=_AgentChoice(),@@ -124,6 +132,7 @@ def learn(project: Path | None,analyze_all: bool,apply: bool,+ target: str | None,agent: str,model: str | None,workers: int | None,@@ -148,6 +157,7 @@ def learn(headroom learn --model gpt-4o # Use GPT-4o for analysisheadroom learn --all # Analyze all projectsheadroom learn --agent codex --all # Analyze all Codex sessions+ headroom learn --target CLAUDE.md # Write to the team-shared file"""import os@@ -200,6 +210,11 @@ def learn(for agent_name, plugin in agent_configs:writer = plugin.create_writer()+ if target is not None:+ if hasattr(writer, "set_context_target"):+ writer.set_context_target(target)+ else:+ click.echo(f"Note: --target is not supported for {agent_name}; ignoring.")all_projects = plugin.discover_projects()if not all_projects:continue@@ -280,6 +295,9 @@ def learn()continue+ for warning in getattr(result, "warnings", None) or []:+ click.echo(f"\n ⚠ {warning}")+for file_path, content in result.content_by_file.items():click.echo(f"\n {'[WOULD WRITE]' if result.dry_run else '[WROTE]'} {file_path}")click.echo(f" {'─' * 50}")diff --git a/headroom/learn/writer.py b/headroom/learn/writer.pyindex ade64a02a..02b643919 100644--- a/headroom/learn/writer.py+++ b/headroom/learn/writer.py@@ -72,6 +72,8 @@ class WriteResult:self.files_written: list[Path] = []self.content_by_file: dict[Path, str] = {}self.dry_run: bool = True+ # Human-readable notices (e.g. legacy CLAUDE.md migration) surfaced by the CLI.+ self.warnings: list[str] = []def add(self, path: Path, content: str) -> None:self.files_written.append(path)@@ -190,13 +192,46 @@ def _merge_into_file(file_path: Path, new_recommendations: list[Recommendation])return section + "\n"+def _strip_marker_block(content: str) -> str:+ """Remove the headroom:learn marker block from text, tidying blank lines.++ Used when migrating a stale block out of the team-shared CLAUDE.md into the+ personal CLAUDE.local.md. Returns "" if nothing but the block remained.+ """+ cleaned = _MARKER_PATTERN.sub("", content)+ cleaned = re.sub(r"\n{3,}", "\n\n", cleaned).strip()+ return cleaned + "\n" if cleaned else ""++# =============================================================================# Claude Code Writer# =============================================================================class ClaudeCodeWriter(ContextWriter):- """Writes learned patterns to CLAUDE.md and MEMORY.md for Claude Code."""+ """Writes learned patterns to CLAUDE.local.md and MEMORY.md for Claude Code.++ Project-level learnings default to ``CLAUDE.local.md`` rather than+ ``CLAUDE.md``: per Claude Code's memory convention ``CLAUDE.md`` is+ team-shared and checked into git, while ``CLAUDE.local.md`` is personal and+ gitignored by default. Learned patterns are personal-by-default (they hold+ machine-specific absolute paths and tool-discovery byproducts), so writing+ them to the shared file pollutes it for teammates (issue #1072).++ Pass an explicit target via :meth:`set_context_target` (CLI ``--target``) to+ override -- e.g. ``CLAUDE.md`` to opt back into the shared file.+ """++ def __init__(self, context_target: str | None = None) -> None:+ # Explicit write target for CONTEXT_FILE recs (overrides the default).+ self._context_target = context_target++ def set_context_target(self, context_target: str | None) -> None:+ """Override where CONTEXT_FILE recommendations are written.++ Accepts a path relative to the project root or an absolute path.+ """+ self._context_target = context_targetdef write(self,@@ -211,12 +246,18 @@ class ClaudeCodeWriter(ContextWriter):memory_recs = [r for r in recommendations if r.target == RecommendationTarget.MEMORY_FILE]if context_recs:- claude_md_path = self._resolve_context_path(project)- full_content = _merge_into_file(claude_md_path, context_recs)- result.add(claude_md_path, full_content)+ target_path = self._resolve_context_path(project)+ # Migrate any stale block left in the team-shared CLAUDE.md by older+ # headroom versions into the new target, then strip it from CLAUDE.md+ # so the shared file is no longer polluted.+ migrated = self._migrate_legacy_block(project, target_path, result, dry_run)+ new_sections = {r.section for r in context_recs}+ merged_recs = context_recs + [r for r in migrated if r.section not in new_sections]+ full_content = _merge_into_file(target_path, merged_recs)+ result.add(target_path, full_content)if not dry_run:- claude_md_path.parent.mkdir(parents=True, exist_ok=True)- claude_md_path.write_text(full_content, encoding="utf-8")+ target_path.parent.mkdir(parents=True, exist_ok=True)+ target_path.write_text(full_content, encoding="utf-8")if memory_recs:memory_path = self._resolve_memory_path(project)@@ -229,13 +270,68 @@ class ClaudeCodeWriter(ContextWriter):return resultdef _resolve_context_path(self, project: ProjectInfo) -> Path:- if project.context_file:- return project.context_file- # If project path is the home directory, write to ~/.claude/CLAUDE.md- # (the global location Claude Code reads) instead of ~/CLAUDE.md+ # Explicit --target wins over every default.+ if self._context_target is not None:+ target = Path(self._context_target).expanduser()+ return target if target.is_absolute() else project.project_path / target+ # The home directory's CLAUDE.md (~/.claude/CLAUDE.md) is the user's+ # personal global memory, not a team-shared file, so keep writing there.if project.project_path == Path.home():return Path.home() / ".claude" / "CLAUDE.md"- return project.project_path / "CLAUDE.md"+ # Project level: default to the gitignored, personal CLAUDE.local.md so+ # we never pollute the team-shared CLAUDE.md (issue #1072).+ return project.project_path / "CLAUDE.local.md"++ def _migrate_legacy_block(+ self,+ project: ProjectInfo,+ target_path: Path,+ result: WriteResult,+ dry_run: bool,+ ) -> list[Recommendation]:+ """Move a stale headroom block out of CLAUDE.md into the new target.++ Only fires for the default project-level case (no explicit --target, not+ the home directory) when CLAUDE.md still carries a marker block and the+ new target doesn't yet own one. Returns the migrated recommendations so+ the caller can carry them forward; records the cleaned CLAUDE.md and a+ warning on ``result``. Honors ``dry_run`` (no writes, warning still set).+ """+ legacy_path = project.project_path / "CLAUDE.md"+ if self._context_target is not None or project.project_path == Path.home():+ return []+ if target_path == legacy_path or not legacy_path.exists():+ return []+ legacy_text = legacy_path.read_text(encoding="utf-8")+ if _MARKER_START not in legacy_text:+ return []+ # If the target already owns a block, it is the source of truth -- don't+ # double-migrate or clobber accumulated learnings.+ if target_path.exists() and _MARKER_START in target_path.read_text(encoding="utf-8"):+ return []++ migrated = _parse_prior_recommendations(legacy_text)+ cleaned = _strip_marker_block(legacy_text)+ gitignore_hint = f" Ensure {target_path.name} is in your .gitignore so it stays personal."+ if cleaned:+ # CLAUDE.md has hand-written content too — keep it, drop only the block.+ result.add(legacy_path, cleaned)+ result.warnings.append(+ f"Moved Headroom learnings out of {legacy_path} into {target_path}: "+ f"CLAUDE.md is team-shared, so personal learnings now live in "+ f"{target_path.name}. Review the diff before committing.{gitignore_hint}"+ )+ if not dry_run:+ legacy_path.write_text(cleaned, encoding="utf-8")+ else:+ # CLAUDE.md held nothing but the Headroom block — remove the husk.+ result.warnings.append(+ f"Removed {legacy_path} (it contained only Headroom learnings) and "+ f"moved them into {target_path}.{gitignore_hint}"+ )+ if not dry_run:+ legacy_path.unlink()+ return migrateddef _resolve_memory_path(self, project: ProjectInfo) -> Path:if project.memory_file:diff --git a/tests/test_cli_learn.py b/tests/test_cli_learn.pyindex a7d6c52d8..b5f58bab9 100644--- a/tests/test_cli_learn.py+++ b/tests/test_cli_learn.py@@ -325,3 +325,82 @@ def test_learn_main_only_flag_threads_to_scanner()assert result.exit_code == 0, result.outputassert plugin.last_include_subagents is False+++class TargetAwareWriter(FakeWriter):+ """A writer that supports --target and surfaces a migration warning."""++ def __init__(self) -> None:+ super().__init__()+ self.context_target: str | None = None++ def set_context_target(self, target: str | None) -> None:+ self.context_target = target++ def write(self, recommendations, project, dry_run: bool): # noqa: ANN001, ANN201+ self.calls.append((recommendations, project, dry_run))+ return SimpleNamespace(+ dry_run=dry_run,+ content_by_file={+ Path(project.project_path) / "CLAUDE.local.md": "<!-- headroom -->\nRule 1"+ },+ warnings=["Moved Headroom learnings out of CLAUDE.md into CLAUDE.local.md."],+ )+++def test_learn_target_threads_to_writer_and_prints_warnings(+ monkeypatch: pytest.MonkeyPatch, runner: CliRunner, tmp_path: Path+) -> None:+ project_path = tmp_path / "proj"+ project_path.mkdir()+ proj = SimpleNamespace(name="proj", project_path=project_path)+ plugin = FakePlugin("claude", "Claude Code", [proj])+ plugin.writer = TargetAwareWriter()++ monkeypatch.setattr("headroom.learn.analyzer._detect_default_model", lambda: "gpt-4o")+ monkeypatch.setattr("headroom.learn.registry.get_plugin", lambda name: plugin)+ monkeypatch.setattr("headroom.learn.analyzer.SessionAnalyzer", FakeAnalyzer)++ result = runner.invoke(+ main,+ [+ "learn",+ "--agent",+ "claude",+ "--project",+ str(project_path),+ "--apply",+ "--target",+ "CLAUDE.md",+ ],+ catch_exceptions=False,+ )++ assert result.exit_code == 0, result.output+ # --target is threaded into the writer...+ assert plugin.writer.context_target == "CLAUDE.md"+ # ...and the writer's warnings are surfaced to the user.+ assert "Moved Headroom learnings" in result.output+++def test_learn_target_ignored_for_unsupported_agent(+ monkeypatch: pytest.MonkeyPatch, runner: CliRunner, tmp_path: Path+) -> None:+ project_path = tmp_path / "proj"+ project_path.mkdir()+ proj = SimpleNamespace(name="proj", project_path=project_path)+ # FakePlugin's FakeWriter has no set_context_target, so --target is unsupported.+ plugin = FakePlugin("codex", "Codex", [proj])++ monkeypatch.setattr("headroom.learn.analyzer._detect_default_model", lambda: "gpt-4o")+ monkeypatch.setattr("headroom.learn.registry.get_plugin", lambda name: plugin)+ monkeypatch.setattr("headroom.learn.analyzer.SessionAnalyzer", FakeAnalyzer)++ result = runner.invoke(+ main,+ ["learn", "--agent", "codex", "--project", str(project_path), "--target", "CLAUDE.md"],+ catch_exceptions=False,+ )++ assert result.exit_code == 0, result.output+ assert "Note: --target is not supported for codex" in result.outputdiff --git a/tests/test_learn/test_integration.py b/tests/test_learn/test_integration.pyindex 1964564e4..c1b21215c 100644--- a/tests/test_learn/test_integration.py+++ b/tests/test_learn/test_integration.py@@ -83,11 +83,11 @@ class TestIdempotency:writer = ClaudeCodeWriter()# First writewriter.write(recs, proj, dry_run=False)- first_content = (tmp_path / "CLAUDE.md").read_text()+ first_content = (tmp_path / "CLAUDE.local.md").read_text()# Second write (same recs)writer.write(recs, proj, dry_run=False)- second_content = (tmp_path / "CLAUDE.md").read_text()+ second_content = (tmp_path / "CLAUDE.local.md").read_text()# Content should be identical (replaced, not appended)assert first_content == second_content@@ -216,7 +216,7 @@ class TestClaudeCodeIntegration:assert write_result.dry_run is Truefor fp in write_result.files_written:- assert "CLAUDE.md" in fp.name or "MEMORY.md" in fp.name+ assert "CLAUDE" in fp.name or "MEMORY" in fp.nameclass TestDecodeProjectPath:diff --git a/tests/test_learn/test_writer.py b/tests/test_learn/test_writer.pyindex 8e4ef956a..ce451a80d 100644--- a/tests/test_learn/test_writer.py+++ b/tests/test_learn/test_writer.py@@ -47,10 +47,12 @@ class TestClaudeCodeWriter:assert result.dry_run is Trueassert len(result.files_written) == 1# File should NOT exist (dry run)- claude_md = proj.project_path / "CLAUDE.md"- assert not claude_md.exists()+ claude_local = proj.project_path / "CLAUDE.local.md"+ assert not claude_local.exists()+ # Default target is the personal CLAUDE.local.md, never the shared CLAUDE.md+ assert result.files_written[0].name == "CLAUDE.local.md"- def test_apply_writes_claude_md(self, tmp_path):+ def test_apply_writes_claude_local_md(self, tmp_path):proj = _project(tmp_path)writer = ClaudeCodeWriter()recs = [_rec(RecommendationTarget.CONTEXT_FILE, "Environment", "- Use `uv run python`")]@@ -58,12 +60,15 @@ class TestClaudeCodeWriter:result = writer.write(recs, proj, dry_run=False)assert result.dry_run is False- claude_md = proj.project_path / "CLAUDE.md"- assert claude_md.exists()- content = claude_md.read_text()+ # Learnings go to the personal, gitignored CLAUDE.local.md by default...+ claude_local = proj.project_path / "CLAUDE.local.md"+ assert claude_local.exists()+ content = claude_local.read_text()assert "uv run python" in contentassert _MARKER_START in contentassert _MARKER_END in content+ # ...and never touch the team-shared CLAUDE.md.+ assert not (proj.project_path / "CLAUDE.md").exists()def test_apply_writes_memory_md(self, tmp_path):proj = _project(tmp_path)@@ -76,24 +81,26 @@ class TestClaudeCodeWriter:assert memory_md.exists()assert "Don't retry globs" in memory_md.read_text()- def test_preserves_existing_claude_md_content(self, tmp_path):+ def test_hand_written_claude_md_left_untouched(self, tmp_path):proj = _project(tmp_path)claude_md = proj.project_path / "CLAUDE.md"- claude_md.write_text("# My Project\n\nExisting instructions here.\n")+ original = "# My Project\n\nExisting instructions here.\n"+ claude_md.write_text(original)writer = ClaudeCodeWriter()recs = [_rec(RecommendationTarget.CONTEXT_FILE, "Environment", "- Use uv")]writer.write(recs, proj, dry_run=False)- content = claude_md.read_text()- assert "My Project" in content- assert "Existing instructions here" in content- assert "Use uv" in content+ # A hand-written CLAUDE.md with no headroom block is left exactly as-is.+ assert claude_md.read_text() == original+ # Learnings land in the personal CLAUDE.local.md instead.+ local_content = (proj.project_path / "CLAUDE.local.md").read_text()+ assert "Use uv" in local_contentdef test_carries_forward_prior_sections_not_resurfaced(self, tmp_path):"""Re-running learn must not drop prior sections that the new run didn't re-surface."""proj = _project(tmp_path)- claude_md = proj.project_path / "CLAUDE.md"+ claude_md = proj.project_path / "CLAUDE.local.md"prior_block = (f"# My Project\n\n{_MARKER_START}\n""## Headroom Learned Patterns\n"@@ -129,7 +136,7 @@ class TestClaudeCodeWriter:def test_new_run_overrides_same_named_prior_section(self, tmp_path):"""When a section appears in both prior and new, the new run wins."""proj = _project(tmp_path)- claude_md = proj.project_path / "CLAUDE.md"+ claude_md = proj.project_path / "CLAUDE.local.md"prior_block = (f"{_MARKER_START}\n""## Headroom Learned Patterns\n"@@ -203,7 +210,7 @@ class TestClaudeCodeWriter:def test_section_without_tokens_annotation_round_trips(self, tmp_path):"""Prior sections emitted without a tokens annotation must still carry forward cleanly."""proj = _project(tmp_path)- claude_md = proj.project_path / "CLAUDE.md"+ claude_md = proj.project_path / "CLAUDE.local.md"claude_md.write_text(f"{_MARKER_START}\n""## Headroom Learned Patterns\n"@@ -240,6 +247,199 @@ class TestClaudeCodeWriter:assert "New pattern" in content+def _legacy_block(section: str, body: str) -> str:+ return (+ f"# My Project\n\nExisting instructions.\n\n{_MARKER_START}\n"+ "## Headroom Learned Patterns\n"+ "*Auto-generated by `headroom learn` on 2026-01-01 — do not edit manually*\n\n"+ f"### {section}\n{body}\n\n"+ f"{_MARKER_END}\n"+ )+++class TestContextTargetOverride:+ """--target / set_context_target controls where CONTEXT_FILE recs are written."""++ def test_target_override_relative_path(self, tmp_path):+ proj = _project(tmp_path)+ writer = ClaudeCodeWriter()+ writer.set_context_target("CLAUDE.md")+ recs = [_rec(RecommendationTarget.CONTEXT_FILE, "Environment", "- Use uv")]+ writer.write(recs, proj, dry_run=False)++ # Explicit target opts back into the team-shared CLAUDE.md.+ assert (proj.project_path / "CLAUDE.md").exists()+ assert "Use uv" in (proj.project_path / "CLAUDE.md").read_text()+ assert not (proj.project_path / "CLAUDE.local.md").exists()++ def test_target_override_via_constructor(self, tmp_path):+ proj = _project(tmp_path)+ writer = ClaudeCodeWriter(context_target="docs/LEARNINGS.md")+ recs = [_rec(RecommendationTarget.CONTEXT_FILE, "Environment", "- Use uv")]+ writer.write(recs, proj, dry_run=False)++ target = proj.project_path / "docs" / "LEARNINGS.md"+ assert target.exists()+ assert "Use uv" in target.read_text()++ def test_target_absolute_path(self, tmp_path):+ proj = _project(tmp_path)+ abs_target = tmp_path / "elsewhere" / "NOTES.md"+ writer = ClaudeCodeWriter(context_target=str(abs_target))+ recs = [_rec(RecommendationTarget.CONTEXT_FILE, "Environment", "- Use uv")]+ writer.write(recs, proj, dry_run=False)++ assert abs_target.exists()+ assert "Use uv" in abs_target.read_text()+++class TestLegacyClaudeMdMigration:+ """A stale headroom block in the shared CLAUDE.md migrates to CLAUDE.local.md."""++ def test_migrates_block_and_strips_legacy(self, tmp_path):+ proj = _project(tmp_path)+ claude_md = proj.project_path / "CLAUDE.md"+ claude_md.write_text(_legacy_block("Build Commands", "- cargo check from src-tauri/"))++ writer = ClaudeCodeWriter()+ recs = [_rec(RecommendationTarget.CONTEXT_FILE, "Environment", "- Use uv")]+ result = writer.write(recs, proj, dry_run=False)++ # Hand-written content stays in CLAUDE.md; the headroom block is gone.+ legacy = claude_md.read_text()+ assert "Existing instructions." in legacy+ assert _MARKER_START not in legacy+ assert "Build Commands" not in legacy++ # CLAUDE.local.md now owns the migrated section AND the new one.+ local = (proj.project_path / "CLAUDE.local.md").read_text()+ assert "### Build Commands" in local+ assert "cargo check from src-tauri/" in local+ assert "### Environment" in local+ assert "Use uv" in local+ assert local.count(_MARKER_START) == 1++ # The migration is surfaced to the user.+ assert any("CLAUDE.md" in w for w in result.warnings)++ def test_block_only_claude_md_is_removed(self, tmp_path):+ proj = _project(tmp_path)+ claude_md = proj.project_path / "CLAUDE.md"+ # CLAUDE.md holds nothing but the Headroom block (no hand-written content).+ claude_md.write_text(+ f"{_MARKER_START}\n## Headroom Learned Patterns\n\n"+ "### Build Commands\n- cargo check\n\n"+ f"{_MARKER_END}\n"+ )++ writer = ClaudeCodeWriter()+ recs = [_rec(RecommendationTarget.CONTEXT_FILE, "Environment", "- Use uv")]+ result = writer.write(recs, proj, dry_run=False)++ # The empty husk is deleted rather than left behind as an empty file.+ assert not claude_md.exists()+ local = (proj.project_path / "CLAUDE.local.md").read_text()+ assert "### Build Commands" in local+ assert "### Environment" in local+ assert any("Removed" in w for w in result.warnings)++ def test_dry_run_block_only_claude_md_not_removed(self, tmp_path):+ proj = _project(tmp_path)+ claude_md = proj.project_path / "CLAUDE.md"+ original = (+ f"{_MARKER_START}\n## Headroom Learned Patterns\n\n"+ "### Build Commands\n- cargo check\n\n"+ f"{_MARKER_END}\n"+ )+ claude_md.write_text(original)++ writer = ClaudeCodeWriter()+ recs = [_rec(RecommendationTarget.CONTEXT_FILE, "Environment", "- Use uv")]+ result = writer.write(recs, proj, dry_run=True)++ # Dry run leaves the file on disk but still previews the removal.+ assert claude_md.read_text() == original+ assert any("Removed" in w for w in result.warnings)++ def test_dry_run_migration_writes_nothing(self, tmp_path):+ proj = _project(tmp_path)+ claude_md = proj.project_path / "CLAUDE.md"+ original = _legacy_block("Build Commands", "- cargo check")+ claude_md.write_text(original)++ writer = ClaudeCodeWriter()+ recs = [_rec(RecommendationTarget.CONTEXT_FILE, "Environment", "- Use uv")]+ result = writer.write(recs, proj, dry_run=True)++ # Nothing written on disk, but the warning still fires for the preview.+ assert claude_md.read_text() == original+ assert not (proj.project_path / "CLAUDE.local.md").exists()+ assert any("CLAUDE.md" in w for w in result.warnings)++ def test_no_migration_when_local_already_owns_block(self, tmp_path):+ proj = _project(tmp_path)+ claude_md = proj.project_path / "CLAUDE.md"+ legacy = _legacy_block("Build Commands", "- cargo check")+ claude_md.write_text(legacy)+ local_md = proj.project_path / "CLAUDE.local.md"+ local_md.write_text(+ f"{_MARKER_START}\n## Headroom Learned Patterns\n\n"+ "### Environment\n- prior local note\n\n"+ f"{_MARKER_END}\n"+ )++ writer = ClaudeCodeWriter()+ recs = [_rec(RecommendationTarget.CONTEXT_FILE, "Environment", "- fresh note")]+ result = writer.write(recs, proj, dry_run=False)++ # CLAUDE.md is left untouched (local is already the source of truth).+ assert claude_md.read_text() == legacy+ assert not result.warnings+ local = local_md.read_text()+ assert "fresh note" in local+ assert "prior local note" not in local++ def test_target_override_skips_migration(self, tmp_path):+ proj = _project(tmp_path)+ claude_md = proj.project_path / "CLAUDE.md"+ legacy = _legacy_block("Build Commands", "- cargo check")+ claude_md.write_text(legacy)++ writer = ClaudeCodeWriter()+ writer.set_context_target("CLAUDE.md")+ recs = [_rec(RecommendationTarget.CONTEXT_FILE, "Environment", "- Use uv")]+ result = writer.write(recs, proj, dry_run=False)++ # Explicit CLAUDE.md target merges in place, no migration warning.+ assert not result.warnings+ content = claude_md.read_text()+ assert "### Environment" in content+ assert "### Build Commands" in content+++class TestHomeDirectoryContext:+ """The home directory keeps writing to ~/.claude/CLAUDE.md (personal global memory)."""++ def test_home_dir_writes_global_claude_md(self, tmp_path, monkeypatch):+ fake_home = tmp_path / "home"+ fake_home.mkdir()+ monkeypatch.setattr(Path, "home", classmethod(lambda cls: fake_home))++ proj = ProjectInfo(+ name="home",+ project_path=fake_home,+ data_path=tmp_path / "data",+ )+ writer = ClaudeCodeWriter()+ recs = [_rec(RecommendationTarget.CONTEXT_FILE, "Environment", "- Use uv")]+ writer.write(recs, proj, dry_run=False)++ global_md = fake_home / ".claude" / "CLAUDE.md"+ assert global_md.exists()+ assert "Use uv" in global_md.read_text()+ assert not (fake_home / "CLAUDE.local.md").exists()++class TestParsePriorRecommendations:"""Direct coverage for _parse_prior_recommendations edge cases."""