dogear 0.1.0__py3-none-any.whl

dogear/__init__.py

@@ -0,0 +1,3 @@
+"""dogear: favourite, list and resume Claude Code and Codex sessions."""
+
+__version__ = "0.1.0"

dogear/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from dogear.cli import main
+
+sys.exit(main())

dogear/agents/__init__.py

@@ -0,0 +1,81 @@
+"""Agent adapters. Adding an agent means adding one module with an Adapter."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Protocol
+
+if TYPE_CHECKING:
+    from dogear.proctree import ProcessTable
+
+
+@dataclass(frozen=True)
+class Session:
+    agent: str
+    session_id: str
+    cwd: str
+    title: str
+    mtime: float
+    path: Path | None
+
+
+class Adapter(Protocol):
+    name: str
+
+    def find(self, prefix: str) -> list[Session]: ...
+    def get(self, session_id: str) -> Session | None: ...
+    def exists(self, session_id: str) -> bool: ...
+    def recent(self, limit: int) -> list[Session]: ...
+    def is_agent_process(self, command: str) -> bool: ...
+    def detect(self, pid: int, table: "ProcessTable") -> list[Session]: ...
+    def resume_args(self, session_id: str) -> list[str]: ...
+
+
+def command_basename(command: str) -> str:
+    """'C:\\x\\claude.exe' -> 'claude'; '-zsh' -> 'zsh' (login shells)."""
+    base = command.replace("\\", "/").rstrip("/").rsplit("/", 1)[-1]
+    if base.lower().endswith(".exe"):
+        base = base[:-4]
+    return base.lstrip("-")
+
+
+def newest_by_id(paths_with_ids: list[tuple[str, Path]]) -> dict[str, Path]:
+    """Several files can exist for one session id; keep the newest (spec §11b)."""
+    best: dict[str, tuple[float, Path]] = {}
+    for sid, p in paths_with_ids:
+        try:
+            m = p.stat().st_mtime
+        except OSError:
+            continue
+        if sid not in best or m > best[sid][0]:
+            best[sid] = (m, p)
+    return {sid: p for sid, (m, p) in best.items()}
+
+
+def newest_first(by_id: dict[str, Path], limit: int) -> list[tuple[str, Path]]:
+    """Sort by mtime without failing when a file disappears meanwhile (agents prune old ones)."""
+    stamped = []
+    for sid, p in by_id.items():
+        try:
+            stamped.append((p.stat().st_mtime, sid, p))
+        except OSError:
+            continue
+    stamped.sort(key=lambda t: t[0], reverse=True)
+    return [(sid, p) for _, sid, p in stamped[:limit]]
+
+
+def get_adapters() -> dict[str, Adapter]:
+    from dogear.agents.claude import ClaudeAdapter
+    from dogear.agents.codex import CodexAdapter
+
+    return {"claude": ClaudeAdapter(), "codex": CodexAdapter()}
+
+
+def find_sessions(prefix: str, agent: str | None = None) -> list[Session]:
+    out: list[Session] = []
+    prefix = prefix.lower()  # session ids are lowercase UUIDs
+    for name, adapter in get_adapters().items():
+        if agent is None or agent == name:
+            out.extend(adapter.find(prefix))
+    return out

dogear/agents/claude.py

@@ -0,0 +1,134 @@
+"""Claude Code session store (read-only). Internal files observed on Claude Code 2.1.x."""
+
+from __future__ import annotations
+
+import glob
+import json
+import re
+from pathlib import Path
+
+from dogear.agents import Session, command_basename, newest_by_id, newest_first
+from dogear.paths import claude_home
+
+TITLE_LEN = 60
+SESSION_FILE = re.compile(r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$")
+
+
+def _prompt_text(message: object) -> str:
+    if not isinstance(message, dict):
+        return ""
+    content = message.get("content")
+    if isinstance(content, str):
+        text = content
+    elif isinstance(content, list):
+        text = next(
+            (b.get("text", "") for b in content if isinstance(b, dict) and b.get("type") == "text"),
+            "",
+        )
+    else:
+        return ""
+    text = " ".join(str(text).split())
+    if text.startswith("<"):  # command wrappers and other meta content, not a real prompt
+        return ""
+    return text
+
+
+def _shorten(text: str) -> str:
+    return text if len(text) <= TITLE_LEN else text[: TITLE_LEN - 1].rstrip() + "…"
+
+
+class ClaudeAdapter:
+    name = "claude"
+
+    def __init__(self, home: Path | None = None):
+        self.home = home or claude_home()
+
+    # store -----------------------------------------------------------------
+
+    def _transcripts(self, prefix: str = "") -> dict[str, Path]:
+        # only the part below the store root is a pattern; the root may contain [ ] * ?
+        pattern = f"*/{glob.escape(prefix)}*.jsonl"
+        # sub-agent and other side files (e.g. agent-*.jsonl) are not resumable sessions
+        found = [(p.stem, p) for p in (self.home / "projects").glob(pattern) if SESSION_FILE.match(p.stem)]
+        return newest_by_id(found)
+
+    def _session(self, sid: str, path: Path) -> Session:
+        custom = ai = prompt = ""
+        cwd = ""
+        for obj in self._wanted_lines(path, lambda: not cwd, lambda: not prompt):
+            t = obj.get("type")
+            if not cwd and isinstance(obj.get("cwd"), str):
+                cwd = obj["cwd"]
+            if t == "custom-title" and isinstance(obj.get("customTitle"), str):
+                custom = obj["customTitle"]
+            elif t == "ai-title" and isinstance(obj.get("aiTitle"), str):
+                ai = obj["aiTitle"]
+            elif t == "user" and not prompt and not obj.get("isMeta"):
+                prompt = _prompt_text(obj.get("message"))
+        title = custom.strip() or ai.strip() or (_shorten(prompt) if prompt else "(untitled)")
+        try:
+            mtime = path.stat().st_mtime
+        except OSError:
+            mtime = 0.0
+        return Session("claude", sid, cwd, title, mtime, path)
+
+    @staticmethod
+    def _wanted_lines(path: Path, need_cwd, need_prompt):
+        """Parse only the lines that can matter: transcripts are large and most lines
+        are messages, so skip JSON-decoding them once cwd and the first prompt are known."""
+        try:
+            f = path.open("rb")
+        except OSError:
+            return
+        with f:
+            for raw in f:
+                if not (b'-title"' in raw or need_cwd() or (need_prompt() and b'"user"' in raw)):
+                    continue
+                try:
+                    obj = json.loads(raw)
+                except ValueError:
+                    continue
+                if isinstance(obj, dict):
+                    yield obj
+
+    def find(self, prefix: str) -> list[Session]:
+        return [self._session(sid, p) for sid, p in sorted(self._transcripts(prefix).items())]
+
+    def get(self, session_id: str) -> Session | None:
+        p = self._transcripts(session_id).get(session_id)
+        return self._session(session_id, p) if p else None
+
+    def exists(self, session_id: str) -> bool:
+        return session_id in self._transcripts(session_id)
+
+    def recent(self, limit: int) -> list[Session]:
+        return [self._session(sid, p) for sid, p in newest_first(self._transcripts(), limit)]
+
+    # processes -------------------------------------------------------------
+
+    def is_agent_process(self, command: str) -> bool:
+        norm = command.replace("\\", "/")
+        return (
+            command_basename(command) == "claude"
+            or "/claude/versions/" in norm
+            or "/@anthropic-ai/claude-code/" in norm
+        )
+
+    def detect(self, pid: int, table) -> list[Session]:
+        """Claude writes sessions/<pid>.json for each live process; stale files are ignored."""
+        try:
+            live = json.loads((self.home / "sessions" / f"{pid}.json").read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError, UnicodeDecodeError):
+            return []
+        if not isinstance(live, dict) or live.get("pid") != pid or not isinstance(live.get("sessionId"), str):
+            return []
+        sid = live["sessionId"]
+        found = self.get(sid)
+        if found:
+            return [found]
+        cwd = live.get("cwd") if isinstance(live.get("cwd"), str) else ""
+        name = live.get("name") if isinstance(live.get("name"), str) and live.get("name") else "(untitled)"
+        return [Session("claude", sid, cwd, name, 0.0, None)]
+
+    def resume_args(self, session_id: str) -> list[str]:
+        return ["--resume", session_id]

dogear/agents/codex.py

@@ -0,0 +1,113 @@
+"""Codex CLI session store (read-only). Internal files observed on codex-cli 0.16x."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+from dogear.agents import Session, command_basename, newest_by_id, newest_first
+from dogear.jsonl import iter_jsonl
+from dogear.paths import codex_home
+
+UUID_LEN = 36
+
+
+def _first_line(path: Path) -> dict:
+    try:
+        with path.open("r", encoding="utf-8", errors="replace") as f:
+            obj = json.loads(f.readline())
+    except (OSError, json.JSONDecodeError):
+        return {}
+    return obj if isinstance(obj, dict) else {}
+
+
+class CodexAdapter:
+    name = "codex"
+
+    def __init__(self, home: Path | None = None):
+        self.home = home or codex_home()
+
+    # store -----------------------------------------------------------------
+
+    def _rollouts(self, prefix: str = "") -> dict[str, Path]:
+        # only the part below the store root is a pattern; the root may contain [ ] * ?
+        found = []
+        for p in (self.home / "sessions").glob("*/*/*/rollout-*.jsonl"):
+            sid = p.stem[-UUID_LEN:]
+            if sid.startswith(prefix):
+                found.append((sid, p))
+        return newest_by_id(found)
+
+    def _titles(self) -> dict[str, str]:
+        titles: dict[str, str] = {}
+        for obj in iter_jsonl(self.home / "session_index.jsonl"):
+            sid, name = obj.get("id"), obj.get("thread_name")
+            if isinstance(sid, str) and isinstance(name, str) and name.strip():
+                titles[sid] = name.strip()
+        return titles
+
+    def _session(self, sid: str, path: Path, titles: dict[str, str]) -> Session:
+        meta = _first_line(path)
+        payload = meta.get("payload") if meta.get("type") == "session_meta" else None
+        payload = payload if isinstance(payload, dict) else {}
+        if isinstance(payload.get("id"), str):
+            sid = payload["id"]
+        cwd = payload.get("cwd") if isinstance(payload.get("cwd"), str) else ""
+        try:
+            mtime = path.stat().st_mtime
+        except OSError:
+            mtime = 0.0
+        return Session("codex", sid, cwd, titles.get(sid, "(untitled)"), mtime, path)
+
+    def find(self, prefix: str) -> list[Session]:
+        titles = self._titles()
+        return [self._session(sid, p, titles) for sid, p in sorted(self._rollouts(prefix).items())]
+
+    def get(self, session_id: str) -> Session | None:
+        p = self._rollouts(session_id).get(session_id)
+        return self._session(session_id, p, self._titles()) if p else None
+
+    def exists(self, session_id: str) -> bool:
+        return session_id in self._rollouts(session_id)
+
+    def recent(self, limit: int) -> list[Session]:
+        newest = newest_first(self._rollouts(), limit)
+        titles = self._titles()
+        return [self._session(sid, p, titles) for sid, p in newest]
+
+    # processes -------------------------------------------------------------
+
+    def is_agent_process(self, command: str) -> bool:
+        return command_basename(command) == "codex"
+
+    def detect(self, pid: int, table) -> list[Session]:
+        """The rollout the process has open; else rollouts in its cwd written since it started."""
+        sessions_dir = os.path.realpath(self.home / "sessions")
+        open_ids = []
+        for f in table.open_files(pid):
+            real = os.path.realpath(f)
+            name = os.path.basename(real)
+            if real.startswith(sessions_dir + os.sep) and name.startswith("rollout-") and name.endswith(".jsonl"):
+                open_ids.append(name[: -len(".jsonl")][-UUID_LEN:])
+        if open_ids:
+            return [s for sid in dict.fromkeys(open_ids) if (s := self.get(sid))]
+        cwd, start = table.cwd(pid), table.start_time(pid)
+        if not cwd or start is None:
+            return []
+        real_cwd = os.path.realpath(cwd)
+        titles = self._titles()
+        out = []
+        for sid, p in sorted(self._rollouts().items()):
+            try:
+                if p.stat().st_mtime < start:
+                    continue
+            except OSError:
+                continue
+            s = self._session(sid, p, titles)
+            if s.cwd and os.path.realpath(s.cwd) == real_cwd:
+                out.append(s)
+        return out
+
+    def resume_args(self, session_id: str) -> list[str]:
+        return ["resume", session_id]

