diff --git a/src/skill.md b/src/skill.md index b30e0ae..247fd04 100644 --- a/src/skill.md +++ b/src/skill.md @@ -1,46 +1,94 @@ +--- +name: cx +description: Semantic code navigation via the cx CLI — symbol search, definitions, references, file/dir overviews. Use when you have a symbol name or want to orient in unfamiliar code; prefer over reading whole files. +--- + # cx — Semantic Code Navigation -Prefer cx over reading files. Escalate: overview → symbols → definition/references → Read tool. +``` +Usage: cx [OPTIONS] -## Quick reference +Commands: + overview [OPTIONS] Table of contents — symbols + ranges + signatures for a file, or symbol names for a directory + symbols [OPTIONS] Search symbols across project + definition [OPTIONS] --name Get a function/type/... body without reading the whole file (default limit: 3) + references [OPTIONS] --name Find all usages of a symbol across the project + lang [OPTIONS] Manage language grammars (sub-commands: add, remove, list, help) + help [COMMAND] Full command/option list or help on the given subcommand(s) +Options: + --root Project root (defaults to git root) + --json Emit JSON instead of TOON + --no-tests Exclude test files and test symbols from results (`*/tests/* and `*.test.ts`, test_*.py`, ...) +Pagination options: + --limit Max number of results to return (overrides per-command default) + --offset Skip the first N results (not counted against limit) + --all Return all results (bypass default limit) ``` -cx overview PATH file or directory table of contents -cx overview DIR --full directory overview with ranges + signatures -cx symbols [--kind K] [--name GLOB] [--file PATH] search symbols project-wide -cx symbols --kinds [--file PATH] list distinct kinds with counts -cx definition --name NAME [--from PATH] [--kind K] get a function/type body -cx references --name NAME [--file PATH] [--context] usages grouped by file; --context exact lines -cx lang list show supported languages -cx lang add LANG [LANG...] install language grammars -Global: --no-tests (exclude test files/symbols), --json, --limit N, --offset N, --all -``` +Prefer cx over reading files. Zoom in until you have what you need, then stop: +`overview` > `symbols` > `definition` or `references`. -Aliases: `cx o`, `cx s`, `cx d`, `cx r` +Fall back to the Read tool when `cx` can't represent the target (anonymous functions, JSX-inline components, dynamic +dispatch, string-keyed lookups, non-symbol regions). -Kinds: fn, struct, enum, trait, type, const, class, interface, module, event, heading +## First-run checks (once per session) -## Key patterns +1. **Is cx installed?** Run `command -v cx`. If absent, stop and ask the user to install it — do not attempt the install + yourself. Canonical commands: + - Homebrew: `brew tap ind-igo/cx && brew install cx` + - Cargo: `cargo install cx-cli` + - Shell (Linux/macOS): `curl -sL https://raw.githubusercontent.com/ind-igo/cx/master/install.sh | sh` -- Start with `cx overview .`, drill into subdirectories — cheaper than ls + reading files -- `cx definition --name X` gives exact text for Edit tool's `old_string` without reading the whole file -- `cx references --name X` groups hits by file; add `--context` only when exact source lines are needed -- After context compression, use `cx overview` / `cx definition` to re-orient — don't re-read full files -- Check signatures for `pub`/`export` to identify public API without reading the file +2. **Are this project's grammars installed?** Just run `cx overview .` as your first probe. If grammars are missing the + output is self-diagnosing — it prints the detected project languages and the exact install command, e.g.: -## Pagination + ``` + cx: no language grammars installed + Detected languages in this project: + typescript (37 files) + markdown (7 files) + Install with: cx lang add typescript markdown + ``` + + If your harness sandboxes network egress, the install will fail with "Connection refused" when `cx` fetches the + grammars + from GitHub. Run the install outside the sandbox, or grant network access for the install command. Once grammars are + cached, normal cx queries don't need network. Re-run `cx overview .` to confirm. -Default limits: definition 3, symbols 100, references 50. When truncated, stderr shows: +## Common Recipes & Extra Info ``` -cx: 3/32 definitions for "X" | --from PATH to narrow | --offset 3 for more | --all +cx overview DIR --full `--full` also includes kind/range/signature for direct files +cx symbols [--kind K] [--name GLOB] [--file PATH] search symbols project-wide +cx symbols --kinds [--file PATH] list distinct kinds with counts +cx definition --name NAME [--from PATH] [--kind K] get a definition (optionally filtered to specific kind, e.g. function body) +cx references --name NAME [--file PATH] [--context] find usages, `--context` will show the line where the use appears ``` -`--offset N` pages forward, `--all` bypasses, `--limit N` overrides. Narrow with `--from`/`--file`/`--kind` before paging. +- `--file` and `--from` are identical and restrict the symbol to a precise file, but only if there is an exact match for + the path resolved from cwd. +- Kinds: fn, struct, enum, trait, type, const, class, interface, module, event, field, heading +- `.gitignore` is honored. Untracked-but-not-ignored files are still indexed. + +## Key patterns + +- Start with `cx overview .`, drill into subdirectories — cheaper than ls + reading files. +- Can't find a symbol that should exist? Make sure the language grammar is installed via `cx lang list`. +- `cx definition --name X` gives exact text for Edit tool's `old_string` without reading the whole file. +- `cx references --name X` groups hits by file; add `--context` only when exact source lines are needed. +- When re-entering an unfamiliar area or picking up a topic after a gap, use `cx overview` / `cx definition` to + re-orient — don't re-read full files +- Check signatures for `pub`/`export` to identify public API without reading the file. +- If your harness restricts writes outside the project root, the default cache location won't be writable. + Set `$CX_CACHE_DIR` to a project-local path, or grant write permission to the default cache dir. + +## Pagination -JSON: paginated → `{total, offset, limit, results: [...]}`, non-paginated → bare array. +Default limits: overview: unlimited, definition 3, symbols 100, references 50. -## Missing grammars +When truncated, stderr shows: `cx: 3/32 definitions for "X"`. Use `--file` (or `--from`) and `--kind` to narrow, or use +`--offset` to get further pages, or `--all` to get all results. -If cx reports a missing grammar, install with `cx lang add `. Run `cx lang list` to see what's installed. +When not limited, `--json` returns an array of results. When limited, it returns an object with +shape `{total, offset, limit, results: }`.