cqs — Unified CLI Dispatcher

Parse the first argument as the command name, pass remaining arguments as flags.

Run via Bash: cqs <command> <args> --json 2>/dev/null

-q/--quiet exists ONLY on top-level search (cqs "query" -q) — subcommands reject it. Use 2>/dev/null to suppress tracing noise instead.

Present results to the user.

---

Search & Discovery

search <query> — Semantic code search

Finds functions by concept, not text. Use instead of grep/glob. Default path is dense cosine + SPLADE sparse fusion with per-category routing (RRF keyword fusion is opt-in via --rrf).

cqs "<query>" [flags] --json -q

Flag	Description
-l/--lang <L>	Filter by language (rust, python, typescript, javascript, go, c, java, sql, markdown)
-n/--limit <N>	Max results (default 5; --limit 0 rejected)
-t/--threshold <N>	Similarity threshold (default 0.3)
--name-only	Definition lookup, skips embedding
--rrf	Enable RRF hybrid search (keyword + semantic fusion); off by default
--splade / --splade-alpha <F>	Force SPLADE on for unknown-category queries / pin fusion weight (1.0 = pure cosine)
--reranker <none|onnx>	Cross-encoder re-ranking (default none; opt-in, measured net-negative on the standing eval)
--include-docs	Include markdown/config chunks (default: code only)
--no-demote	Disable demotion of test functions and underscore-prefixed names
-p/--path <glob>	Path pattern filter (e.g., src/cli/**)
--include-type <T>	Include only: function, method, class, struct, test, endpoint, etc.
--exclude-type <T>	Exclude: test, variable, configkey, etc.
--pattern <P>	Pattern: builder, error_swallow, async, mutex, unsafe, recursion
--name-boost <F>	Weight for name matching in hybrid search 0.0-1.0 (default 0.2)
--ref <name>	Search only this reference index (--include-refs to merge refs in)
--tokens <N>	Token budget (greedy knapsack by score)
--expand-parent	Parent type/module context (small-to-big retrieval)
-C/--context <N>	Lines of context around chunk
--no-content	File:line only, no code
--no-stale-check	Skip per-file staleness checks
--model <M>	Query embedder override (embeddinggemma-300m default)

similar <function> — Find similar code

Find code similar to a given function. Refactoring discovery, duplicates.

cqs similar "<name>" --json

gather <query> — Smart context assembly

Seed search + BFS call graph expansion. "Show me everything related to X."

cqs gather "<query>" [flags] --json 2>/dev/null

Flag	Description
-d/--depth <N> (alias --expand)	BFS depth (default 1, max 5)
--direction <D>	both, callers, callees (default both)
-n/--limit <N>	Max seed results (default 5)
--tokens <N>	Token budget
--ref <name>	Cross-index: seed from reference, bridge into project

where <description> — Placement suggestion

Where to add new code based on semantic similarity and local patterns.

cqs where "<description>" --json

scout <task> — Pre-investigation dashboard

Search + callers/tests + staleness + notes in one call. First step for new tasks.

cqs scout "<task>" [-n N] [--tokens N] --json 2>/dev/null

task <description> — Implementation brief

Scout + gather + impact + placement + notes. Waterfall token budgeting (scout 15%, code 50%, impact 15%, placement 10%, notes 10%).

cqs task "<description>" [-n N] [--tokens N] --json 2>/dev/null

onboard <concept> — Guided codebase tour

Entry point + call chain + callers + types + tests. Ordered reading list.

cqs onboard "<concept>" [-d/--depth N] [--tokens N] --json 2>/dev/null

read <path> — File with contextual notes

File contents with notes injected as comments. Richer than raw Read.

cqs read <path> [--focus <function>] --json

--focus <function> returns only the target function + type dependencies.

context <file> — Module overview

Chunks, callers, callees, notes for a file.

cqs context <file> --json

explain <function> — Function card

Signature, docs, callers, callees, similar in one call.

cqs explain "<name>" --json

---

Call Graph

callers <function> — Who calls this?

cqs callers "<name>" --json

callees <function> — What does this call?

cqs callees "<name>" --json

trace <source> <target> — Shortest call path

BFS shortest path between two functions.

cqs trace "<source>" "<target>" --json

deps <name> — Type dependencies

Forward: who uses this type? Reverse (--reverse): what types does this function use?

cqs deps "<name>" [--reverse] --json

related <function> — Co-occurrence

Functions sharing callers, callees, or types.

cqs related "<name>" --json

impact <function> — What breaks if you change X?

Callers with snippets + affected tests via reverse BFS.

cqs impact "<name>" [--depth N] [--suggest-tests] --json

impact-diff — Diff-aware impact analysis

Changed functions, affected callers, tests to re-run.

cqs impact-diff [--base <ref>] [--stdin] [--json] [--tokens N]

test-map <function> — Map function to tests

Tests that exercise a function via reverse call graph.

cqs test-map "<name>" --json

---

Quality & Review

dead — Find dead code

Functions/methods with no callers.

cqs dead [--include-pub] [--min-confidence low|medium|high] --json

stale — Index freshness

Files modified since last index.

cqs stale --json

health — Codebase quality snapshot

Stats + dead code + staleness + hotspots + untested hotspots + notes.

cqs health [--json]

ci — CI pipeline analysis

Review + dead code + gate logic. Exit 3 on gate fail.

cqs ci [--base <ref>] [--stdin] [--gate high|medium|off] [--json] [--tokens N]

review — Comprehensive diff review

Impact + notes + risk scoring + staleness. More detailed than ci (no gate).

cqs review [--base <ref>] [--stdin] [--json] [--tokens N]

suggest — Auto-suggest notes

Scan for dead code clusters, untested hotspots, high-risk functions.

cqs suggest [--apply] [--json]

gc — Garbage-collect the index

Removes stale chunks and rebuilds the vector index. MUTATING — not a report-only command.

cqs gc --json

stats — Index statistics

Chunk counts, languages, last update.

cqs stats --json

---

Notes

notes add <text> — Add a note

cqs notes add "<text>" [--sentiment N] [--mentions a,b,c]

Sentiment: -1 (serious pain), -0.5 (notable pain), 0 (neutral), 0.5 (notable gain), 1 (major win).

notes update <exact text> — Update a note

cqs notes update "<exact text>" [--new-text "..."] [--new-sentiment N]

notes remove <exact text> — Remove a note

cqs notes remove "<exact text>"

audit-mode — Toggle audit mode

Excludes notes from search/read for unbiased review.

cqs audit-mode [on|off] [--expires 30m] --json

---

Infrastructure

ref — Reference index management

Manage external codebases for multi-index search.

Subcommand	Usage
ref add <name> <path> [--weight 0.8]	Index external codebase (weight 0.0-1.0)
ref list	Show all references
ref update <name>	Re-index reference
ref remove <name>	Delete reference

watch — File watcher / daemon

Keep index fresh automatically. --serve also answers daemon queries over the socket (3-19ms vs ~2s CLI startup); the systemd service runs cqs watch --serve.

cqs watch [--debounce <ms>] [--no-ignore] [--poll] [--serve]

Daemon & index plumbing

Command	Usage
ping	Daemon healthcheck — model, uptime, counters (cqs ping --json)
status	Watch-mode freshness — is the index caught up (cqs status --json)
refresh	Invalidate daemon caches, re-open the Store
slot list/create/promote/remove/active	Named side-by-side indexes under .cqs/slots/<name>/; --slot <name> on most commands
cache stats/prune/compact	Embeddings cache at .cqs/embeddings_cache.db
model show/list/swap	Embedding model recorded in the index
eval <query_file>	R@K eval harness (cqs eval evals/queries/v3_test.v2.json --json)
telemetry	Usage dashboard — command frequency, categories, sessions
doctor [--fix]	Check model, index, hardware

convert <path> — Document conversion

PDF/HTML/CHM/MD to cleaned Markdown.

cqs convert <path> [--output <dir>] [--overwrite] [--dry-run] [--clean-tags <tags>]

Tags: aveva, pdf, generic.

diff <source> — Semantic diff

Compare indexed snapshots. Requires references via ref add.

cqs diff "<source>" [target] [--threshold F] [--lang L] --json

drift <reference> — Semantic drift detection

Embedding distance between same-named functions across snapshots.

cqs drift "<ref>" [--min-drift 0.1] [--lang L] [--limit N] --json