| 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 --version
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
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
$BIN sessions --all --limit 3
$BIN sql "SELECT COUNT(*) AS n FROM messages"
$BIN schema --examples
$BIN sessions --all --limit 1 --json
--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
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.
