Skip to content
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.

More tools from this site

  • claudestream Drive Claude Code from Python: run it as a subprocess and read its output as typed events, with async and sync sessions, sandbox policies, and tools you define in Python
  • dirstat Fast, single-binary directory statistics CLI: every file under a tree grouped by format, with counts, sizes, and lines of code, as a colored terminal table or as JSON
  • fastware A batteries-included ASGI framework: msgspec JSON, a managed Granian server, dependency injection, SSE, WebSockets, auth, and a test client
  • go-toml-edit Zero-dep TOML editing library for Go with comment preservation
  • howmuchleft The fastest Claude Code statusline: context window, 5-hour, and weekly limit usage as three customizable gradient bars, rendering in about 6 ms
  • orxtra
  • pgdesign
  • predraw Declarative rendering pipeline: describe a scene in JSON and get SVG, PNG and WebP out, with light and dark style tokens, reusable components and text converted to path outlines
  • reposummary Turn a git repository's history into a Markdown journal: pick a time window or revision range and get a readable digest of what changed, optionally narrated by an LLM
  • rlsbl Release orchestration and project scaffolding CLI that bumps versions, validates a structured JSONL changelog, tags only the commit CI verified, and publishes to npm, PyPI, Go and more
  • safegit git wrapper CLI that gives each commit its own temporary index and retries ref updates on conflict, so concurrent agents share one repository
  • saferm Command-line replacement for rm that archives every deletion with a mandatory reason and the context it ran in, so deleted files can be listed, inspected and restored
  • selfdoc Static Site Generator that builds a project's documentation site directly from its source code, so the docs can never drift from the code they describe, with SEO/AEO, first-class blog, search, and cross-project linking built in
  • strictcli
  • stricttest An always-on test-isolation floor: a pytest plugin and a Go env-hygiene module that make a test suite structurally unable to reach real credentials, the real HOME, the network, or the development repository.
  • wesktop A Python framework that turns an ASGI web app into a desktop application, serving it from a local Granian server and displaying it in a native OS window via pywebview
Search