dogear 0.1.0__tar.gz

dogear-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/

dogear-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oriol Martí
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dogear-0.1.0/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.5
+Name: dogear
+Version: 0.1.0
+Summary: Bookmark, save and resume Claude Code and Codex sessions from any folder: a tiny session manager with names, tags and notes.
+Project-URL: Homepage, https://github.com/orimarti/dogear
+Project-URL: Issues, https://github.com/orimarti/dogear/issues
+Author: Oriol Martí
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,anthropic,bookmark,bookmarks,claude,claude-code,cli,codex,codex-cli,openai-codex,resume,session-manager,sessions
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# dogear: bookmark and resume Claude Code & Codex sessions
+
+> Bookmark, save and resume Claude Code and Codex sessions from any folder. A tiny session manager with names, tags and notes.
+
+You have hundreds of Claude sessions and Codex sessions spread over many
+folders, and a few of them matter. dogear keeps a short, named list of those —
+like folding the corner of a page — and resumes any of them with one command,
+from anywhere: it changes to the session's folder and runs `claude --resume` or
+`codex resume` for you.
+
+- Save the session you're in without leaving it: `/dogear` (Claude Code), `$dogear` (Codex), or `! dogear add`.
+- Save any recent session from a normal terminal through a picker.
+- One list for both agents, with your own names, tags and notes.
+- `dogear` alone: pick a saved session, land in its folder, resumed.
+- Python 3.11+, standard library only. macOS, Linux and Windows. No network access, ever.
+
+## Install
+
+```sh
+uv tool install dogear      # or: pipx install dogear
+```
+
+Then, optionally, add the in-session command:
+
+| Where | How | You type |
+| --- | --- | --- |
+| Claude Code, as a plugin | `/plugin install dogear --marketplace orimarti/dogear` (or `/plugin marketplace add orimarti/dogear` then `/plugin install dogear@dogear`) | `/dogear:dogear` |
+| Claude Code, as a personal skill | `dogear setup claude` | `/dogear` |
+| Codex | `dogear setup codex` | `$dogear` |
+
+Plain words work too: `/dogear save it as jobs, tag work` or just "dogear this
+session as jobs" — the agent turns it into the right `dogear add` flags (and
+renames the favourite if the session was already saved).
+
+Use the plugin **or** `dogear setup claude`, not both. The plugin only provides
+the slash command; the `dogear` CLI still comes from PyPI (the command tells you
+if it's missing).
+
+## 30-second tour
+
+```sh
+# inside a Claude Code or Codex session
+/dogear jobs-api -t work            # or $dogear … in Codex, or: ! dogear add jobs-api -t work
+
+# later, from any terminal
+dogear ls
+#  #  LABEL       AGENT   FOLDER          TITLE           TAGS  NOTE
+#  1  jobs-api    claude  ~/code/jobs     New jobs api    work
+#  2  docs-site   codex   ~/code/site     Docs refresh
+dogear open jobs-api                 # cd ~/code/jobs && claude --resume <id>
+dogear                               # or pick from a list (uses fzf if installed)
+```
+
+From a plain terminal, `dogear add` shows your 50 most recent sessions (both
+agents) to choose from; `dogear add <session-id>` saves one directly (a unique
+prefix of the id is enough).
+
+| Command | What it does |
+| --- | --- |
+| `dogear add [SESSION\|LABEL] [-l LABEL] [-n NOTE] [-t TAG]... [--args FLAGS] [--agent A]` | Save a session. A word that isn't a session id (8+ hex characters) is taken as the label for the current session. Repeat `-t` (or use `-t a,b`) for several tags. Giving a label for a session that's already saved renames it. |
+| `dogear ls [-t TAG] [--agent A] [--json]` | List favourites, newest first. `missing` marks sessions that no longer exist. |
+| `dogear open REF [-- FLAGS]` | Resume a favourite in its folder. Flags after `--` replace its saved flags for this launch (`--` alone: no flags). |
+| `dogear rename REF NEW` · `note REF TEXT` · `tag REF +a -b` · `edit REF --args FLAGS` · `rm REF ...` | Manage favourites. `REF` is a label or the number from `dogear ls`. |
+| `dogear prune [--yes]` | Remove favourites whose session is gone. |
+| `dogear setup claude\|codex [--force]` | Install the in-session command. |
+| `dogear config [--path]` | Show the effective configuration. |
+
+Flags that start with `-` need quoting with a space or an `=`:
+`--args "--model opus"` or `--args=--verbose`.
+
+## Configuration
+
+Optional, at `~/.config/dogear/config.toml` (`$XDG_CONFIG_HOME/dogear`;
+`%APPDATA%\dogear` on Windows; `$DOGEAR_HOME` overrides). Favourites live in
+`favorites.json` next to it, so there's one folder to back up.
+
+```toml
+[claude]
+command = "claude"          # e.g. "claude --dangerously-skip-permissions"
+
+[codex]
+command = "codex"           # e.g. "codex --full-auto"
+
+[picker]
+use_fzf = "auto"            # auto | always | never
+```
+
+**Shell aliases are invisible to dogear.** If you run `alias cc='claude --some-flag'`,
+dogear can't see it — put the flags in `command` above instead. Per-favourite
+flags (`--args`) are added after it.
+
+## How it finds your sessions
+
+dogear reads the agents' own files and never writes to them (the only exception
+is `dogear setup`, when you ask for it). These are internal formats, not public
+APIs, and may change between agent versions:
+
+- **Claude Code**: transcripts in `~/.claude/projects/*/<id>.jsonl` (title from
+  `/rename`, else the generated title, else your first prompt); running sessions
+  in `~/.claude/sessions/<pid>.json`. `$CLAUDE_CONFIG_DIR` is respected.
+- **Codex**: rollouts in `~/.codex/sessions/YYYY/MM/DD/rollout-*-<id>.jsonl`,
+  titles in `~/.codex/session_index.jsonl`. `$CODEX_HOME` is respected.
+
+To save "the current session", dogear walks up its parent processes to the
+nearest `claude` or `codex` process and asks which session it is running. If it
+can't tell for sure it refuses rather than guess, and shows the candidates. On
+Windows this detection is best effort: if it fails, use `dogear add <session-id>`.
+
+Resuming runs `claude --resume <id>` / `codex resume <id>` from the session's
+folder. dogear replaces itself with the agent (on Windows it runs it and waits),
+so your shell is where you left it when the agent exits.
+
+## FAQ
+
+### How do I resume a Claude Code session from another folder?
+
+Save it once with `/dogear my-label` (or `dogear add` from a terminal). From
+then on, `dogear open my-label` works from any directory: dogear changes to the
+folder the session was started in and runs `claude --resume <id>` there.
+
+### How do I resume a Codex session?
+
+The same way. `$dogear my-label` inside Codex (after `dogear setup codex`), or
+`dogear add` from a terminal, saves it; `dogear open my-label` runs
+`codex resume <id>` in the right folder. Claude Code and Codex sessions share
+one list.
+
+### How do I save or bookmark a Claude Code session?
+
+Inside the session, type `/dogear` with an optional name, tags or a note, in
+flags or plain words: `/dogear jobs-api -t work` or `/dogear save it as jobs-api, tag work`.
+From a terminal, `dogear add` lets you pick from your 50 most recent sessions.
+
+### How is this different from `claude --resume` or `codex resume`?
+
+Those pickers list every past session; dogear is the short list you chose to
+keep, with names you'll remember, across both agents, and it starts each
+session from the right folder. It uses the agents' own resume commands, so
+nothing about the sessions themselves changes.
+
+### Does dogear upload or modify my sessions?
+
+No. It only reads the agents' files, never writes to them (except installing
+the in-session command when you run `dogear setup`), and makes no network
+requests.
+
+## Development
+
+```sh
+uv sync
+uv run pytest
+```
+
+Tests use synthetic fixtures only; they never read your real `~/.claude` or `~/.codex`.
+
+## License
+
+MIT

