docs: add README and MIT license
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>main
Elijah Voigt
2 months ago
parent
361c2cb99c
commit
7f321060f5
@ -0,0 +1,21 @@
|
|||||||
|
MIT License
|
||||||
|
|
||||||
|
Copyright (c) 2026 Elijah Voigt
|
||||||
|
|
||||||
|
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||||
|
of this software and associated documentation files (the "Software"), to deal
|
||||||
|
in the Software without restriction, including without limitation the rights
|
||||||
|
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||||
|
copies of the Software, and to permit persons to whom the Software is
|
||||||
|
furnished to do so, subject to the following conditions:
|
||||||
|
|
||||||
|
The above copyright notice and this permission notice shall be included in all
|
||||||
|
copies or substantial portions of the Software.
|
||||||
|
|
||||||
|
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||||
|
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||||
|
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||||
|
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||||
|
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||||
|
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||||
|
SOFTWARE.
|
||||||
@ -0,0 +1,156 @@
|
|||||||
|
# claudbg
|
||||||
|
|
||||||
|
A CLI tool for inspecting [Claude Code](https://claude.ai/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](https://rustup.rs)
|
||||||
|
|
||||||
|
### From source
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git clone https://github.com/pop/claudbg
|
||||||
|
cd claudbg
|
||||||
|
cargo install --path .
|
||||||
|
```
|
||||||
|
|
||||||
|
### With Nix flakes
|
||||||
|
|
||||||
|
```bash
|
||||||
|
nix run github:pop/claudbg
|
||||||
|
```
|
||||||
|
|
||||||
|
Or add to your flake inputs and install into your profile:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
inputs.claudbg.url = "github:pop/claudbg";
|
||||||
|
```
|
||||||
|
|
||||||
|
## Usage
|
||||||
|
|
||||||
|
### Listing sessions
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 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.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 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.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 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:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 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](https://nixos.wiki/wiki/Flakes) for a reproducible dev environment:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
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](LICENSE)
|
||||||
Loading…
Reference in New Issue