threadkeeper 0.4.0__py3-none-any.whl

threadkeeper/adapters/claude_code.py

@@ -0,0 +1,178 @@
+"""Claude Code adapter.
+
+Claude Code stores conversation transcripts as JSONL files under
+~/.claude/projects/<slug>/<conversation-id>.jsonl. MCP servers are
+registered in ~/.claude.json under "mcpServers".
+"""
+from __future__ import annotations
+
+import json
+import os
+import shutil
+from datetime import datetime
+from pathlib import Path
+from typing import Iterator
+
+from .base import CLIAdapter, NormalizedMessage
+
+
+def _ts(s: str) -> int:
+    try:
+        return int(datetime.fromisoformat(s.replace("Z", "+00:00")).timestamp())
+    except Exception:
+        import time
+        return int(time.time())
+
+
+def _extract_text(msg: dict) -> str:
+    """Pull searchable text from a message; skip tool_use args,
+    cap tool_results. Matches the legacy behavior pre-adapter."""
+    content = msg.get("content", "")
+    if isinstance(content, str):
+        return content
+    if not isinstance(content, list):
+        return ""
+    parts: list[str] = []
+    for block in content:
+        if not isinstance(block, dict):
+            continue
+        t = block.get("type")
+        if t == "text":
+            parts.append(block.get("text", ""))
+        elif t == "thinking":
+            parts.append(f"[thinking] {block.get('thinking', '')}")
+        elif t == "tool_result":
+            tr = block.get("content", "")
+            if isinstance(tr, list):
+                tr = " ".join(b.get("text", "") for b in tr if isinstance(b, dict))
+            if isinstance(tr, str) and tr:
+                parts.append(f"[tool_result] {tr[:800]}")
+    return "\n".join(p for p in parts if p)
+
+
+class ClaudeCodeAdapter(CLIAdapter):
+    name = "claude-code"
+
+    def __init__(self) -> None:
+        self.projects_dir = Path(
+            os.environ.get("CLAUDE_PROJECTS_DIR", "~/.claude/projects")
+        ).expanduser()
+        self.config_path = Path("~/.claude.json").expanduser()
+        self._instructions = Path("~/.claude/CLAUDE.md").expanduser()
+        # Hooks live in the same settings.json that controls other
+        # editor preferences. Each entry under "hooks" is keyed by event
+        # name (SessionStart, PostToolUse, ...).
+        self._settings_path = Path("~/.claude/settings.json").expanduser()
+        # Claude auto-discovers SKILL.md files under this directory via
+        # frontmatter description scanning at session start. The canonical
+        # Anthropic skills format.
+        self._skills_dir = Path(
+            os.environ.get("CLAUDE_SKILLS_DIR", "~/.claude/skills")
+        ).expanduser()
+
+    def skills_dir(self):
+        return self._skills_dir
+
+    def instructions_path(self):
+        return self._instructions
+
+    def hooks_supported(self) -> bool:
+        return True
+
+    def register_hooks(self, specs, dry_run=False) -> str:
+        from ._hook_helpers import install_claude_style_hooks
+        return install_claude_style_hooks(
+            self._settings_path, specs, dry_run=dry_run,
+        )
+
+    # ----------------------------- detection -----------------------------
+    def is_installed(self) -> bool:
+        # Either the projects dir exists (user has used Claude Code at
+        # least once) OR the executable is on PATH.
+        if self.projects_dir.exists():
+            return True
+        return shutil.which("claude") is not None
+
+    # ----------------------------- mcp -----------------------------------
+    def register_mcp_server(
+        self, name, command, args, env, dry_run=False
+    ) -> str:
+        cfg: dict
+        if self.config_path.exists():
+            try:
+                cfg = json.loads(self.config_path.read_text())
+            except json.JSONDecodeError:
+                return "claude-code: malformed ~/.claude.json — refused"
+        else:
+            cfg = {}
+        servers = cfg.setdefault("mcpServers", {})
+        entry = {
+            "type": "stdio",
+            "command": command,
+            "args": list(args),
+            "env": dict(env),
+        }
+        existing = servers.get(name)
+        if existing == entry:
+            return "claude-code: already current"
+        servers[name] = entry
+        if not dry_run:
+            self.config_path.write_text(json.dumps(cfg, indent=2))
+        return f"claude-code: {'would ' if dry_run else ''}{'update' if existing else 'add'}"
+
+    def unregister_mcp_server(self, name, dry_run=False) -> str:
+        if not self.config_path.exists():
+            return "claude-code: nothing to remove"
+        cfg = json.loads(self.config_path.read_text())
+        servers = (cfg.get("mcpServers") or {})
+        if name not in servers:
+            return "claude-code: not present"
+        if dry_run:
+            return f"claude-code: would remove {name}"
+        servers.pop(name)
+        self.config_path.write_text(json.dumps(cfg, indent=2))
+        return f"claude-code: removed {name}"
+
+    # ----------------------------- transcripts ---------------------------
+    def session_dir(self):
+        return self.projects_dir
+
+    def transcript_files(self) -> list[Path]:
+        if not self.projects_dir.exists():
+            return []
+        return list(self.projects_dir.glob("**/*.jsonl"))
+
+    def iter_messages(self, fp: Path) -> Iterator[NormalizedMessage]:
+        try:
+            with fp.open("r", encoding="utf-8", errors="replace") as f:
+                for line in f:
+                    line = line.strip()
+                    if not line:
+                        continue
+                    try:
+                        obj = json.loads(line)
+                    except json.JSONDecodeError:
+                        continue
+                    uuid = obj.get("uuid")
+                    if not uuid:
+                        continue
+                    msg = obj.get("message", {})
+                    role = msg.get("role") or obj.get("type")
+                    if role not in ("user", "assistant"):
+                        continue
+                    text = _extract_text(msg)
+                    created = _ts(obj.get("timestamp", ""))
+                    yield NormalizedMessage(
+                        uuid=uuid,
+                        session_id=obj.get("sessionId") or "",
+                        role=role,
+                        content=text,
+                        model=msg.get("model") or "",
+                        created_at=created,
+                        raw=msg,
+                    )
+        except OSError:
+            return
+
+
+ADAPTER = ClaudeCodeAdapter()

