Skip to content

Session Inspection

Random-access into individual Claude Code conversation sessions — browsing, search, context expansion, git commit extraction

Details

Random-access into individual Claude Code conversation sessions. Provides paginated browsing, context expansion, and bridging from IR search hits to message-level results.

For the find-a-prior-conversation-by-topic flow, the system is layered. The top layer (summary_search) ranks compressed summaries and auto-drills via session_search; for very recent sessions (cron is 2h-cadence), error-status summaries, or exact-substring needles, fall back to context_search(source="conversation") against raw spans. The directions at context/session-identify (/wb-session-identify) recipe the full pattern; disclosure/ carries the broader find → walk → read decision rule.

The capabilities below are the leaf-level building blocks for reading session contents once a session id is in hand:

  • Find which sessions mention X: summary_search(query, scope="conversation_session") (preferred — ranks against compressed layer, drills via session_search); or context_search(query, source="conversation") for raw-span search.
  • Browse a session's messages: session_get(session_id, optional limit/offset/query/roles/message_types).
  • Find messages within a known session: session_get(session_id, query=...) (substring filter) or session_search(session_id, query=...) (BM25 + dense within one session, resolves spans to turn indices).
  • Read full text around a message: session_expand(session_id, message_index, span).
  • Jump from a search hit to a turn: session_locate(session_id, span_index).
  • Pivot from a summary_search hit to walk the tree: drill_tree(domain="summary", node_id=hit['drill_node_id'], depth=...).
  • Git commits from agent sessions: session_commits(optional days). Pair with context_git(annotate=true) for git context tagged by session.
  • Resume a session locally: session_resume (registered in the sidecar category) opens a new terminal running claude --resume <id> without sending a prompt. cwd auto-derived via get_session_cwd. Also exposed on the dashboard as a Resume button in each chat's header.

Session ID resolution: All IDs are 36-char UUIDs. All session_* capabilities accept partial prefix IDs (8 chars is canonical short form). Three helpers on the same shape: - resolve_session_id(partial) returns full UUID. - resolve_session_path(partial) returns (Path, full_uuid). - get_session_cwd(partial) returns the working directory the session ran in (scanned from the first JSONL record carrying a cwd field), or None. Used by session_resume and begin_session to open the terminal in the right place.

resolve_session_id and resolve_session_path raise FileNotFoundError on zero or ambiguous matches; get_session_cwd returns None instead of raising. Convention: store full UUIDs in data, truncate to 8 chars only at display boundaries.

Architecture: ConversationSession wraps a JSONL session file with lazy-loaded in-memory indexed turn list (via iter_session_turns from chat_collector.py). Span-to-turn mapping replays the IR chunking algorithm for reliable session_locate. Metadata: message count, duration, timestamps, tool usage summary.

Git commit extraction: session_commits parses raw JSONL entries (bypassing iter_session_turns which drops tool I/O) to find Bash tool calls containing git commit and their results. build_session_map(days) returns {short_hash: full_session_id} for joining with git_collector output. context_git(annotate=true) uses this map to tag commit lines.

Files: inspector.py (ConversationSession class, session ID + cwd resolvers, commit extraction, 6 gateway handlers), __init__.py (empty package init).