dogear-0.1.0/README.md

@@ -0,0 +1,158 @@
+# dogear: bookmark and resume Claude Code & Codex sessions
+
+> Bookmark, save and resume Claude Code and Codex sessions from any folder. A tiny session manager with names, tags and notes.
+
+You have hundreds of Claude sessions and Codex sessions spread over many
+folders, and a few of them matter. dogear keeps a short, named list of those —
+like folding the corner of a page — and resumes any of them with one command,
+from anywhere: it changes to the session's folder and runs `claude --resume` or
+`codex resume` for you.
+
+- Save the session you're in without leaving it: `/dogear` (Claude Code), `$dogear` (Codex), or `! dogear add`.
+- Save any recent session from a normal terminal through a picker.
+- One list for both agents, with your own names, tags and notes.
+- `dogear` alone: pick a saved session, land in its folder, resumed.
+- Python 3.11+, standard library only. macOS, Linux and Windows. No network access, ever.
+
+## Install
+
+```sh
+uv tool install dogear      # or: pipx install dogear
+```
+
+Then, optionally, add the in-session command:
+
+| Where | How | You type |
+| --- | --- | --- |
+| Claude Code, as a plugin | `/plugin install dogear --marketplace orimarti/dogear` (or `/plugin marketplace add orimarti/dogear` then `/plugin install dogear@dogear`) | `/dogear:dogear` |
+| Claude Code, as a personal skill | `dogear setup claude` | `/dogear` |
+| Codex | `dogear setup codex` | `$dogear` |
+
+Plain words work too: `/dogear save it as jobs, tag work` or just "dogear this
+session as jobs" — the agent turns it into the right `dogear add` flags (and
+renames the favourite if the session was already saved).
+
+Use the plugin **or** `dogear setup claude`, not both. The plugin only provides
+the slash command; the `dogear` CLI still comes from PyPI (the command tells you
+if it's missing).
+
+## 30-second tour
+
+```sh
+# inside a Claude Code or Codex session
+/dogear jobs-api -t work            # or $dogear … in Codex, or: ! dogear add jobs-api -t work
+
+# later, from any terminal
+dogear ls
+#  #  LABEL       AGENT   FOLDER          TITLE           TAGS  NOTE
+#  1  jobs-api    claude  ~/code/jobs     New jobs api    work
+#  2  docs-site   codex   ~/code/site     Docs refresh
+dogear open jobs-api                 # cd ~/code/jobs && claude --resume <id>
+dogear                               # or pick from a list (uses fzf if installed)
+```
+
+From a plain terminal, `dogear add` shows your 50 most recent sessions (both
+agents) to choose from; `dogear add <session-id>` saves one directly (a unique
+prefix of the id is enough).
+
+| Command | What it does |
+| --- | --- |
+| `dogear add [SESSION\|LABEL] [-l LABEL] [-n NOTE] [-t TAG]... [--args FLAGS] [--agent A]` | Save a session. A word that isn't a session id (8+ hex characters) is taken as the label for the current session. Repeat `-t` (or use `-t a,b`) for several tags. Giving a label for a session that's already saved renames it. |
+| `dogear ls [-t TAG] [--agent A] [--json]` | List favourites, newest first. `missing` marks sessions that no longer exist. |
+| `dogear open REF [-- FLAGS]` | Resume a favourite in its folder. Flags after `--` replace its saved flags for this launch (`--` alone: no flags). |
+| `dogear rename REF NEW` · `note REF TEXT` · `tag REF +a -b` · `edit REF --args FLAGS` · `rm REF ...` | Manage favourites. `REF` is a label or the number from `dogear ls`. |
+| `dogear prune [--yes]` | Remove favourites whose session is gone. |
+| `dogear setup claude\|codex [--force]` | Install the in-session command. |
+| `dogear config [--path]` | Show the effective configuration. |
+
+Flags that start with `-` need quoting with a space or an `=`:
+`--args "--model opus"` or `--args=--verbose`.
+
+## Configuration
+
+Optional, at `~/.config/dogear/config.toml` (`$XDG_CONFIG_HOME/dogear`;
+`%APPDATA%\dogear` on Windows; `$DOGEAR_HOME` overrides). Favourites live in
+`favorites.json` next to it, so there's one folder to back up.
+
+```toml
+[claude]
+command = "claude"          # e.g. "claude --dangerously-skip-permissions"
+
+[codex]
+command = "codex"           # e.g. "codex --full-auto"
+
+[picker]
+use_fzf = "auto"            # auto | always | never
+```
+
+**Shell aliases are invisible to dogear.** If you run `alias cc='claude --some-flag'`,
+dogear can't see it — put the flags in `command` above instead. Per-favourite
+flags (`--args`) are added after it.
+
+## How it finds your sessions
+
+dogear reads the agents' own files and never writes to them (the only exception
+is `dogear setup`, when you ask for it). These are internal formats, not public
+APIs, and may change between agent versions:
+
+- **Claude Code**: transcripts in `~/.claude/projects/*/<id>.jsonl` (title from
+  `/rename`, else the generated title, else your first prompt); running sessions
+  in `~/.claude/sessions/<pid>.json`. `$CLAUDE_CONFIG_DIR` is respected.
+- **Codex**: rollouts in `~/.codex/sessions/YYYY/MM/DD/rollout-*-<id>.jsonl`,
+  titles in `~/.codex/session_index.jsonl`. `$CODEX_HOME` is respected.
+
+To save "the current session", dogear walks up its parent processes to the
+nearest `claude` or `codex` process and asks which session it is running. If it
+can't tell for sure it refuses rather than guess, and shows the candidates. On
+Windows this detection is best effort: if it fails, use `dogear add <session-id>`.
+
+Resuming runs `claude --resume <id>` / `codex resume <id>` from the session's
+folder. dogear replaces itself with the agent (on Windows it runs it and waits),
+so your shell is where you left it when the agent exits.
+
+## FAQ
+
+### How do I resume a Claude Code session from another folder?
+
+Save it once with `/dogear my-label` (or `dogear add` from a terminal). From
+then on, `dogear open my-label` works from any directory: dogear changes to the
+folder the session was started in and runs `claude --resume <id>` there.
+
+### How do I resume a Codex session?
+
+The same way. `$dogear my-label` inside Codex (after `dogear setup codex`), or
+`dogear add` from a terminal, saves it; `dogear open my-label` runs
+`codex resume <id>` in the right folder. Claude Code and Codex sessions share
+one list.
+
+### How do I save or bookmark a Claude Code session?
+
+Inside the session, type `/dogear` with an optional name, tags or a note, in
+flags or plain words: `/dogear jobs-api -t work` or `/dogear save it as jobs-api, tag work`.
+From a terminal, `dogear add` lets you pick from your 50 most recent sessions.
+
+### How is this different from `claude --resume` or `codex resume`?
+
+Those pickers list every past session; dogear is the short list you chose to
+keep, with names you'll remember, across both agents, and it starts each
+session from the right folder. It uses the agents' own resume commands, so
+nothing about the sessions themselves changes.
+
+### Does dogear upload or modify my sessions?
+
+No. It only reads the agents' files, never writes to them (except installing
+the in-session command when you run `dogear setup`), and makes no network
+requests.
+
+## Development
+
+```sh
+uv sync
+uv run pytest
+```
+
+Tests use synthetic fixtures only; they never read your real `~/.claude` or `~/.codex`.
+
+## License
+
+MIT

dogear-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "dogear"
+dynamic = ["version"]
+description = "Bookmark, save and resume Claude Code and Codex sessions from any folder: a tiny session manager with names, tags and notes."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Oriol Martí" }]
+keywords = [
+    "claude-code", "claude", "anthropic", "codex", "codex-cli", "openai-codex",
+    "sessions", "session-manager", "resume", "bookmark", "bookmarks", "cli", "ai-agents",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development",
+    "Topic :: Utilities",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/orimarti/dogear"
+Issues = "https://github.com/orimarti/dogear/issues"
+
+[project.scripts]
+dogear = "dogear.cli:main"
+
+[dependency-groups]
+dev = ["pytest>=8"]
+
+[tool.hatch.version]
+path = "src/dogear/__init__.py"
+
+[tool.hatch.build.targets.sdist]
+only-include = ["src", "tests", "README.md", "LICENSE", "pyproject.toml"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/dogear"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

dogear-0.1.0/src/dogear/__init__.py

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

dogear-0.1.0/src/dogear/__main__.py

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

dogear-0.1.0/src/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-0.1.0/src/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]