claudbg

A CLI tool for inspecting Claude Code sessions. Reads JSONL session files from ~/.claude/projects/, caches them in a local SQLite database, and lets you list, dump, and transcribe sessions and sub-agent runs.

+----------+--------------------------+----------------------------+-------------------+----------+
| ID       | Date                     | Project                    | Model             | Messages |
+==========================================================================================================================+
| 21fae0a8 | 2026-03-28T20:36:00.417Z | /home/user/my-project      | claude-sonnet-4-6 | 663      |
| 80e9ebac | 2026-03-28T17:45:00.872Z | /home/user/my-project      | claude-sonnet-4-6 | 36       |
| 18b7e801 | 2026-03-28T03:13:13.354Z | /home/user/other-project   | claude-sonnet-4-6 | 239      |
+----------+--------------------------+----------------------------+-------------------+----------+

Features

• List sessions sorted by most recent activity
• Dump raw message entries from any session
• Transcribe sessions as a human-readable chat log
• Inspect sub-agent runs with the same list/dump/transcribe commands
• Live follow (--follow) streams new entries as a session is written
• Multiple output formats: table, JSON, XML
• Local cache with lazy sync — only re-parses files that have changed on disk

Installation

Prerequisites

• Rust (stable) — install via rustup

From source

git clone https://github.com/pop/claudbg
cd claudbg
cargo install --path .

With Nix flakes

nix run github:pop/claudbg

Or add to your flake inputs and install into your profile:

inputs.claudbg.url = "github:pop/claudbg";

Usage

Listing sessions

# Show all sessions, most recent first
claudbg sessions list

# Show full UUIDs and paths
claudbg sessions list --verbose

# Output as JSON
claudbg sessions list --output json

Reading a session

Session IDs can be given as the full UUID or an 8-character prefix.

# Dump raw message entries (sequence, timestamp, type, role, content preview)
claudbg sessions dump 21fae0a8

# Full content, no truncation
claudbg sessions dump 21fae0a8 --verbose

# Human-readable transcript (user/assistant turns, tool calls)
claudbg sessions transcribe 21fae0a8

# Include thinking blocks and tool output in the transcript
claudbg sessions transcribe 21fae0a8 --include thinking,output

# Stream new entries as they are written (e.g. while a session is active)
claudbg sessions transcribe 21fae0a8 --follow

Sub-agent runs

Claude Code uses sub-agents for long-running tasks. claudbg agents mirrors the sessions commands for those runs.

# List all sub-agent runs within a session
claudbg agents list 21fae0a8

# Transcribe a specific sub-agent run
claudbg agents transcribe 21fae0a8 <agent-id>

# Follow a live sub-agent run
claudbg agents transcribe 21fae0a8 <agent-id> --follow

Indexing

The database is kept in sync lazily (on every read command). You can also trigger a full resync manually:

# Sync any changed session files
claudbg index

# Force rebuild of the entire cache
claudbg index --force

Global flags

Flag	Description
--output table|json|xml	Output format (default: table)
--verbose	Show full UUIDs and untruncated content
--include thinking,output	Include thinking blocks and/or tool results in transcripts

Database

claudbg stores its cache at ~/.claude/claudbg.db (libsql/SQLite). The JSONL files under ~/.claude/projects/ are always the source of truth — the database is a read-through cache and can be deleted or rebuilt at any time.

Roadmap

• tui — Terminal UI for browsing sessions interactively
• query — Run ad-hoc SQL against the session cache (claudbg query "SELECT ...")
• Token usage reports — Aggregate cost/usage across sessions and date ranges
• Search — Full-text search across session content
• Export — Export transcripts to Markdown or HTML
• Watch mode — Automatically index new sessions as Claude Code writes them

Development

The project uses Nix flakes for a reproducible dev environment:

nix develop    # enter the dev shell (provides rustup, cargo-nextest, etc.)
cargo build
cargo nextest run
cargo clippy --all-targets -- -D warnings
nix flake check   # runs the full CI suite

License

MIT