https://github.com/utensils/claudex
Query, search, and analyze Claude Code sessions.
https://github.com/utensils/claudex
anthropic claude claude-code cli developer-tools fts5 observability rust session-analysis sqlite
Last synced: 24 days ago
JSON representation
Query, search, and analyze Claude Code sessions.
- Host: GitHub
- URL: https://github.com/utensils/claudex
- Owner: utensils
- License: mit
- Created: 2026-04-18T05:07:34.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-05-30T17:11:14.000Z (24 days ago)
- Last Synced: 2026-05-30T17:11:18.164Z (24 days ago)
- Topics: anthropic, claude, claude-code, cli, developer-tools, fts5, observability, rust, session-analysis, sqlite
- Language: Rust
- Homepage: https://utensils.io/claudex/
- Size: 325 KB
- Stars: 1
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# claudex
[](https://github.com/utensils/claudex/actions/workflows/ci.yml)
[](https://github.com/utensils/claudex/actions/workflows/pages.yml)
[](https://codecov.io/gh/utensils/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. It can also summarize OpenAI Codex CLI state from `~/.codex`. Every read command supports `--json` for machine-readable output; most Claude Code reports also support `--no-index` to bypass the index and scan files directly.
📚 **Docs:** — guide, per-command reference, index schema, pricing.
---
## Quickstart
```bash
claudex summary # dashboard: sessions, cost, top projects, model mix
claudex summary --plan flat-monthly:250 # reframe cost for a flat subscription (Pro/Pro Max)
claudex codex # Codex CLI session/state stats
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](https://utensils.io/claudex/commands/) for per-command `--json` / `--no-index` coverage.
## Install
Pick one. All four paths are covered in depth in the [installation guide](https://utensils.io/claudex/guide/installation) — pinning, module inputs, verification.
### Install script — macOS + Linux
```bash
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.5.2` or `CLAUDEX_INSTALL_DIR=/usr/local/bin`.
### Cargo
```bash
cargo install --git https://github.com/utensils/claudex --tag v0.5.2 claudex
```
### AUR — Arch Linux
```bash
paru -S claudex-bin # prebuilt binary (fastest)
paru -S claudex # build from source
paru -S claudex-git # track main HEAD
```
Maintained in-tree at [`packaging/aur/`](./packaging/aur/) and auto-published on every release.
### Nix flake
```bash
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:
```nix
inputs.claudex.url = "github:utensils/claudex";
```
Source builds require Rust 1.95+. Prebuilt binaries have no runtime dependencies.
## Subcommands
| Command | What it does |
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| [`summary`](https://utensils.io/claudex/commands/summary) | Dashboard — sessions, cost, top projects/tools, model mix |
| [`codex`](https://utensils.io/claudex/commands/codex) | Codex CLI session/state stats from `~/.codex` |
| [`sessions`](https://utensils.io/claudex/commands/sessions) | List sessions grouped by project |
| [`session `](https://utensils.io/claudex/commands/session) | Drill into one session: cost, tools, files, PRs, turns, stop reasons |
| [`cost`](https://utensils.io/claudex/commands/cost) | Token usage and approximate cost per project or per session |
| [`search `](https://utensils.io/claudex/commands/search) | Full-text search across session messages (FTS5), with JSON hits |
| [`tools`](https://utensils.io/claudex/commands/tools) | Tool usage frequency |
| [`models`](https://utensils.io/claudex/commands/models) | Per-model call counts, token usage, and cost |
| [`turns`](https://utensils.io/claudex/commands/turns) | Per-turn timing (avg / p50 / p95 / max) |
| [`prs`](https://utensils.io/claudex/commands/prs) | Sessions linked to pull requests |
| [`files`](https://utensils.io/claudex/commands/files) | Most frequently modified files across sessions |
| [`export `](https://utensils.io/claudex/commands/export) | Export a session transcript as Markdown or JSON |
| [`watch`](https://utensils.io/claudex/commands/watch) | Tail Claude Code's debug log in real time |
| [`index`](https://utensils.io/claudex/commands/index-cmd) | Manage the session index (normally updated automatically) |
| [`update`](https://utensils.io/claudex/commands/update) | Self-update claudex, or print the right upgrade recipe for Nix/cargo/brew |
| [`completions `](https://utensils.io/claudex/commands/completions) | Generate shell completions (bash, zsh, fish, elvish, powershell) |
Global flag: `--color auto|always|never` (respects `NO_COLOR`).
## Documentation
- [Quickstart](https://utensils.io/claudex/guide/quickstart) — first five minutes.
- [How it works](https://utensils.io/claudex/guide/architecture) — data flow, modules, key invariants.
- [The index](https://utensils.io/claudex/guide/indexing) — sync semantics, staleness window.
- [JSON output](https://utensils.io/claudex/guide/json-output) — stable shapes for pipelines.
- [Recipes](https://utensils.io/claudex/guide/recipes) — copy-paste one-liners.
- [Reference](https://utensils.io/claudex/reference/) — file layout, index schema, pricing.
## Development
```bash
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](CLAUDE.md) for the full development guide.
## License
MIT — see [LICENSE](LICENSE).