dogear/assets/claude_skill.md

@@ -0,0 +1,35 @@
+---
+name: dogear
+description: Save the current Claude Code session as a dogear favourite (bookmark) so it can be listed and resumed later from any folder. Use when the user runs /dogear or explicitly asks to dogear, bookmark or favourite this session. Not for browser bookmarks or bookmarks in code.
+argument-hint: "[name] [tags, note, launch flags — plain words are fine]"
+allowed-tools: Bash(command -v dogear), Bash(where dogear), Bash(dogear add *), Bash(dogear rename *)
+---
+
+Save this session as a dogear favourite.
+
+The user's request: $ARGUMENTS
+(If that is empty, use what the user just asked for; it may be nothing beyond "save it".)
+
+1. Check that the `dogear` command is installed: run `command -v dogear`
+   (on Windows, `where dogear`).
+2. If it is not installed, reply with exactly this line and stop:
+   `dogear is not installed. Install it with: uv tool install dogear (or pipx install dogear)`
+3. Turn the request into one `dogear add` command:
+   - Already in flag form (`my-label -t work -n "note"`): use it unchanged.
+   - A name or label: put it first, as one word (lowercase, hyphens instead of
+     spaces, not only digits).
+   - Tags: one `-t TAG` per tag. A note: `-n "TEXT"`. Launch flags such as a model:
+     `--args "FLAGS"`. Quote any value with spaces.
+   - Nothing given: plain `dogear add`.
+   - Never add a session id unless the user gave one.
+
+   Examples:
+   - "save with name testtest" → `dogear add testtest`
+   - "call it jobs, tags work and client, note: auth half done" →
+     `dogear add jobs -t work -t client -n "auth half done"`
+   - "bookmark this with opus" → `dogear add --args "--model opus"`
+4. Run that command once with the shell tool.
+5. If the output says `already saved as OLD` and the user asked for a
+   different name NEW, run `dogear rename OLD NEW` once.
+6. Reply with the commands' output verbatim and nothing else. If a command
+   fails, show its error and stop; do not retry or run anything else.

