run-cq

name	run-cq
description	Build, run, test, and smoke-drive cq — the SQL-over-Claude-Code-transcripts CLI (Rust + DuckDB). Use when asked to build cq, run it, try a subcommand, verify a change works end-to-end, or run its tests.

cq is a Rust CLI that indexes Claude Code JSONL session transcripts into a DuckDB cache and queries them with SQL. No server, no UI — you drive it by running subcommands and checking output + exit codes.

Agent path: run .claude/skills/run-cq/smoke.sh — it builds the release binary if missing, then exercises every subcommand against an isolated cache and asserts exit codes (including the error path). All paths below are relative to the repo root.

Verified on macOS (Darwin, arm64). Linux is a first-class target too (CI ships Linux x86_64 + arm64 builds), but the commands below were run on macOS.

Prerequisites

• Rust toolchain (cargo, rustc). Verified with 1.96.
• A C++ compiler. The duckdb crate is pinned with the bundled feature, so it compiles DuckDB from C++ source on first build. macOS: Xcode Command Line Tools (xcode-select --install) provide clang. Ubuntu: sudo apt-get install -y build-essential.

No system DuckDB, no other services. The tool reads ~/.claude/projects/ (or $CQ_PROJECTS_DIR) and writes a cache at ~/.cache/cq/index.duckdb (or $CQ_CACHE_DIR).

Build

cargo build --release
# → target/release/cq  (first build ~4 min: DuckDB compiles from source; later builds are seconds)
./target/release/cq --version
# → cq 0.2.0

Run (agent path)

The smoke driver is the fastest way to confirm a working binary. It uses an isolated CQ_CACHE_DIR under $TMPDIR, so it never touches your real cache:

.claude/skills/run-cq/smoke.sh
# builds if needed, then:
#   ok   version (exit 0)
#   ok   tools summary (exit 0)
#   ...
#   ok   error: bad --count-by (exit 1)
#   ALL CHECKS PASSED

Exit 0 = every check passed. It drives: --version, --help, tools, sessions, messages, projects, sql, schema --examples, --json output, and one deliberate error case that must exit 1.

To poke it by hand (these all ran clean on real session data):

BIN=./target/release/cq
$BIN tools --all --limit 10                          # bar-chart summary of tool usage
$BIN sessions --all --limit 3                        # recent sessions
$BIN sql "SELECT COUNT(*) AS n FROM messages"        # raw SQL over the four views
$BIN schema --examples                               # view schema + example queries (no DB needed)
$BIN sessions --all --limit 1 --json                 # machine-readable output

--all disables auto-scoping to the current directory. Without it, queries scope to the project matching your cwd (from the repo root you'll get cq's own sessions, which may be sparse).

Run (human path)

Same binary, no wrapper: cargo run -- <subcommand>, e.g. cargo run -- tools --limit 5. See README.md and docs/ for the tour.

Test

cargo test
# → 5 suites: lib (57), cache (11), integration (95), views (32), + 0 doc-tests. All pass in ~20s.

Fixtures are handcrafted JSONL under tests/fixtures/; tests don't need your real ~/.claude/projects/ data.

Gotchas

• --all matters for a visible result. cq defaults to auto-scoping to the current directory's project. Run from the repo root without --all and you only see cq's own sessions. Use --all (or --project <name>) to see everything. An over-scoped query prints No results. plus an Active filters: hint — that's exit 0, not a failure.
• First build is slow, and it's the C++, not your code. bundled DuckDB compiles from source (~4 min). If a build hangs on libduckdb-sys, it's compiling, not stuck.
• --reindex waits for the file lock; --no-reindex skips sync entirely. Default (Auto) does an mtime fast-path and skips if the lock is busy, so a concurrent cq won't block you — you just read slightly stale data.
• Writing under .claude/skills/ may hit a sandbox deny rule. If you edit this skill or smoke.sh and the write is refused, that's the tool sandbox, not a permissions bug — .claude/skills is on the deny list. Manage with /sandbox.

Troubleshooting

• Error: Unknown count-by column '<x>' for tools (exit 1) — expected for an invalid --count-by. Valid columns: name, session, project. The smoke driver relies on this exiting non-zero.
• Fresh/empty CQ_CACHE_DIR — first run prints Synced N new files and builds index.duckdb + index.lock from scratch (a couple seconds for ~500 files). Not an error.