Skip to content

Session Inspection

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

Entry points

  • work_buddy.sessions.inspector

Details

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

When to use what: - Find which sessions mention X: context_search (then drill in) - Browse a session's messages: session_get with session_id + optional limit/offset/query/roles/message_types - Find messages in a known session: session_get with query param (substring filter) - Read full text around a message: session_expand with session_id + message_index - Jump from search hit to conversation: session_locate with session_id + span_index - Semantic/keyword search within session: session_search with session_id + query - Git commits from agent sessions: session_commits with optional days param - Git context with session attribution: context_git with annotate=true

Session ID resolution: All IDs are 36-char UUIDs. All session_* capabilities accept partial prefix IDs (8 chars is canonical short form). Two resolvers: resolve_session_id(partial) returns full UUID, resolve_session_path(partial) returns (Path, full_uuid). Both raise FileNotFoundError on zero or ambiguous matches. 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 with annotate=true uses this map to tag commit lines.

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