Skip to content

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.

feat(learn): write per-project learnings to CLAUDE.local.md by default (#1115)

Focused Instabilityced75e4718b5
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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.mdx
index 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.md
headroom learn --apply
# Analyze a specific project
@@ -19,6 +19,9 @@ headroom learn --project ~/my-project --apply
# Analyze all projects
headroom 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 workers
diff --git a/headroom/cli/learn.py b/headroom/cli/learn.py
index 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 analysis
headroom learn --all # Analyze all projects
headroom 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.py
index 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_target
def 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 result
def _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 migrated
def _resolve_memory_path(self, project: ProjectInfo) -> Path:
if project.memory_file:
diff --git a/tests/test_cli_learn.py b/tests/test_cli_learn.py
index 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.output
assert 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.output
diff --git a/tests/test_learn/test_integration.py b/tests/test_learn/test_integration.py
index 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 write
writer.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 True
for 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.name
class TestDecodeProjectPath:
diff --git a/tests/test_learn/test_writer.py b/tests/test_learn/test_writer.py
index 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 True
assert 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 content
assert _MARKER_START in content
assert _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_content
def 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."""