--- name: cqs description: "Unified cqs CLI dispatcher — semantic code search, call graph navigation, impact analysis, quality tools, notes, and infrastructure. Use `/cqs [args]` for any cqs operation." disable-model-invocation: false argument-hint: " [args...]" --- # cqs — Unified CLI Dispatcher Parse the first argument as the command name, pass remaining arguments as flags. Run via Bash: `cqs --json -q 2>/dev/null` Present results to the user. --- ## Search & Discovery ### search `` — Semantic code search Finds functions by concept, not text. Use instead of grep/glob. ``` cqs "" [flags] --json -q ``` | Flag | Description | |------|-------------| | `--lang ` | Filter by language (rust, python, typescript, javascript, go, c, java, sql, markdown) | | `-n/--limit ` | Max results (default 5, max 20) | | `-t/--threshold ` | Similarity threshold (default 0.3) | | `--name-only` | Definition lookup, skips embedding | | `--semantic-only` | Pure vector similarity, no hybrid RRF | | `--rerank` | Cross-encoder re-ranking (slower, more accurate) | | `-p/--path ` | Path pattern filter (e.g., `src/cli/**`) | | `--include-type ` | Include only: function, method, class, struct, test, endpoint, etc. | | `--exclude-type ` | Exclude: test, variable, configkey, etc. | | `--pattern

` | Pattern: builder, error_swallow, async, mutex, unsafe, recursion | | `--note-only` | Return only notes | | `--note-weight ` | Note score weight 0.0-1.0 (default 1.0) | | `--ref ` | Search only this reference index | | `--tokens ` | Token budget (greedy knapsack by score) | | `--expand` | Parent context (small-to-big retrieval) | | `-C/--context ` | Lines of context around chunk | | `--no-content` | File:line only, no code | | `--no-stale-check` | Skip per-file staleness checks | ### similar `` — Find similar code Find code similar to a given function. Refactoring discovery, duplicates. ``` cqs similar "" --json -q ``` ### gather `` — Smart context assembly Seed search + BFS call graph expansion. "Show me everything related to X." ``` cqs gather "" [flags] --json 2>/dev/null ``` | Flag | Description | |------|-------------| | `--expand ` | BFS depth (default 1, max 5) | | `--direction ` | both, callers, callees (default both) | | `-n/--limit ` | Max results (default 10) | | `--tokens ` | Token budget | | `--ref ` | Cross-index: seed from reference, bridge into project | ### where `` — Placement suggestion Where to add new code based on semantic similarity and local patterns. ``` cqs where "" --json -q ``` ### scout `` — Pre-investigation dashboard Search + callers/tests + staleness + notes in one call. First step for new tasks. ``` cqs scout "" [-n N] [--tokens N] --json 2>/dev/null ``` ### task `` — Implementation brief Scout + gather + impact + placement + notes. Waterfall token budgeting (scout 15%, code 50%, impact 15%, placement 10%, notes 10%). ``` cqs task "" [-n N] [--tokens N] --json 2>/dev/null ``` ### onboard `` — Guided codebase tour Entry point + call chain + callers + types + tests. Ordered reading list. ``` cqs onboard "" [-d/--depth N] [--tokens N] --json 2>/dev/null ``` ### read `` — File with contextual notes File contents with notes injected as comments. Richer than raw Read. ``` cqs read [--focus ] --json -q ``` `--focus ` returns only the target function + type dependencies. ### context `` — Module overview Chunks, callers, callees, notes for a file. ``` cqs context --json -q ``` ### explain `` — Function card Signature, docs, callers, callees, similar in one call. ``` cqs explain "" --json -q ``` --- ## Call Graph ### callers `` — Who calls this? ``` cqs callers "" --json -q ``` ### callees `` — What does this call? ``` cqs callees "" --json -q ``` ### trace `` `` — Shortest call path BFS shortest path between two functions. ``` cqs trace "" "" --json -q ``` ### deps `` — Type dependencies Forward: who uses this type? Reverse (`--reverse`): what types does this function use? ``` cqs deps "" [--reverse] --json -q ``` ### related `` — Co-occurrence Functions sharing callers, callees, or types. ``` cqs related "" --json -q ``` ### impact `` — What breaks if you change X? Callers with snippets + affected tests via reverse BFS. ``` cqs impact "" [--depth N] [--suggest-tests] --json -q ``` ### impact-diff — Diff-aware impact analysis Changed functions, affected callers, tests to re-run. ``` cqs impact-diff [--base ] [--stdin] [--json] [--tokens N] ``` ### test-map `` — Map function to tests Tests that exercise a function via reverse call graph. ``` cqs test-map "" --json -q ``` --- ## Quality & Review ### dead — Find dead code Functions/methods with no callers. ``` cqs dead [--include-pub] [--min-confidence low|medium|high] --json -q ``` ### stale — Index freshness Files modified since last index. ``` cqs stale --json -q ``` ### 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 ] [--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 ] [--stdin] [--json] [--tokens N] ``` ### suggest — Auto-suggest notes Scan for dead code clusters, untested hotspots, high-risk functions. ``` cqs suggest [--apply] [--json] ``` ### gc — Report staleness Report/clean stale index entries. ``` cqs gc --json -q ``` ### stats — Index statistics Chunk counts, languages, last update. ``` cqs stats --json -q ``` --- ## Notes ### notes add `` — Add a note ``` cqs notes add "" [--sentiment N] [--mentions a,b,c] -q ``` Sentiment: -1 (serious pain), -0.5 (notable pain), 0 (neutral), 0.5 (notable gain), 1 (major win). ### notes update `` — Update a note ``` cqs notes update "" [--new-text "..."] [--new-sentiment N] -q ``` ### notes remove `` — Remove a note ``` cqs notes remove "" -q ``` ### 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 [--weight 0.8]` | Index external codebase (weight 0.0-1.0) | | `ref list` | Show all references | | `ref update ` | Re-index reference | | `ref remove ` | Delete reference | ### watch — File watcher Keep index fresh automatically. ``` cqs watch [--debounce ] [--no-ignore] ``` ### convert `` — Document conversion PDF/HTML/CHM/MD to cleaned Markdown. ``` cqs convert [--output

] [--overwrite] [--dry-run] [--clean-tags ] ``` Tags: `aveva`, `pdf`, `generic`. ### diff `` — Semantic diff Compare indexed snapshots. Requires references via `ref add`. ``` cqs diff "" [target] [--threshold F] [--lang L] --json -q ``` ### drift `` — Semantic drift detection Embedding distance between same-named functions across snapshots. ``` cqs drift "" [--min-drift 0.1] [--lang L] [--limit N] --json ```