claudewheel v0.24.2 /claudewheel.session
Updated Edit
On this page

Session lookup: locate session JSONL files and extract metadata.

#claudewheel.session

#claudewheel.session

Session lookup: locate session JSONL files and extract metadata.

#SessionInfo

Metadata for a single session resolved from the shared store.

#TitleMatch

A session file whose custom-title record matches a requested title.

#OrphanedProject

A project directory in the shared store whose original cwd no longer exists.

#get_session_cwd

python
def get_session_cwd(jsonl_path: Path, max_lines: int=MAX_CWD_SCAN_LINES) -> str | None

Read up to max_lines from a JSONL file and return the first cwd value.

Returns None when the file is missing, empty, or contains no cwd field within the scanned range. Corrupt JSON lines are silently skipped.

#find_session

python
def find_session(session_id: str, shared_projects_dir: Path) -> SessionInfo | None

Locate a session by UUID in the shared projects store.

Globs <shared_projects_dir>/*/<session_id>.jsonl and returns a :class:SessionInfo on the first match (UUIDs are globally unique). Returns None when no matching file exists.

#_find_title_in_file

python
def _find_title_in_file(jsonl_path: Path, title: str) -> str | None

Return the session UUID if jsonl_path holds a matching custom-title.

Scans the file line by line. A cheap substring check on the raw line skips the overwhelming majority of lines (and files) without JSON-parsing them, which matters because real project dirs hold thousands of multi-megabyte JSONL files. Only lines containing :data:CUSTOM_TITLE_MARKER are parsed.

A line matches only when it is a genuine custom-title record whose customTitle equals title exactly. Auto-generated ai-title and agent-name records are ignored (their type is not custom-title). The returned UUID is the record's sessionId when present, else the file stem (Claude Code keeps these identical).

#find_sessions_by_title

python
def find_sessions_by_title(title: str, project_dirs: list[Path]) -> list[TitleMatch]

Find sessions whose user-assigned title equals title exactly.

Scans ONLY the top-level *.jsonl files of each directory in project_dirs (non-recursive, deliberately: subagent session files live two levels deeper under <parent>/subagents/ and must never match a top-level resume). Returns one :class:TitleMatch per matching file, in directory order.

#find_orphaned_project_dirs

python
def find_orphaned_project_dirs(shared_projects_dir: Path) -> list[OrphanedProject]

Find all project dirs whose original cwd no longer exists on disk.

Scans every subdirectory of shared_projects_dir. For each, reads the newest .jsonl file (by mtime) to extract the cwd. If the cwd is not None and no longer exists on disk, the project is included as an :class:OrphanedProject.

Search