claudex

Query, search, and analyze Claude Code sessions from the command line.

claudex reads the JSONL transcripts Claude Code writes under ~/.claude/projects/, indexes them into a local SQLite database at ~/.claudex/index.db, and exposes reports as subcommands. Every read command supports --json for machine-readable output; most also support --no-index to bypass the index and scan files directly.

📚 Docs: https://utensils.io/claudex/ — guide, per-command reference, index schema, pricing.

---

Quickstart

claudex summary                  # dashboard: sessions, cost, top projects, model mix
claudex sessions --limit 10      # recent sessions
claudex session 3f2a1b          # drill into one session (ID prefix or project name)
claudex search "migration"       # full-text search across all transcripts
claudex cost --per-session       # token & cost breakdown
claudex export 3f2a1b --format markdown > session.md

See the flag support matrix for per-command --json / --no-index coverage.

Install

Pick one. All three paths are covered in depth in the installation guide — pinning, module inputs, verification.

Install script — macOS + Linux

curl -fsSL https://raw.githubusercontent.com/utensils/claudex/main/install.sh | sh

Fetches a prebuilt, stripped, SHA256-verified binary into ~/.local/bin/claudex. Override with CLAUDEX_VERSION=v0.3.0 or CLAUDEX_INSTALL_DIR=/usr/local/bin.

Cargo

cargo install --git https://github.com/utensils/claudex --tag v0.3.0 claudex

Nix flake

nix run     github:utensils/claudex -- summary    # run without installing
nix profile install github:utensils/claudex       # install into user profile
nix build   github:utensils/claudex               # build locally → ./result/bin/claudex

As a flake input:

inputs.claudex.url = "github:utensils/claudex";

Source builds require Rust 1.95+. Prebuilt binaries have no runtime dependencies.

Subcommands

Command	What it does
summary	Dashboard — sessions, cost, top projects/tools, model mix
sessions	List sessions grouped by project
session <selector>	Drill into one session: cost, tools, files, PRs, turns, stop reasons
cost	Token usage and approximate cost per project or per session
search <query>	Full-text search across session messages (FTS5), with JSON hits
tools	Tool usage frequency
models	Per-model call counts, token usage, and cost
turns	Per-turn timing (avg / p50 / p95 / max)
prs	Sessions linked to pull requests
files	Most frequently modified files across sessions
export <selector>	Export a session transcript as Markdown or JSON
watch	Tail Claude Code's debug log in real time
index	Manage the session index (normally updated automatically)
update	Self-update claudex, or print the right upgrade recipe for Nix/cargo/brew
completions <shell>	Generate shell completions (bash, zsh, fish, elvish, powershell)

Global flag: --color auto|always|never (respects NO_COLOR).

Documentation

• Quickstart — first five minutes.
• How it works — data flow, modules, key invariants.
• The index — sync semantics, staleness window.
• JSON output — stable shapes for pipelines.
• Recipes — copy-paste one-liners.
• Reference — file layout, index schema, pricing.

Development

git clone https://github.com/utensils/claudex
cd claudex
nix develop        # auto via direnv + use_flake
ci-local           # fmt-check → check → clippy → test → build

Additional commands: coverage runs cargo llvm-cov (pass --html for a browsable report). See CLAUDE.md for the full development guide.

License

MIT — see LICENSE.