dogear/assets/codex_openai.yaml

@@ -0,0 +1,2 @@
+policy:
+  allow_implicit_invocation: true

dogear/assets/codex_skill.md

@@ -0,0 +1,32 @@
+---
+name: dogear
+description: Save the current Codex session as a dogear favourite (bookmark) so it can be listed and resumed later from any folder. Use when the user invokes $dogear or explicitly asks to dogear, bookmark or favourite this session. Not for browser bookmarks or bookmarks in code.
+---
+
+Save this session as a dogear favourite.
+
+The user's request is whatever they typed after `$dogear`, or what they just
+asked for; it may be nothing beyond "save it".
+
+1. Check that the `dogear` command is installed: run `command -v dogear`
+   (on Windows, `where dogear`).
+2. If it is not installed, reply with exactly this line and stop:
+   `dogear is not installed. Install it with: uv tool install dogear (or pipx install dogear)`
+3. Turn the request into one `dogear add` command:
+   - Already in flag form (`my-label -t work -n "note"`): use it unchanged.
+   - A name or label: put it first, as one word (lowercase, hyphens instead of
+     spaces, not only digits).
+   - Tags: one `-t TAG` per tag. A note: `-n "TEXT"`. Launch flags: `--args "FLAGS"`.
+     Quote any value with spaces.
+   - Nothing given: plain `dogear add`.
+   - Never add a session id unless the user gave one.
+
+   Examples:
+   - "save with name testtest" → `dogear add testtest`
+   - "call it jobs, tags work and client, note: auth half done" →
+     `dogear add jobs -t work -t client -n "auth half done"`
+4. Run that command once with the shell tool.
+5. If the output says `already saved as OLD` and the user asked for a
+   different name NEW, run `dogear rename OLD NEW` once.
+6. Reply with the commands' output verbatim and nothing else. If a command
+   fails, show its error and stop; do not retry or run anything else.