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.

fix(learn): honor CLAUDE_CONFIG_DIR when locating Claude logs and memory (#1642)

Manmit Singhc600e314b375
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8d812c1ff..940aa6893 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## Unreleased
### Fixed
+- `headroom learn` now honors `CLAUDE_CONFIG_DIR`. It resolved the Claude
+ config directory as `~/.claude` and wrote global memory to
+ `~/.claude/CLAUDE.md`, so users who relocate their Claude config via that
+ env var had `learn` scan the wrong directory and detect no projects. The
+ scanner and memory writer now read/write the configured directory
+ ([#1630](https://github.com/headroomlabs-ai/headroom/issues/1630)).
- `--backend bedrock` now fails fast with an actionable error when temporary
AWS credentials (`AWS_SESSION_TOKEN`) are used but botocore is not installed
(e.g. the slim default Docker image). litellm's session-token auth path
diff --git a/headroom/learn/_shared.py b/headroom/learn/_shared.py
index 1c1ec6210..1cae53229 100644
--- a/headroom/learn/_shared.py
+++ b/headroom/learn/_shared.py
@@ -6,10 +6,26 @@ used across all scanner plugins.
from __future__ import annotations
+import os
import re
+from pathlib import Path
from .models import ErrorCategory
+
+def claude_config_dir() -> Path:
+ """Resolve the Claude Code config directory, honoring ``CLAUDE_CONFIG_DIR``.
+
+ Claude Code relocates its config (including ``projects/`` logs and the
+ global ``CLAUDE.md``) when ``CLAUDE_CONFIG_DIR`` is set. ``headroom learn``
+ must read and write the same directory, mirroring the override already
+ honored in ``subscription`` and ``mcp_registry``. Falls back to
+ ``~/.claude``.
+ """
+ base = os.environ.get("CLAUDE_CONFIG_DIR")
+ return Path(base) if base else Path.home() / ".claude"
+
+
# =============================================================================
# Error Classification
# =============================================================================
diff --git a/headroom/learn/plugins/claude.py b/headroom/learn/plugins/claude.py
index c790bfdf1..2753c8c20 100644
--- a/headroom/learn/plugins/claude.py
+++ b/headroom/learn/plugins/claude.py
@@ -10,7 +10,7 @@ import logging
import re
from pathlib import Path, PureWindowsPath
-from .._shared import classify_error, is_error_content
+from .._shared import classify_error, claude_config_dir, is_error_content
from ..base import ConversationScanner, LearnPlugin
from ..models import (
ErrorCategory,
@@ -33,7 +33,7 @@ class ClaudeCodePlugin(LearnPlugin, ConversationScanner):
"""
def __init__(self, claude_dir: Path | None = None):
- self.claude_dir = claude_dir or Path.home() / ".claude"
+ self.claude_dir = claude_dir or claude_config_dir()
self.projects_dir = self.claude_dir / "projects"
# --- LearnPlugin identity ---
diff --git a/headroom/learn/writer.py b/headroom/learn/writer.py
index 02b643919..3a5e8a03b 100644
--- a/headroom/learn/writer.py
+++ b/headroom/learn/writer.py
@@ -11,6 +11,7 @@ from abc import ABC, abstractmethod
from datetime import datetime, timezone
from pathlib import Path
+from ._shared import claude_config_dir
from .models import (
ProjectInfo,
Recommendation,
@@ -274,10 +275,11 @@ class ClaudeCodeWriter(ContextWriter):
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.
+ # The home directory's CLAUDE.md (~/.claude/CLAUDE.md, or
+ # $CLAUDE_CONFIG_DIR/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 claude_config_dir() / "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"
@@ -302,12 +304,12 @@ class ClaudeCodeWriter(ContextWriter):
return []
if target_path == legacy_path or not legacy_path.exists():
return []
- legacy_text = legacy_path.read_text(encoding="utf-8")
+ legacy_text = _read_text_tolerant(legacy_path)
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"):
+ if target_path.exists() and _MARKER_START in _read_text_tolerant(target_path):
return []
migrated = _parse_prior_recommendations(legacy_text)
diff --git a/tests/test_learn/test_claude_config_dir.py b/tests/test_learn/test_claude_config_dir.py
new file mode 100644
index 000000000..9c9b0bf71
--- /dev/null
+++ b/tests/test_learn/test_claude_config_dir.py
@@ -0,0 +1,54 @@
+"""Regression tests: `headroom learn` honors CLAUDE_CONFIG_DIR (issue #1630).
+
+Claude Code relocates its config (conversation logs under ``projects/`` and the
+global ``CLAUDE.md``) when ``CLAUDE_CONFIG_DIR`` is set. The learn scanner and
+memory writer previously hardcoded ``~/.claude``, so they scanned/wrote the
+wrong directory and detected no projects for such users.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from headroom.learn._shared import claude_config_dir
+from headroom.learn.models import ProjectInfo
+from headroom.learn.plugins.claude import ClaudeCodePlugin
+from headroom.learn.writer import ClaudeCodeWriter
+
+
+def test_config_dir_honors_env(tmp_path, monkeypatch) -> None:
+ custom = tmp_path / "custom-claude"
+ monkeypatch.setenv("CLAUDE_CONFIG_DIR", str(custom))
+ assert claude_config_dir() == custom
+
+
+def test_config_dir_defaults_to_home(monkeypatch) -> None:
+ monkeypatch.delenv("CLAUDE_CONFIG_DIR", raising=False)
+ assert claude_config_dir() == Path.home() / ".claude"
+
+
+def test_plugin_scans_config_dir_override(tmp_path, monkeypatch) -> None:
+ custom = tmp_path / "custom-claude"
+ monkeypatch.setenv("CLAUDE_CONFIG_DIR", str(custom))
+ plugin = ClaudeCodePlugin()
+ assert plugin.claude_dir == custom
+ assert plugin.projects_dir == custom / "projects"
+
+
+def test_plugin_explicit_dir_wins_over_env(tmp_path, monkeypatch) -> None:
+ monkeypatch.setenv("CLAUDE_CONFIG_DIR", str(tmp_path / "env"))
+ explicit = tmp_path / "explicit"
+ plugin = ClaudeCodePlugin(claude_dir=explicit)
+ assert plugin.claude_dir == explicit
+
+
+def test_writer_home_memory_follows_config_dir(tmp_path, monkeypatch) -> None:
+ custom = tmp_path / "custom-claude"
+ monkeypatch.setenv("CLAUDE_CONFIG_DIR", str(custom))
+ writer = ClaudeCodeWriter()
+ project = ProjectInfo(
+ name="home",
+ project_path=Path.home(),
+ data_path=custom / "projects",
+ )
+ assert writer._resolve_context_path(project) == custom / "CLAUDE.md"