Discovery & ingestion state
discover()
Every transcript under root, sorted by path.
Usage
discover(root=None)Transcripts live as *.jsonl files under root (defaulting to CLAUDE_PROJECTS_DIR), one directory per project plus subagents/ sidechain files.
Returns
list[Path]-
The transcript paths;
[]when the root does not exist.
Example
>>> for transcript in stream(discover()):
... print(transcript.path)resolve()
Locates session_id’s transcript on disk.
Usage
resolve(session_id, *, root=None)Scans root (defaulting to CLAUDE_PROJECTS_DIR) for <session_id>.jsonl, resolving symlinks — cc-pool gives one transcript several path spellings — and deduping by resolved real path.
A successful lookup is memoized in TRANSCRIPT_MEMO under (session_id, resolved root) and revalidated on the next hit, so a repeated probe skips the recursive scan while a pruned transcript still forces a fresh one. When the projects tree yields nothing, the codex sessions tree is tried as a fallback, so a codex session id resolves too.
Returns
Path | None- The newest-mtime real path, or None when no transcript exists.
find_in()
Finds transcripts under directory newer than known mtimes.
Usage
find_in(directory, *, name_contains=None, limit=None, known_mtimes=None)Parameters
directory: Path-
The directory to search recursively.
name_contains: str | None = None-
When set, keep only files whose name contains it.
limit: int | None = None-
When set, return at most this many paths.
known_mtimes: dict[str, float] | None = None- Map of path string to last-seen mtime; a file is kept only when absent from the map or modified since.
Returns
list[tuple[Path, float]]-
Pairs of
(path, mtime)sorted by path.
subagent_paths()
Sidechain transcript files spawned by the session transcript at path.
Usage
subagent_paths(path)Claude Code writes subagent transcripts as <parent>/<stem>/subagents/agent-<tool_use_id>.jsonl next to the main transcript; macOS resource-fork artifacts (._*) are skipped.
Returns
tuple[Path, …]-
The sidechain files sorted by path;
()when none exist.
TranscriptExpiredError
A session’s transcript file is gone from disk.
Usage
TranscriptExpiredError(session_id)Raised for the file-gone miss mode only — Claude Code prunes transcripts after roughly thirty days. A reference compacted away inside a still-living transcript is a separate miss mode, modeled by lookups such as turn_of() and hydrate() returning None.
Attributes
session_id: SessionId- The session whose transcript has expired.
CLAUDE_PROJECTS_DIR
CLAUDE_PROJECTS_DIR=Path.home() / ".claude" / "projects"