# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

`claudbg` is a Rust CLI tool for inspecting Claude Code sessions. It reads JSONL session files from `~/.claude/projects/`, caches them in a local libsql database (`~/.claude/claudbg.db`), and exposes commands to list, dump, and transcribe sessions and sub-agent runs.

## Development Environment

The project uses Nix flakes with [crane](https://github.com/ipetkov/crane) for building. Enter the dev shell before working:

```bash
nix develop
```

The dev shell provides: `rustToolchain` (stable + rust-analyzer + clippy), `cargo-watch`, `cargo-edit`, `clang`, `beans`, `jq`.

Use `jq` for all JSON processing in shell commands — do not use `python3`.

## Common Commands

```bash
# Build
cargo build

# Run
cargo run -- <args>

# Tests
cargo test

# Single test
cargo test <test_name>

# Watch mode (rebuild on changes)
cargo watch -x build
cargo watch -x test

# Lint (deny warnings — same as CI)
cargo clippy --all-targets -- --deny warnings

# Format check
cargo fmt --check

# Format fix
cargo fmt

# Run all checks via Nix (matches CI)
nix flake check
```

## Planned Architecture

The v0.1.0 milestone targets a working session inspector with these layers, in dependency order:

### 1. CLI Foundation (`src/main.rs`, `src/cli/`)
- `clap` (derive) wires top-level subcommands: `sessions`, `agents`, `index`, `tui`, `query`
- Global flags on every command: `--output [table|json|xml]` (default: table), `--verbose`, `--include <thinking,output,tools>` (default: tools)
- `AppError` enum + `Result<T>` alias using `thiserror`
- Short UUID display utility (8-char prefix)

### 2. Data Parsing & Models (`src/models/`)
- Rust types (serde-deserializable) for the full JSONL schema:
  - `SessionEntry` enum: `user` / `assistant` / `system` / `progress` / `file-history-snapshot` / `queue-operation`
  - `AssistantContent` enum: `text` / `thinking` / `tool_use`
  - `UserContent` enum: `text` / `tool_result` / `image`
  - `Usage`, `ToolUseInput`, `SystemMessage` subtypes
- Session file discovery: walk `~/.claude/projects/`, URL-decode directory names to recover project paths, return `SessionRef { session_id, project_path, file_path, modified_at }`
- Sub-agent file discovery (parallel structure)
- JSONL line-by-line reader
- `SessionStats` computation: token counts, tool call breakdown by name, duration, model

### 3. Database & Caching (`src/db/`)
- libsql (local file, async via tokio) at `~/.claude/claudbg.db`
- **Normalized tables**: `sessions`, `messages`, `tool_uses` — used for queries and list views
- **Denormalized table**: `raw_sessions (session_id PK, raw_jsonl TEXT, file_mtime, file_size)` — used for fast dump
- **Lazy sync**: on any read command, check `file_mtime`/`file_size` against DB; re-parse and upsert if stale
- **`index` subcommand**: force full resync of all discovered session files
- `--clear` flag: drops and recreates the DB

### 4. Output Formatting (`src/output/`)
- Trait-based renderers behind the `--output` flag
- **Table** (default): `comfy-table` (in use — `render_table` in `src/output/table.rs`)
- **JSON**: `serde_json` pretty-print
- **XML**: hand-rolled or quick-xml

### 5. Sessions Commands (`src/commands/sessions/`)
- `sessions list`: sorted most-recent-first; columns: short session ID, date, project path, model, message count; `--verbose` shows full UUID
- `sessions dump <id>`: table rows — `#`, timestamp, type, role, content preview (truncated); `--verbose` shows full content; accepts 8-char prefix or full UUID
- `sessions transcribe <id>`: header with `SessionStats`, then chat log (user text, assistant text/tool-use blocks, thinking blocks gated by `--include thinking`, tool output gated by `--include output`)
- `--follow` flag: watch the session file and stream new entries as they arrive

### 6. Agents Commands (`src/commands/agents/`)
- Mirror of sessions commands but for sub-agent JSONL files
- `agents list <session-id>`, `agents dump <session-id> <agent-id>`, `agents transcribe`, `--follow`
- **Note:** `discover_agents_for_session(session_file)` must look in `session_file.stem()/subagents/`, not `session_file.parent()/subagents/`

### 7. Stub Commands
- `tui`: prints "coming soon!"
- `query`: prints "coming soon!"

## Key Design Decisions

- Session IDs are UUIDs; display as 8-char prefixes by default, full with `--verbose`
- `~/.claude/projects/` directory names are URL-encoded project paths (e.g. `-run-media-pop-...` → `/run/media/pop/...`)
- The DB acts as a read-through cache; the JSONL files on disk are the source of truth
- All async runtime: tokio (full)
- Dependency crate choices (from beans tickets): `clap` (derive), `tokio` (full), `serde` + `serde_json`, `libsql`, `chrono`, `uuid`, `thiserror`, `comfy-table` or `tabled`

## JSONL Schema Notes

- Field names in Claude Code JSONL are **camelCase** — serde fields need `#[serde(rename = "...")]`:
  - `durationMs` (not `duration_ms`) — on top-level `system` entries
  - `sessionId` (not `session_id`) — on all entries
  - `parentUuid`, `promptId`, `gitBranch`, etc.
- Sub-agent files live at `<project-dir>/<session-uuid>/subagents/agent-<id>.jsonl` — the session UUID is **also a directory** alongside `<session-uuid>.jsonl`; `subagents/` is inside that directory, not next to the `.jsonl`

## Issue Tracking

This project uses `beans` for issue tracking. Always use `beans` instead of TodoWrite for task management. See `beans --help` for usage.