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
fix(learn): merge git worktree sessions into the repo's project (#3854)
gglucass3fdf18ededa1
diff --git a/headroom/cli/learn.py b/headroom/cli/learn.pyindex b3722184b..da1303816 100644--- a/headroom/cli/learn.py+++ b/headroom/cli/learn.py@@ -13,6 +13,16 @@ if TYPE_CHECKING:from .main import main+def _projects_at(projects: list[Any], path: Path) -> list[Any]:+ """Projects checked out at ``path``, including linked worktrees merged into one.++ ``getattr``: external plugins may return duck-typed projects without the field.+ """+ return [+ p for p in projects if p.project_path == path or path in getattr(p, "worktree_paths", ())+ ]++class _AgentChoice(click.ParamType):"""Dynamic Click type that validates against the plugin registry."""@@ -257,15 +267,15 @@ def learn(targets = all_projectselif project:resolved = project.resolve()- targets = [p for p in all_projects if p.project_path == resolved]+ targets = _projects_at(all_projects, resolved)if not targets:continueelse:cwd = Path.cwd().resolve()- targets = [p for p in all_projects if p.project_path == cwd]+ targets = _projects_at(all_projects, cwd)if not targets:for parent in cwd.parents:- targets = [p for p in all_projects if p.project_path == parent]+ targets = _projects_at(all_projects, parent)if targets:breakif not targets and len(agent_configs) == 1:@@ -496,13 +506,13 @@ def _run_verbosity(targets = all_projectselif project:resolved = project.resolve()- targets = [p for p in all_projects if p.project_path == resolved]+ targets = _projects_at(all_projects, resolved)else:cwd = Path.cwd().resolve()- targets = [p for p in all_projects if p.project_path == cwd]+ targets = _projects_at(all_projects, cwd)if not targets:for parent in cwd.parents:- targets = [p for p in all_projects if p.project_path == parent]+ targets = _projects_at(all_projects, parent)if targets:breakif not targets:@@ -521,7 +531,9 @@ def _run_verbosity(analyzed_count = 0for proj in targets:- session_paths = sorted(proj.data_path.glob("*.jsonl"))+ session_paths = sorted(+ f for d in (proj.data_path, *proj.extra_data_paths) for f in d.glob("*.jsonl")+ )if not session_paths:continueprofile, baseline = analyze(session_paths, str(proj.project_path), llm_judge=judge)diff --git a/headroom/learn/models.py b/headroom/learn/models.pyindex 057a4ea6d..c669d143f 100644--- a/headroom/learn/models.py+++ b/headroom/learn/models.py@@ -134,6 +134,10 @@ class ProjectInfo:data_path: Path # Where conversation logs are storedcontext_file: Path | None = None # CLAUDE.md / .cursorrules / AGENTS.mdmemory_file: Path | None = None # MEMORY.md or equivalent+ # Linked git worktrees folded into this project: their checkouts, and the+ # extra folders their conversation logs are stored in.+ worktree_paths: list[Path] = field(default_factory=list)+ extra_data_paths: list[Path] = field(default_factory=list)# =============================================================================diff --git a/headroom/learn/plugins/claude.py b/headroom/learn/plugins/claude.pyindex b4dd1c694..9a74c8a69 100644--- a/headroom/learn/plugins/claude.py+++ b/headroom/learn/plugins/claude.py@@ -5,6 +5,7 @@ Reads conversation logs from ~/.claude/projects/ (JSONL format).from __future__ import annotations+import dataclassesimport jsonimport loggingimport re@@ -115,7 +116,70 @@ class ClaudeCodePlugin(LearnPlugin, ConversationScanner):))- return projects+ return self._merge_worktrees(projects)++ def _merge_worktrees(self, projects: list[ProjectInfo]) -> list[ProjectInfo]:+ """Fold each linked git worktree into the project of its main checkout.++ Claude Code files every working directory's sessions under its own+ folder, so each worktree (a Conductor workspace, ``.claude/worktrees/*``)+ would otherwise be its own project: a handful of sessions, too thin to+ cross a pattern threshold, with learnings written into a checkout that+ is deleted with the workspace. The merged project keeps the main+ checkout's path and memory folder, which Claude Code's auto-memory+ shares across a repo's worktrees, and scans every member's sessions.+ A worktree whose checkout is gone has nothing to resolve it from and+ stays separate.+ """+ groups: dict[Path, list[tuple[ProjectInfo, Path | None]]] = {}+ for project in projects:+ root = _main_worktree_root(project.project_path)+ try:+ key = root or project.project_path.resolve()+ except OSError:+ key = project.project_path+ groups.setdefault(key, []).append((project, root))++ merged: list[ProjectInfo] = []+ for key, members in groups.items():+ if all(root is None for _, root in members):+ merged.extend(project for project, _ in members)+ continue+ main = next((project for project, root in members if root is None), None)+ # A repo worked on only through worktrees has no session folder of+ # its own; use the one Claude Code would give its main checkout.+ data_path = (+ main.data_path+ if main+ else self.projects_dir / re.sub(r"[^A-Za-z0-9]", "-", str(key))+ )+ project_path = main.project_path if main else key+ claude_md = project_path / "CLAUDE.md"+ memory_file = data_path / "memory" / "MEMORY.md"+ merged.append(+ dataclasses.replace(+ main or members[0][0],+ name=_project_display_name(project_path, data_path.name),+ project_path=project_path,+ data_path=data_path,+ context_file=claude_md if _path_exists(claude_md) else None,+ memory_file=memory_file if _path_exists(memory_file) else None,+ # The session folder can be a subdirectory of the checkout;+ # record the checkout root too so selecting the worktree+ # itself, or a path elsewhere in it, still finds this project.+ worktree_paths=list(+ dict.fromkeys(+ path+ for p, root in members+ if root is not None+ for path in (p.project_path, _checkout_root(p.project_path))+ if path is not None+ )+ ),+ extra_data_paths=[p.data_path for p, _ in members if p is not main],+ )+ )+ return merged@staticmethoddef _project_path_from_session_cwd(jsonl_files: list[Path]) -> Path | None:@@ -150,15 +214,16 @@ class ClaudeCodePlugin(LearnPlugin, ConversationScanner):by default we descend into them. Pass ``include_subagents=False`` torestrict to top-level main sessions only."""- data_path = project.data_path- if include_subagents:- jsonl_files = sorted(data_path.rglob("*.jsonl"))- else:- jsonl_files = sorted(data_path.glob("*.jsonl"))- if not jsonl_files:+ file_sources: list[tuple[Path, str]] = []+ for data_path in (project.data_path, *project.extra_data_paths):+ if include_subagents:+ jsonl_files = sorted(data_path.rglob("*.jsonl"))+ else:+ jsonl_files = sorted(data_path.glob("*.jsonl"))+ file_sources.extend((f, self._classify_source(data_path, f)) for f in jsonl_files)+ if not file_sources:return []-- file_sources = [(f, self._classify_source(data_path, f)) for f in jsonl_files]+ jsonl_files = [f for f, _ in file_sources]if max_workers <= 1 or len(jsonl_files) <= 1:return [@@ -436,6 +501,41 @@ def _decode_project_path(escaped_name: str) -> Path | None:return None+def _checkout_root(path: Path) -> Path | None:+ """The nearest directory at or above ``path`` holding a ``.git`` entry."""+ try:+ return next((d for d in (path, *path.parents) if _path_exists(d / ".git")), None)+ except OSError:+ return None+++def _main_worktree_root(path: Path) -> Path | None:+ """Return the main checkout of the linked git worktree ``path`` is in.++ Returns None for a main checkout, a submodule, a bare repo, or anything+ outside git. Reads git's own pointer files rather than running git.+ """+ # A relative path (a Windows path decoded on POSIX) would walk up into the+ # process's working directory and match whatever repo that sits in.+ if not path.is_absolute():+ return None+ try:+ checkout = _checkout_root(path)+ if checkout is None:+ return None+ # A main checkout's .git is a directory, so this read fails there.+ pointer = (checkout / ".git").read_text(encoding="utf-8").strip()+ if not pointer.startswith("gitdir:"):+ return None+ gitdir = checkout / pointer[len("gitdir:") :].strip()+ # Only a linked worktree's gitdir has `commondir` (a submodule's does not).+ common = (gitdir / (gitdir / "commondir").read_text(encoding="utf-8").strip()).resolve()+ except (OSError, UnicodeDecodeError):+ return None+ # A bare repo has no checkout to merge into.+ return common.parent if common.name == ".git" else None++def _project_display_name(project_path: Path, fallback: str) -> str:"""Return a human project name for POSIX and Windows-style decoded paths."""rendered = str(project_path)diff --git a/headroom/memory/traffic_learner.py b/headroom/memory/traffic_learner.pyindex ba7a3edbc..5818abce7 100644--- a/headroom/memory/traffic_learner.py+++ b/headroom/memory/traffic_learner.py@@ -1729,12 +1729,17 @@ def _project_for_pattern(pattern: ExtractedPattern, roots: list[ProjectInfo]) ->if not candidates:return None+ # A path inside a worktree folded into a project belongs to that project.# Longest root first — most specific wins- roots_sorted = sorted(roots, key=lambda p: len(str(p.project_path)), reverse=True)+ roots_sorted = sorted(+ ((path, root) for root in roots for path in (root.project_path, *root.worktree_paths)),+ key=lambda item: len(str(item[0])),+ reverse=True,+ )for cand in candidates:- for root in roots_sorted:- root_str = str(root.project_path).rstrip("/\\")+ for path, root in roots_sorted:+ root_str = str(path).rstrip("/\\")if not root_str:continueif (diff --git a/tests/test_cli_learn.py b/tests/test_cli_learn.pyindex f4341417a..8ebc7e858 100644--- a/tests/test_cli_learn.py+++ b/tests/test_cli_learn.py@@ -208,6 +208,34 @@ def test_learn_project_lookup_and_apply_flow(assert plugin.writer.calls[0][2] is False[email protected]("from_cwd", [False, True])+def test_learn_selects_the_project_a_worktree_was_merged_into(+ monkeypatch: pytest.MonkeyPatch, runner: CliRunner, tmp_path: Path, from_cwd: bool+) -> None:+ main_checkout, worktree = tmp_path / "repo", tmp_path / "workspaces" / "ws"+ (worktree / "src").mkdir(parents=True)+ worktree = worktree.resolve()+ merged = SimpleNamespace(+ name="repo", project_path=main_checkout, worktree_paths=[worktree], extra_data_paths=[]+ )+ plugin = FakePlugin("claude", "Claude Code", [merged])+ analyzer = FakeAnalyzer()++ 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", lambda model=None: analyzer)++ args = ["learn", "--agent", "claude"]+ if from_cwd:+ monkeypatch.chdir(worktree / "src")+ else:+ args += ["--project", str(worktree)]+ result = runner.invoke(main, args, catch_exceptions=False)++ assert result.exit_code == 0, result.output+ assert [call[0] for call in plugin.scan_calls] == [merged]++class ProgressEchoingAnalyzer(FakeAnalyzer):def analyze(self, project, sessions, on_progress=None): # noqa: ANN001, ANN201self.calls.append((project, sessions))@@ -263,8 +291,12 @@ def test_verbosity_all_apply_aggregates_baselines_across_projects(for d in (proj_a_dir, proj_b_dir):d.mkdir()(d / "s.jsonl").write_text("{}")- proj_a = SimpleNamespace(name="a", project_path=tmp_path / "src-a", data_path=proj_a_dir)- proj_b = SimpleNamespace(name="b", project_path=tmp_path / "src-b", data_path=proj_b_dir)+ proj_a = SimpleNamespace(+ name="a", project_path=tmp_path / "src-a", data_path=proj_a_dir, extra_data_paths=[]+ )+ proj_b = SimpleNamespace(+ name="b", project_path=tmp_path / "src-b", data_path=proj_b_dir, extra_data_paths=[]+ )plugin = FakePlugin("claude", "Claude Code", [proj_a, proj_b])# Per-project synthetic baselines. Project A has more samples, so its leveldiff --git a/tests/test_learn/test_worktree_merge.py b/tests/test_learn/test_worktree_merge.pynew file mode 100644index 000000000..be351f012--- /dev/null+++ b/tests/test_learn/test_worktree_merge.py@@ -0,0 +1,151 @@+"""A linked git worktree's sessions belong to its repo's learn project.++Claude Code files each working directory's sessions under its own+``~/.claude/projects`` folder, so a worktree (a Conductor workspace,+``.claude/worktrees/*``) used to surface as its own project.+"""++from __future__ import annotations++import json+import re+from pathlib import Path++from headroom.learn.plugins.claude import ClaudeCodePlugin, _main_worktree_root+from headroom.memory.traffic_learner import (+ ExtractedPattern,+ PatternCategory,+ _project_for_pattern,+)+++def _repo_with_worktree(base: Path) -> tuple[Path, Path]:+ main, worktree = base / "repo", base / "workspaces" / "san-salvador"+ gitdir = main / ".git" / "worktrees" / "san-salvador"+ gitdir.mkdir(parents=True)+ (gitdir / "commondir").write_text("../..\n")+ worktree.mkdir(parents=True)+ (worktree / ".git").write_text(f"gitdir: {gitdir}\n")+ return main, worktree+++def _folder(claude_dir: Path, cwd: Path) -> Path:+ return claude_dir / "projects" / re.sub(r"[^A-Za-z0-9]", "-", str(cwd))+++def _write_session(claude_dir: Path, cwd: Path, name: str) -> None:+ call = {"type": "tool_use", "id": "u1", "name": "Bash", "input": {"command": "ls"}}+ result = {"type": "tool_result", "tool_use_id": "u1", "content": "ok"}+ lines = [+ {"type": "assistant", "cwd": str(cwd), "message": {"content": [call]}},+ {"type": "user", "cwd": str(cwd), "message": {"content": [result]}},+ ]+ folder = _folder(claude_dir, cwd)+ folder.mkdir(parents=True, exist_ok=True)+ (folder / f"{name}.jsonl").write_text("\n".join(json.dumps(x) for x in lines) + "\n")+++def test_main_worktree_root_resolves_linked_worktrees_only(tmp_path: Path) -> None:+ base = tmp_path.resolve()+ main, worktree = _repo_with_worktree(base)+ (worktree / "src").mkdir()+ submodule, sub_gitdir = main / "vendor" / "lib", main / ".git" / "modules" / "lib"+ submodule.mkdir(parents=True)+ sub_gitdir.mkdir(parents=True)+ (submodule / ".git").write_text("gitdir: ../../.git/modules/lib\n")++ assert _main_worktree_root(worktree) == main+ assert _main_worktree_root(worktree / "src") == main+ assert _main_worktree_root(main) is None+ assert _main_worktree_root(submodule) is None+ assert _main_worktree_root(base) is None+++def test_relative_path_never_resolves_through_the_working_directory(+ tmp_path: Path, monkeypatch+) -> None:+ _, worktree = _repo_with_worktree(tmp_path.resolve())+ monkeypatch.chdir(worktree)++ assert _main_worktree_root(Path("C:\\Users\\dev\\work")) is None+ assert _main_worktree_root(Path("src")) is None+++def test_worktree_sessions_merge_into_the_main_checkout(tmp_path: Path) -> None:+ base = tmp_path.resolve()+ main, worktree = _repo_with_worktree(base)+ claude_dir = base / "claude"+ _write_session(claude_dir, main, "a")+ _write_session(claude_dir, worktree, "b")+ plugin = ClaudeCodePlugin(claude_dir=claude_dir)++ [project] = plugin.discover_projects()++ assert project.project_path == main+ assert project.data_path == _folder(claude_dir, main)+ assert project.worktree_paths == [worktree]+ assert project.extra_data_paths == [_folder(claude_dir, worktree)]+ assert len(plugin.scan_project(project)) == 2+++def test_worktree_only_repo_gets_the_main_checkouts_memory_folder(tmp_path: Path) -> None:+ # Conductor shape: every session runs in a workspace, none in the repo.+ base = tmp_path.resolve()+ main, worktree = _repo_with_worktree(base)+ claude_dir = base / "claude"+ _write_session(claude_dir, worktree, "a")+ plugin = ClaudeCodePlugin(claude_dir=claude_dir)++ [project] = plugin.discover_projects()++ assert project.project_path == main+ assert project.name == "repo"+ assert project.data_path == _folder(claude_dir, main)+ assert project.extra_data_paths == [_folder(claude_dir, worktree)]+ assert len(plugin.scan_project(project)) == 1+++def test_projects_outside_worktrees_are_untouched(tmp_path: Path) -> None:+ base = tmp_path.resolve()+ one, two = base / "one", base / "two"+ one.mkdir()+ two.mkdir()+ claude_dir = base / "claude"+ _write_session(claude_dir, one, "a")+ _write_session(claude_dir, two, "b")++ projects = ClaudeCodePlugin(claude_dir=claude_dir).discover_projects()++ assert sorted(p.project_path for p in projects) == [one, two]+ assert all(not p.worktree_paths and not p.extra_data_paths for p in projects)+++def test_traffic_pattern_in_a_worktree_routes_to_its_repo(tmp_path: Path) -> None:+ base = tmp_path.resolve()+ main, worktree = _repo_with_worktree(base)+ claude_dir = base / "claude"+ _write_session(claude_dir, main, "a")+ _write_session(claude_dir, worktree, "b")+ [project] = ClaudeCodePlugin(claude_dir=claude_dir).discover_projects()+ pattern = ExtractedPattern(+ category=PatternCategory.PREFERENCE,+ content=f"Edit `{worktree}/src/app.py` rather than the generated copy.",+ importance=0.5,+ )++ assert _project_for_pattern(pattern, [project]) is project+++def test_a_session_started_in_a_worktree_subfolder_records_the_checkout(tmp_path: Path) -> None:+ """Selecting the worktree itself must find a project whose only session+ started in one of its subfolders."""+ base = tmp_path.resolve()+ main, worktree = _repo_with_worktree(base)+ (worktree / "src").mkdir()+ claude_dir = base / "claude"+ _write_session(claude_dir, worktree / "src", "a")++ [project] = ClaudeCodePlugin(claude_dir=claude_dir).discover_projects()++ assert project.project_path == main+ assert project.worktree_paths == [worktree / "src", worktree]