From 8942f8f3131845ee0acd74612f5b844c133f2066 Mon Sep 17 00:00:00 2001 From: "Nicolas \"Norswap\" Laurent" Date: Wed, 17 Jun 2026 17:51:27 +0800 Subject: [PATCH 1/7] cx skill: reformat --- src/skill.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/src/skill.md b/src/skill.md index b30e0ae..fc6036e 100644 --- a/src/skill.md +++ b/src/skill.md @@ -5,11 +5,11 @@ Prefer cx over reading files. Escalate: overview → symbols → definition/refe ## Quick reference ``` -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 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 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 @@ -37,7 +37,8 @@ Default limits: definition 3, symbols 100, references 50. When truncated, stderr cx: 3/32 definitions for "X" | --from PATH to narrow | --offset 3 for more | --all ``` -`--offset N` pages forward, `--all` bypasses, `--limit N` overrides. Narrow with `--from`/`--file`/`--kind` before paging. +`--offset N` pages forward, `--all` bypasses, `--limit N` overrides. Narrow with `--from`/`--file`/`--kind` before +paging. JSON: paginated → `{total, offset, limit, results: [...]}`, non-paginated → bare array. From 8316a941a73481d21968def8aa9d3e9c2edcf82b Mon Sep 17 00:00:00 2001 From: "Nicolas \"Norswap\" Laurent" Date: Wed, 17 Jun 2026 17:51:39 +0800 Subject: [PATCH 2/7] cx skill: preflight check --- src/skill.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/src/skill.md b/src/skill.md index fc6036e..caffce1 100644 --- a/src/skill.md +++ b/src/skill.md @@ -2,6 +2,31 @@ Prefer cx over reading files. Escalate: overview → symbols → definition/references → Read tool. +## First-run checks (once per session) + +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` + +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.: + + ``` + cx: no language grammars installed + Detected languages in this project: + typescript (37 files) + markdown (7 files) + Install with: cx lang add typescript markdown + ``` + + Run that suggested command **with the sandbox disabled** (`dangerouslyDisableSandbox: true`) — cx fetches grammars + from + GitHub releases and its Rust HTTP client doesn't honor the sandbox HTTP(S)_PROXY env vars, so it hits "Connection + refused" inside the sandbox. Once grammars are installed, all cx queries work inside the sandbox (reads don't need + network). Re-run `cx overview .` to confirm. + ## Quick reference ``` From 8f3efb4cc9dc3ab85d00c0c253ad7dd50755e68f Mon Sep 17 00:00:00 2001 From: "Nicolas \"Norswap\" Laurent" Date: Wed, 17 Jun 2026 17:59:52 +0800 Subject: [PATCH 3/7] cx skill: claude doesn't know when the context compresses --- src/skill.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/skill.md b/src/skill.md index caffce1..2a36948 100644 --- a/src/skill.md +++ b/src/skill.md @@ -51,7 +51,8 @@ Kinds: fn, struct, enum, trait, type, const, class, interface, module, event, he - 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 +- 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 ## Pagination From 489eba58be86483aa8660ebf1ec38db0a0b214a7 Mon Sep 17 00:00:00 2001 From: "Nicolas \"Norswap\" Laurent" Date: Wed, 17 Jun 2026 18:34:54 +0800 Subject: [PATCH 4/7] cx skill: missing field type --- src/skill.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/skill.md b/src/skill.md index 2a36948..db64c96 100644 --- a/src/skill.md +++ b/src/skill.md @@ -44,7 +44,7 @@ Global: --no-tests (exclude test files/symbols), --json, --limit N, --offset N, Aliases: `cx o`, `cx s`, `cx d`, `cx r` -Kinds: fn, struct, enum, trait, type, const, class, interface, module, event, heading +Kinds: fn, struct, enum, trait, type, const, class, interface, module, event, field, heading ## Key patterns From 8c9d1ac5471297742df0665b6b31f40e969b5083 Mon Sep 17 00:00:00 2001 From: "Nicolas \"Norswap\" Laurent" Date: Wed, 17 Jun 2026 18:57:30 +0800 Subject: [PATCH 5/7] cx skill: clarify doc, add precision for .gitignore and cache with Claude sandbox --- src/skill.md | 75 ++++++++++++++++++++++++++++++++-------------------- 1 file changed, 46 insertions(+), 29 deletions(-) diff --git a/src/skill.md b/src/skill.md index db64c96..fbb2761 100644 --- a/src/skill.md +++ b/src/skill.md @@ -1,6 +1,31 @@ # cx — Semantic Code Navigation -Prefer cx over reading files. Escalate: overview → symbols → definition/references → Read tool. +``` +Usage: cx [OPTIONS] + +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) +``` + +Prefer cx over reading files. Zoom in until you have what you need, then stop: +`overview` > `symbols` > `definition` or `references`. + +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). ## First-run checks (once per session) @@ -27,47 +52,39 @@ Prefer cx over reading files. Escalate: overview → symbols → definition/refe refused" inside the sandbox. Once grammars are installed, all cx queries work inside the sandbox (reads don't need network). Re-run `cx overview .` to confirm. -## Quick reference +## Common Recipes & Extra Info ``` -cx overview PATH file or directory table of contents -cx overview DIR --full directory overview with ranges + signatures +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 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 +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 ``` -Aliases: `cx o`, `cx s`, `cx d`, `cx r` - -Kinds: fn, struct, enum, trait, type, const, class, interface, module, event, field, heading +- `--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 -- `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 +- 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 +- Check signatures for `pub`/`export` to identify public API without reading the file. +- In Claude's sandbox mode, cannot write the cache's default location. Prompt to add to permissions or to set the + `$CX_CACHE_DIR` env var. ## Pagination -Default limits: definition 3, symbols 100, references 50. When truncated, stderr shows: - -``` -cx: 3/32 definitions for "X" | --from PATH to narrow | --offset 3 for more | --all -``` - -`--offset N` pages forward, `--all` bypasses, `--limit N` overrides. Narrow with `--from`/`--file`/`--kind` before -paging. - -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: }`. From 33b45ac3fd154762d7619737f54bf988ca88134a Mon Sep 17 00:00:00 2001 From: "Nicolas \"Norswap\" Laurent" Date: Thu, 18 Jun 2026 02:30:15 +0800 Subject: [PATCH 6/7] cx skill: generalize Claude-specific stuff --- src/skill.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/src/skill.md b/src/skill.md index fbb2761..d19972f 100644 --- a/src/skill.md +++ b/src/skill.md @@ -46,11 +46,10 @@ dispatch, string-keyed lookups, non-symbol regions). Install with: cx lang add typescript markdown ``` - Run that suggested command **with the sandbox disabled** (`dangerouslyDisableSandbox: true`) — cx fetches grammars - from - GitHub releases and its Rust HTTP client doesn't honor the sandbox HTTP(S)_PROXY env vars, so it hits "Connection - refused" inside the sandbox. Once grammars are installed, all cx queries work inside the sandbox (reads don't need - network). Re-run `cx overview .` to confirm. + 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. ## Common Recipes & Extra Info @@ -76,8 +75,8 @@ cx references --name NAME [--file PATH] [--context] find usages, `--context` wi - 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. -- In Claude's sandbox mode, cannot write the cache's default location. Prompt to add to permissions or to set the - `$CX_CACHE_DIR` env var. +- 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 From cd3f6967d82c28a225ee9fba4beb33c2cf45b676 Mon Sep 17 00:00:00 2001 From: "Nicolas \"Norswap\" Laurent" Date: Thu, 18 Jun 2026 02:59:44 +0800 Subject: [PATCH 7/7] cx skill: add frontmatter --- src/skill.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/src/skill.md b/src/skill.md index d19972f..247fd04 100644 --- a/src/skill.md +++ b/src/skill.md @@ -1,3 +1,8 @@ +--- +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 ```