threadkeeper/adapters/claude_desktop.py

@@ -0,0 +1,128 @@
+"""Claude Desktop adapter.
+
+Claude Desktop is the Electron app — distinct from Claude Code (the CLI).
+The two share a vendor but not a config or transcript location:
+
+  * Claude Code (CLI):  ~/.claude.json , ~/.claude/projects/**/*.jsonl
+  * Claude Desktop:     ~/Library/Application Support/Claude/
+                        claude_desktop_config.json on macOS;
+                        %APPDATA%/Claude/... on Windows;
+                        ~/.config/Claude/... on Linux.
+
+Config shape mirrors Gemini/Copilot:
+
+    {"mcpServers": {"<name>": {"command": "...", "args": [...], "env": {...}}}}
+
+Claude Desktop has no shell-style hook mechanism and no global per-user
+instructions file analogous to ~/.claude/CLAUDE.md (style + memory live
+inside the app's GUI settings, not on disk). Conversations are stored
+in Electron's IndexedDB (a leveldb on disk), which is fragile to parse
+without browser tooling — we skip transcript ingest. MCP registration
+alone gets thread-keeper's tools available inside Claude Desktop chats,
+which is the integration users actually ask for.
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Iterator
+
+from .base import CLIAdapter, NormalizedMessage
+
+
+def _default_config_path() -> Path:
+    """Per-OS default location for claude_desktop_config.json.
+
+    Overridable via CLAUDE_DESKTOP_CONFIG env var (used by tests)."""
+    env = os.environ.get("CLAUDE_DESKTOP_CONFIG")
+    if env:
+        return Path(env).expanduser()
+    if sys.platform == "darwin":
+        return Path(
+            "~/Library/Application Support/Claude/claude_desktop_config.json"
+        ).expanduser()
+    if sys.platform == "win32":
+        appdata = os.environ.get("APPDATA") or "~/AppData/Roaming"
+        return Path(appdata).expanduser() / "Claude" / "claude_desktop_config.json"
+    # linux / freebsd / others — follow XDG-ish convention used by other
+    # Electron apps shipped under "Claude".
+    return Path("~/.config/Claude/claude_desktop_config.json").expanduser()
+
+
+def _app_bundle_present() -> bool:
+    """On macOS, detect Claude Desktop without requiring its config file
+    to exist yet (fresh install hasn't launched once)."""
+    if sys.platform == "darwin":
+        return Path("/Applications/Claude.app").exists()
+    return False
+
+
+class ClaudeDesktopAdapter(CLIAdapter):
+    name = "claude-desktop"
+
+    def __init__(self) -> None:
+        self.config_path = _default_config_path()
+
+    # ----------------------------- detection -----------------------------
+    def is_installed(self) -> bool:
+        return self.config_path.exists() or _app_bundle_present()
+
+    # ----------------------------- mcp -----------------------------------
+    def register_mcp_server(
+        self, name, command, args, env, dry_run=False
+    ) -> str:
+        cfg: dict
+        if self.config_path.exists():
+            try:
+                cfg = json.loads(self.config_path.read_text())
+            except json.JSONDecodeError:
+                return "claude-desktop: malformed config — refused"
+        else:
+            cfg = {}
+        servers = cfg.setdefault("mcpServers", {})
+        entry: dict = {
+            "command": command,
+            "args": list(args),
+        }
+        if env:
+            entry["env"] = dict(env)
+        existing = servers.get(name)
+        if existing == entry:
+            return "claude-desktop: already current"
+        servers[name] = entry
+        if not dry_run:
+            self.config_path.parent.mkdir(parents=True, exist_ok=True)
+            self.config_path.write_text(json.dumps(cfg, indent=2))
+        return f"claude-desktop: {'would ' if dry_run else ''}{'update' if existing else 'add'}"
+
+    def unregister_mcp_server(self, name, dry_run=False) -> str:
+        if not self.config_path.exists():
+            return "claude-desktop: nothing to remove"
+        try:
+            cfg = json.loads(self.config_path.read_text())
+        except json.JSONDecodeError:
+            return "claude-desktop: malformed config — refused"
+        servers = (cfg.get("mcpServers") or {})
+        if name not in servers:
+            return "claude-desktop: not present"
+        if dry_run:
+            return f"claude-desktop: would remove {name}"
+        servers.pop(name)
+        self.config_path.write_text(json.dumps(cfg, indent=2))
+        return f"claude-desktop: removed {name}"
+
+    # ----------------------------- transcripts ---------------------------
+    # Claude Desktop stores chats inside Electron IndexedDB (leveldb on
+    # disk). Parsing that without Chromium/Electron tooling is brittle,
+    # so we don't expose any transcripts here — MCP registration alone is
+    # the win. dialog_search() across other CLIs still works normally.
+    def transcript_files(self) -> list[Path]:
+        return []
+
+    def iter_messages(self, fp: Path) -> Iterator[NormalizedMessage]:
+        return iter(())
+
+
+ADAPTER = ClaudeDesktopAdapter()

threadkeeper/adapters/codex.py

@@ -0,0 +1,259 @@
+"""OpenAI Codex CLI adapter.
+
+Codex stores configuration in ~/.codex/config.toml with sections
+`[mcp_servers.<name>]`. Conversation transcripts are JSONL files at
+~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl with envelopes like:
+
+  {"timestamp": "...", "type": "session_meta", "payload": {...}}
+  {"timestamp": "...", "type": "event_msg",    "payload": {...}}
+  {"timestamp": "...", "type": "response_item","payload": {"type": "message", "role": ..., "content": [...]}}
+
+We pick `type=response_item` and `payload.type=message` as turns.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+from datetime import datetime
+from pathlib import Path
+from typing import Iterator
+
+from .base import CLIAdapter, NormalizedMessage
+
+
+def _ts(s: str) -> int:
+    try:
+        return int(datetime.fromisoformat(s.replace("Z", "+00:00")).timestamp())
+    except Exception:
+        import time
+        return int(time.time())
+
+
+def _extract_text(payload: dict) -> str:
+    """Codex content blocks: input_text/output_text/tool_call/etc.
+    We collect the text-flavored ones, cap tool_call payloads."""
+    content = payload.get("content", [])
+    if isinstance(content, str):
+        return content
+    if not isinstance(content, list):
+        return ""
+    parts: list[str] = []
+    for block in content:
+        if not isinstance(block, dict):
+            continue
+        t = block.get("type")
+        if t in ("input_text", "output_text", "text"):
+            parts.append(block.get("text", ""))
+        elif t == "thinking":
+            parts.append(f"[thinking] {block.get('text', '')}")
+        elif t == "tool_call_output":
+            out = block.get("output", "")
+            if isinstance(out, str) and out:
+                parts.append(f"[tool_result] {out[:800]}")
+    return "\n".join(p for p in parts if p)
+
+
+# --- minimal TOML R/W ---------------------------------------------------
+# We don't want to depend on tomllib for writes (Python's stdlib has
+# tomllib for reads only). The shape we touch is one section:
+# `[mcp_servers.<name>]` with key=value lines. Implement just enough.
+
+def _read_toml(fp: Path) -> dict:
+    if not fp.exists():
+        return {}
+    try:
+        import tomllib  # py3.11+
+    except ImportError:
+        # Fallback: VERY narrow parser — only used in environments
+        # without tomllib. Returns empty (caller treats as "no MCP").
+        return {}
+    try:
+        return tomllib.loads(fp.read_text())
+    except Exception:
+        return {}
+
+
+def _serialize_mcp_section(name: str, command: str,
+                           args: list[str], env: dict[str, str]) -> str:
+    """Produce the `[mcp_servers.<name>]` TOML block as a string."""
+    lines = [f"[mcp_servers.{name}]"]
+    lines.append(f"command = {json.dumps(command)}")
+    args_str = "[" + ", ".join(json.dumps(a) for a in args) + "]"
+    lines.append(f"args = {args_str}")
+    if env:
+        lines.append("[mcp_servers." + name + ".env]")
+        for k, v in env.items():
+            lines.append(f"{k} = {json.dumps(v)}")
+    return "\n".join(lines) + "\n"
+
+
+_SECTION_HEADER_RE = re.compile(
+    r"^\[(mcp_servers\.[A-Za-z0-9_\-]+)(?:\.[A-Za-z0-9_\-]+)?\]\s*$",
+    re.MULTILINE,
+)
+
+
+def _replace_or_append_mcp_block(
+    body: str, name: str, new_block: str
+) -> str:
+    """Strip every TOML section beginning with `[mcp_servers.<name>...]`
+    (including nested `.env`), then append the new block at end.
+    Other sections are preserved as-is."""
+    out: list[str] = []
+    current_section = ""
+    target_prefix = f"mcp_servers.{name}"
+    skip_current = False
+    for line in body.splitlines(keepends=True):
+        m = _SECTION_HEADER_RE.match(line.rstrip("\n"))
+        if m:
+            section_full = m.group(0).strip("[]")
+            current_section = section_full
+            skip_current = (
+                section_full == target_prefix
+                or section_full.startswith(target_prefix + ".")
+            )
+            if skip_current:
+                continue
+        if skip_current:
+            # still inside the target section — drop the line
+            continue
+        out.append(line)
+    result = "".join(out).rstrip() + "\n\n" + new_block
+    return result
+
+
+# --- adapter ------------------------------------------------------------
+
+class CodexAdapter(CLIAdapter):
+    name = "codex"
+
+    def __init__(self) -> None:
+        self.config_path = Path("~/.codex/config.toml").expanduser()
+        self.sessions_dir = Path("~/.codex/sessions").expanduser()
+        # Codex loads AGENTS.md from cwd → parents → ~. We manage the
+        # home-level fallback so it's always present even outside a
+        # project tree.
+        self._instructions = Path("~/.codex/AGENTS.md").expanduser()
+        # Codex auto-discovers skills under $CODEX_HOME/skills/ — same
+        # Anthropic-style SKILL.md format Claude uses. Multi-mirror in
+        # skill_manage propagates SKILL.md here so the same skill is
+        # available in Codex's own session.
+        self._skills_dir = Path(
+            os.environ.get("CODEX_HOME", "~/.codex")
+        ).expanduser() / "skills"
+
+    def skills_dir(self):
+        return self._skills_dir
+
+    def instructions_path(self):
+        return self._instructions
+
+    def is_installed(self) -> bool:
+        if self.config_path.exists() or self.sessions_dir.exists():
+            return True
+        return shutil.which("codex") is not None
+
+    # ----- MCP registration ---------------------------------------------
+    def register_mcp_server(
+        self, name, command, args, env, dry_run=False
+    ) -> str:
+        block = _serialize_mcp_section(name, command, list(args), dict(env))
+        if not self.config_path.exists():
+            if dry_run:
+                return "codex: would create config.toml with mcp section"
+            self.config_path.parent.mkdir(parents=True, exist_ok=True)
+            self.config_path.write_text(block)
+            return "codex: created config.toml"
+        body = self.config_path.read_text()
+        # Check if already current (cheap normalization compare)
+        already = _read_toml(self.config_path).get("mcp_servers", {}).get(name)
+        if isinstance(already, dict):
+            want = {"command": command, "args": list(args)}
+            if env:
+                want["env"] = dict(env)
+            if already == want:
+                return "codex: already current"
+        new_body = _replace_or_append_mcp_block(body, name, block)
+        if new_body == body:
+            return "codex: already current"
+        if dry_run:
+            return "codex: would update config.toml"
+        self.config_path.write_text(new_body)
+        return "codex: updated config.toml"
+
+    def unregister_mcp_server(self, name, dry_run=False) -> str:
+        if not self.config_path.exists():
+            return "codex: nothing to remove"
+        body = self.config_path.read_text()
+        new_body = _replace_or_append_mcp_block(body, name, "").rstrip() + "\n"
+        if new_body.rstrip() == body.rstrip():
+            return "codex: not present"
+        if dry_run:
+            return f"codex: would remove {name}"
+        self.config_path.write_text(new_body)
+        return f"codex: removed {name}"
+
+    # ----- Transcript ingestion -----------------------------------------
+    def session_dir(self):
+        return self.sessions_dir
+
+    def transcript_files(self) -> list[Path]:
+        if not self.sessions_dir.exists():
+            return []
+        return list(self.sessions_dir.glob("**/rollout-*.jsonl"))
+
+    def iter_messages(self, fp: Path) -> Iterator[NormalizedMessage]:
+        sess_id = ""
+        try:
+            with fp.open("r", encoding="utf-8", errors="replace") as f:
+                for line in f:
+                    line = line.strip()
+                    if not line:
+                        continue
+                    try:
+                        env = json.loads(line)
+                    except json.JSONDecodeError:
+                        continue
+                    typ = env.get("type")
+                    payload = env.get("payload") or {}
+                    if typ == "session_meta" and isinstance(payload, dict):
+                        sess_id = payload.get("id") or sess_id
+                        continue
+                    if typ != "response_item":
+                        continue
+                    if not isinstance(payload, dict):
+                        continue
+                    if payload.get("type") != "message":
+                        continue
+                    role = payload.get("role")
+                    if role == "developer":
+                        # Codex injects a developer turn with permission
+                        # instructions etc. Skip — not user dialog.
+                        continue
+                    if role not in ("user", "assistant"):
+                        continue
+                    text = _extract_text(payload)
+                    # Stable per-line id: use payload.id when present,
+                    # else fall back to timestamp+offset.
+                    uuid = payload.get("id") or f"codex:{fp.name}:{env.get('timestamp', '')}"
+                    yield NormalizedMessage(
+                        uuid=uuid,
+                        session_id=sess_id,
+                        role=role,
+                        content=text,
+                        model=payload.get("model") or "",
+                        created_at=_ts(env.get("timestamp", "")),
+                        raw=payload,
+                    )
+        except OSError:
+            return
+
+    def project_label(self, fp: Path) -> str:
+        # rollout files are in YYYY/MM/DD subdirs — use the parent of
+        # parent (year/month) for a coarse but meaningful label.
+        return f"codex-{fp.parent.parent.parent.name}"  # year
+
+
+ADAPTER = CodexAdapter()