Compare commits
4 Commits
9bc2dd91e2
...
main
| Author | SHA1 | Date | |
|---|---|---|---|
 alexei.dolgolyov
|
1f8195b420 | ||
|
alexei.dolgolyov
|
5a17fe960d | ||
|
alexei.dolgolyov
|
4c3b0188d8 | ||
|
alexei.dolgolyov
|
cd0d984930 |
@@ -1,6 +1,6 @@
|
||||
# Claude Code Facts
|
||||
|
||||
> Last updated: 2026-06-01
|
||||
> Last updated: 2026-06-23
|
||||
|
||||
A collection of interesting and useful facts, tips, tools, and guides for working with Claude and Claude Code.
|
||||
|
||||
@@ -8,7 +8,11 @@ A collection of interesting and useful facts, tips, tools, and guides for workin
|
||||
|
||||
### [Claude Code Tools & Extensions](claude-code-tools.md)
|
||||
|
||||
MCP servers, skills, and plugins that extend Claude Code — including Context7 (library docs), AST Index, and vex (fast code search with semantic embeddings).
|
||||
MCP servers, skills, and plugins that extend Claude Code — including Context7 (library docs), AST Index, and vex (hybrid code search; summarized here with a link to its full reference).
|
||||
|
||||
### [Everything Claude Code (ECC) — Setup Guide](ecc-setup-guide.md)
|
||||
|
||||
Step-by-step setup and update guide for ECC (Everything Claude Code) v2.0.0 — clone/install, the `ecc` selective-install CLI (profiles, `auto-update`, `doctor`/`repair`), the `skills/ecc/` namespaced layout, agent model tiers, Continuous Learning v2, and Windows gotchas.
|
||||
|
||||
### [Gitea Release Workflow (Minimal)](gitea-release-workflow.md)
|
||||
|
||||
@@ -26,6 +30,10 @@ Review of code signing options for Windows executables — Azure Trusted Signing
|
||||
|
||||
How to configure parallel job capacity for Gitea Act Runner on TrueNAS. Covers the `CONFIG_FILE` env var requirement, custom `config.yaml` mount, and capacity tuning.
|
||||
|
||||
### [vex — Hybrid Code Search Reference](vex.md)
|
||||
|
||||
Full reference for the `vex` code-search tool (current release **v1.16.0**) — install (prebuilt Windows/macOS/Linux binaries + `self-update`, or build-from-source), **GPU / CUDA acceleration** with the `jina-code` embedder recommendation, MCP-server registration (`vex mcp install`), the recommended `.vex.toml`, the complete command set (call graph, git history, scope/metadata search filters), and CLAUDE.md integration.
|
||||
|
||||
### [Code Search: vex vs ast-index — Benchmark Notes](code-search-vex-vs-ast-index.md)
|
||||
|
||||
Point-in-time benchmark of `vex` and `ast-index` on a real mixed-language repo — indexing footprint, query latency, precision findings, and when to fall back from one to the other. Refreshed for `vex 1.9.1` / `ast-index 3.41.0`, with a summary of what flipped since the previous snapshot.
|
||||
Point-in-time benchmark of `vex` and `ast-index` on a real mixed-language repo — indexing footprint, query latency, precision findings, and when to fall back from one to the other. Latency/quality tables pinned to `vex 1.9.1` / `ast-index 3.41.0`, with a summary of what flipped since the previous snapshot and a vex 1.16.0 capability-update note (see [vex.md](vex.md) for the current command set).
|
||||
|
||||
+4
-92
@@ -70,99 +70,11 @@ Fast code search skill for Claude Code — find classes, symbols, usages, implem
|
||||
|
||||
### vex
|
||||
|
||||
Fast hybrid code search — combines tree-sitter AST parsing, FST symbol lookup, BM25 body search, and optional ONNX semantic embeddings. Ships as a CLI (`vex search`, `vex usages`, `vex callers`, `vex similar`, `vex duplicates`, `vex pattern`, etc.) plus an optional MCP server (`vex-mcp`) that exposes the same operations to Claude Code as ~17 structured tools. Useful as a peer or replacement for AST Index when you want semantic / concept-level search in addition to exact symbol lookup.
|
||||
Fast hybrid code search — tree-sitter AST parsing, FST symbol lookup, BM25 body search, a persistent call graph, optional ONNX semantic embeddings, and (v1.16) a query-time git-history walker. Ships as a CLI plus an optional `vex-mcp` MCP server exposing 20+ structured tools to Claude Code. A strong peer or replacement for AST Index when you want semantic / concept-level search, call-graph navigation, and symbol-level git archaeology alongside exact symbol lookup.
|
||||
|
||||
- **Repository:** <https://github.com/tenatarika/vex>
|
||||
- **Languages:** 18+ via tree-sitter — Python, TypeScript/JavaScript, Go, Rust, Java, Kotlin, C#, Ruby, Swift, C++, PHP, Bash, Lua, CSS, HTML, YAML, TOML, SQL, Markdown.
|
||||
|
||||
- **Install (Linux/macOS):**
|
||||
|
||||
```bash
|
||||
brew tap tenatarika/tap && brew install vex
|
||||
```
|
||||
|
||||
Latest release also ships prebuilt tarballs for `linux-x86_64` and `darwin-aarch64`.
|
||||
|
||||
- **Install (Windows — build from source, ~3 min):**
|
||||
|
||||
As of v1.5.0 there is **no prebuilt Windows binary** in the release assets, so a Rust toolchain (≥1.80) is required:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/tenatarika/vex.git "$HOME/Documents/vex"
|
||||
cd "$HOME/Documents/vex"
|
||||
cargo build --release --workspace
|
||||
cp target/release/vex.exe target/release/vex-mcp.exe "$HOME/.cargo/bin/"
|
||||
```
|
||||
|
||||
`~/.cargo/bin/` (i.e. `%USERPROFILE%\.cargo\bin`) is already on PATH on any system with `cargo` installed, so both binaries become globally callable immediately.
|
||||
|
||||
- **Per-project bootstrap:**
|
||||
|
||||
```bash
|
||||
cd <your-project>
|
||||
vex init # creates .vex.toml
|
||||
vex index --path . # plain index, sub-second, no downloads
|
||||
# or, for semantic / concept-level search:
|
||||
vex index --path . --semantic # downloads ~86 MB ONNX model on first run
|
||||
```
|
||||
|
||||
Recommended `.vex.toml` for serious use:
|
||||
|
||||
```toml
|
||||
semantic = true # enable meaning-based search (vex similar, vex duplicates, --semantic queries)
|
||||
auto_update = true # incrementally refresh the index before each search
|
||||
```
|
||||
|
||||
- **Register `vex-mcp` with Claude Code (user scope — available across all projects):**
|
||||
|
||||
```bash
|
||||
# Windows
|
||||
claude mcp add vex -s user -- "$HOME/.cargo/bin/vex-mcp.exe"
|
||||
|
||||
# macOS / Linux
|
||||
claude mcp add vex -s user -- "$HOME/.cargo/bin/vex-mcp"
|
||||
```
|
||||
|
||||
`vex-mcp` defaults `VEX_ROOT` to the current working directory, so a single global registration works for every project — individual tool calls can also override per-call via a `project_root` argument.
|
||||
|
||||
- **Key commands / MCP tools:** `search` (symbol + semantic), `show` (full body), `usages`, `callers`, `callees`, `implementations`, `outline`, `pattern` (ast-grep–style structural match), `similar` (semantic, requires `--semantic` index), `duplicates`, `status`, `grep` (regex fallback, no index needed), `update` (incremental reindex).
|
||||
|
||||
- **Wire it into `CLAUDE.md` (recommended):**
|
||||
|
||||
Installing the binaries and building an index isn't enough — Claude won't reliably prefer `vex` over `Grep`/`Read` unless a `CLAUDE.md` tells it to.
|
||||
|
||||
**Start from upstream**, don't duplicate. The vex README maintains a canonical `CLAUDE.md` snippet — see [`README.md` → "CLAUDE.md Integration"](https://github.com/tenatarika/vex#claudemd-integration). Paste it into your **global** `~/.claude/CLAUDE.md` (applies to every project) or a **project-local** `./CLAUDE.md` (overrides global per repo).
|
||||
|
||||
**Then graft on these local additions** — they go beyond what upstream covers and are worth keeping wherever you install vex:
|
||||
|
||||
1. **MCP server line** — add this near the top of the snippet so Claude knows the MCP route exists:
|
||||
|
||||
> Equivalent **MCP tools** are also available via the `vex` MCP server when registered (`claude mcp add vex -s user`) — prefer them inside a Claude Code session for cheaper token output; use the Bash CLI from subagents, hooks, and scripts.
|
||||
|
||||
2. **Skip-vex rule** — add to the Rules block:
|
||||
|
||||
> **Skip vex** for non-code text — config files (YAML/JSON/TOML), docs, log strings, free-form prose — and for files in languages vex doesn't parse. Fall back to the next tool in the priority chain that's actually capable for the case (typically Grep/Glob for free-form text).
|
||||
|
||||
3. **Subagent reminder** — add to the Rules block:
|
||||
|
||||
> **Subagents** (Plan/Explore/general-purpose) don't inherit project CLAUDE.md or the parent's MCP toolset — explicitly tell them in the prompt to use `vex` via Bash for code search.
|
||||
|
||||
4. **`auto_update` accuracy fix** — upstream says "Run `vex update` after modifying source files if `auto_update` is not enabled." With `auto_update = true` it runs before *each search*, so during a Claude session the manual update is rarely needed. Reword as:
|
||||
|
||||
> **Run `vex update` manually after editing** only if `auto_update = false`; with `auto_update = true`, vex auto-refreshes before each search.
|
||||
|
||||
5. **`--semantic` cost note** — append to the `vex index --semantic` line in the Indexing block:
|
||||
|
||||
> downloads ~86 MB ONNX model on first run, enables `vex search --semantic`, `vex similar`, `vex duplicates`.
|
||||
|
||||
**When to put it in global vs project CLAUDE.md:**
|
||||
|
||||
- **Global (`~/.claude/CLAUDE.md`)** — preferred default once `vex-mcp` is registered at user scope. Vex becomes the recommendation for every project as soon as the index is built.
|
||||
- **Project-local (`./CLAUDE.md`)** — for overrides (different fallback chain, monorepo-specific `--filter` paths, language-specific `--kind` defaults, or excluding vex on repos where it isn't set up).
|
||||
|
||||
- **Caveats (as of v1.5.0):** vex is a young tool under active development. Known quirks: `implementations` doesn't detect generic-parameterized subclasses (`class Foo(Base[T])`); `usages` is text-flavored and matches inside comments/docstrings; first-time Windows install requires building from source. Verify load-bearing results against `ast-index` or `Grep`. The benchmark notes below capture more specific findings on a real repo.
|
||||
|
||||
- **vex vs AST Index — when each wins:** Both tools cover similar ground, but they're not interchangeable. For a point-in-time head-to-head on a real mixed-language repo (Python / Kotlin / TypeScript / JavaScript) with measured latency, quality differences, and version-pinned findings, see [`code-search-vex-vs-ast-index.md`](code-search-vex-vs-ast-index.md). Headline: keep `vex` as primary, fall back to `ast-index changed --base <branch>` for code-review diffs (no vex equivalent) and to `ast-index symbol`/`usages` when vex's textual matches are too noisy.
|
||||
- **Repository:** <https://github.com/tenatarika/vex> · **Current release:** v1.16.0 (`vex self-update` to upgrade in place).
|
||||
- **Full reference → [vex.md](vex.md)** — install (prebuilt Windows/macOS/Linux + `self-update`, or build-from-source), **GPU / CUDA acceleration** (strongly prefer `jina-code` + CUDA; it's too slow on CPU), `vex mcp install`, the recommended `.vex.toml`, the full command set (`bundle`, `paths`, `reachable`, `diff`, `history`, search scope/metadata filters), CLAUDE.md integration, and caveats.
|
||||
- **Benchmark vs AST Index → [code-search-vex-vs-ast-index.md](code-search-vex-vs-ast-index.md)** — point-in-time head-to-head. Headline: keep `vex` primary; fall back to `ast-index changed --base <branch>` for code-review diffs and to `ast-index symbol` / `usages` when you want textual matches.
|
||||
|
||||
### Packaged Skills
|
||||
|
||||
|
||||
@@ -11,6 +11,24 @@
|
||||
> this revision. See ["Changes since the 2026-05-18 snapshot"](#changes-since-the-2026-05-18-snapshot)
|
||||
> at the bottom for a summary.
|
||||
|
||||
> **Capability update — vex 1.16.0 (capabilities only, NOT re-benchmarked):** the
|
||||
> latency and quality tables below remain pinned to **vex 1.9.1**, but vex's feature
|
||||
> surface has moved on. New since 1.9.1 (no fresh measurements taken here):
|
||||
>
|
||||
> - **`vex history <Symbol>`** (v1.16) — query-time git-log walker returning every
|
||||
> historical version of a symbol (`--diff`, `--since`/`--until`, `--author`, `--kind`);
|
||||
> opt-in indexed sidecar via `vex index --history`. No ast-index equivalent.
|
||||
> - **`vex mcp install` / `uninstall` / `list`** (v1.15.0) — idempotent MCP-server
|
||||
> registration for Claude Code / Cursor (replaces hand-editing the agent config).
|
||||
> - **Scope & metadata search filters** on `vex search` / `vex usages` — `--kind`,
|
||||
> `--include`/`--exclude`, `--since`/`--since-branched`/`--changed-only`, `--visibility`,
|
||||
> `--async-only`, `--static-only`, `--sealed-only`, `--why`.
|
||||
> - **`vex gpu`** execution-provider probe; **`vex watch`** continuous reindex;
|
||||
> **`vex init --agents-md`**; prebuilt Windows `vex` + `vex-mcp` binaries.
|
||||
>
|
||||
> See **[vex.md](vex.md)** for the full current reference (install, GPU/CUDA, config,
|
||||
> command set). Re-run the tables below on 1.16.0 before citing the numbers.
|
||||
|
||||
## Test environment
|
||||
|
||||
| Aspect | Value |
|
||||
@@ -94,6 +112,7 @@ Three real queries from the test repo (re-run on 2026-05-26):
|
||||
- `vex bundle --mode {symbol,pr-impact,project}` — one call replaces the `show → callers → callees → similar` round trip; pr-impact mode bundles changed symbols + transitive callers + reachable tests for code review.
|
||||
- `vex eval` — built-in ranking eval harness for CI regression.
|
||||
- `vex capabilities` — machine-readable feature matrix.
|
||||
- **Since v1.10–v1.16 (see the capability-update note at the top + [vex.md](vex.md)):** `vex history` (symbol-level git archaeology), `vex mcp install`/`uninstall`/`list` (idempotent MCP registration), `vex gpu` (EP probe), `vex watch` (continuous reindex), and scope/metadata search filters (`--kind`, `--include`/`--exclude`, `--since`/`--changed-only`, `--visibility`, `--async-only`, `--why`).
|
||||
|
||||
## Practical recommendation
|
||||
|
||||
|
||||
+184
-158
@@ -2,21 +2,21 @@
|
||||
|
||||
Step-by-step instructions for setting up ECC on a new machine. Can be followed manually or by Claude.
|
||||
|
||||
> **Staleness warning:** The Windows-specific fixes (gotchas 6–8) were documented against ECC as of early 2026. These bugs may have been fixed upstream — check the [ECC repository](https://github.com/affaan-m/everything-claude-code) for recent changes before applying the workarounds.
|
||||
> **Version note:** Written and verified against **ECC v2.0.0** (2026-06-23). v2.0.0 is a major rewrite: a new `ecc` selective-install CLI, a `skills/ecc/` + `rules/ecc/` namespaced layout, a SQLite/JSON install-state with `doctor`/`repair`/`auto-update`, and ~67 agents / 271 skills in the catalog. The GitHub repo was renamed from `affaan-m/everything-claude-code` to **`affaan-m/ECC`** (homepage <https://ecc.tools>); the old URL still redirects. Re-check the [repository](https://github.com/affaan-m/ECC) before relying on any version-specific detail below.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Node.js + npm installed
|
||||
- Git installed
|
||||
- Claude Code CLI installed
|
||||
- **Node.js ≥ 18** + npm (v2.0.0 declares `packageManager: yarn@4`, but `npm install` still works; `install.ps1`/`install.sh` auto-install deps for you)
|
||||
- Git
|
||||
- Claude Code CLI
|
||||
- PowerShell (Windows) or Bash (macOS/Linux)
|
||||
|
||||
## Step 1 — Clone and install
|
||||
## Step 1 — Clone and install dependencies
|
||||
|
||||
**Windows (PowerShell):**
|
||||
|
||||
```powershell
|
||||
git clone https://github.com/affaan-m/everything-claude-code.git C:\Users\<USERNAME>\everything-claude-code
|
||||
git clone https://github.com/affaan-m/ECC.git C:\Users\<USERNAME>\everything-claude-code
|
||||
cd C:\Users\<USERNAME>\everything-claude-code
|
||||
npm install
|
||||
```
|
||||
@@ -24,79 +24,105 @@ npm install
|
||||
**macOS/Linux (Bash):**
|
||||
|
||||
```bash
|
||||
git clone https://github.com/affaan-m/everything-claude-code.git ~/everything-claude-code
|
||||
git clone https://github.com/affaan-m/ECC.git ~/everything-claude-code
|
||||
cd ~/everything-claude-code
|
||||
npm install
|
||||
```
|
||||
|
||||
> The clone directory name is your choice (`everything-claude-code` keeps older paths/scripts working). Runtime deps are small (`sql.js`, `ajv`, `@iarna/toml`). If you prefer the declared toolchain, `corepack enable && corepack yarn install` also works. You can skip `npm install` entirely if you use `install.ps1`/`install.sh` in Step 2 — they install deps automatically when `node_modules` is missing.
|
||||
|
||||
## Step 2 — Run the installer
|
||||
|
||||
Run the installer **from inside the cloned repo**.
|
||||
Run **from inside the cloned repo**. v2.0.0 ships a real CLI (`scripts/ecc.js`, also exposed as the `ecc` bin). Two equivalent ways to invoke it:
|
||||
|
||||
**Windows (PowerShell):**
|
||||
- `node scripts/ecc.js <command>` — most reliable, no PATH/npx ambiguity
|
||||
- `npx ecc <command>` — works from inside the repo (the postinstall banner suggests this form)
|
||||
|
||||
### Option A — Legacy language mode (simplest; matches older setups)
|
||||
|
||||
```powershell
|
||||
.\install.ps1 <languages>
|
||||
# Example: .\install.ps1 python typescript
|
||||
node scripts/ecc.js python typescript # bare languages route to "install"
|
||||
```
|
||||
|
||||
**macOS/Linux (Bash):**
|
||||
Equivalent compat scripts (auto-install deps, then delegate to the installer):
|
||||
|
||||
```bash
|
||||
./install.sh <languages>
|
||||
# Example: ./install.sh python typescript
|
||||
```powershell
|
||||
.\install.ps1 python typescript # Windows
|
||||
```
|
||||
|
||||
**Cross-platform (npm):**
|
||||
|
||||
```bash
|
||||
npx ecc-install <languages>
|
||||
./install.sh python typescript # macOS/Linux
|
||||
```
|
||||
|
||||
Available languages: `python`, `typescript`, `golang`, `swift`, `php`, `rust`, `cpp`, `csharp`, `java`, `kotlin`, `perl`
|
||||
|
||||
> **Note:** In legacy-compat mode the installer copies rules for ALL languages regardless of arguments. The extra rules are harmless — they sit in `~/.claude/rules/<lang>/` and only load when relevant.
|
||||
### Option B — Profile mode (v2.0.0, recommended for new installs)
|
||||
|
||||
### What gets installed
|
||||
|
||||
All files go to `~/.claude/` (global, applies to all projects):
|
||||
|
||||
| Category | Location | Examples |
|
||||
| ---------- | ---------- | --------- |
|
||||
| Rules | `~/.claude/rules/` | coding-style, testing, security (per language) |
|
||||
| Agents | `~/.claude/agents/` | planner, architect, code-reviewer, tdd-guide, security-reviewer |
|
||||
| Skills | `~/.claude/skills/` | python-patterns, tdd-workflow, e2e-testing, continuous-learning |
|
||||
| Commands | `~/.claude/commands/` | `/plan`, `/tdd`, `/code-review`, `/verify`, `/learn` |
|
||||
| Hooks | `~/.claude/hooks/` | auto-format, console-log check, cost tracker |
|
||||
|
||||
## Step 3 — Add Bash tool to read-only agents
|
||||
|
||||
Some agents (planner, architect) ship with only `Read, Grep, Glob` tools. To enable `ast-index` and other CLI tools, add `Bash` to their tool lists.
|
||||
|
||||
Edit these files in `~/.claude/agents/`:
|
||||
|
||||
- `planner.md`
|
||||
- `architect.md`
|
||||
|
||||
Change the frontmatter `tools` line from:
|
||||
|
||||
```yaml
|
||||
tools: ["Read", "Grep", "Glob"]
|
||||
```powershell
|
||||
node scripts/ecc.js install --profile developer --target claude
|
||||
```
|
||||
|
||||
To:
|
||||
Profiles (`node scripts/ecc.js catalog profiles` for the live list):
|
||||
|
||||
| Profile | Modules | Use |
|
||||
| --------- | --------- | ----- |
|
||||
| `minimal` | 5 | Low-context: rules, agents, commands, platform configs, quality — **no hook runtime** |
|
||||
| `core` | 6 | Harness baseline with commands, hooks, platform configs, quality |
|
||||
| `developer` | 9 | **Default engineering profile** for most users |
|
||||
| `security` | 7 | Security-heavy, baseline runtime + security guidance |
|
||||
| `research` | 9 | Research/content: investigation, synthesis, publishing |
|
||||
| `full` | 23 | Everything currently classified |
|
||||
| `opencode` | 3 | OpenCode target (excludes hooks-runtime) |
|
||||
|
||||
Not sure what you need? `node scripts/ecc.js consult "security reviews and python"` recommends components/profiles from a natural-language query, and `node scripts/ecc.js catalog components --family language` lists installable components.
|
||||
|
||||
> **Selective install caveat:** Profiles/languages only install the **selected modules'** skills. The full catalog is ~271 skills; a `developer`/language install lands ~70–80 under `~/.claude/skills/ecc/`. Add more later with `--modules <id>` or a broader profile — they are additive.
|
||||
|
||||
### What gets installed (v2.0.0 layout)
|
||||
|
||||
All files go to `~/.claude/` (global, applies to all projects). **v2.0.0 namespaces skills and rules under `ecc/`; agents and commands stay flat** (legacy-compat):
|
||||
|
||||
| Category | Location | Notes |
|
||||
| ---------- | ---------- | ------- |
|
||||
| Skills | `~/.claude/skills/ecc/<name>/` | **namespaced** under `ecc/` |
|
||||
| Rules | `~/.claude/rules/ecc/` | **namespaced** under `ecc/` |
|
||||
| Agents | `~/.claude/agents/<name>.md` | flat — **overwrites** existing files of the same name |
|
||||
| Commands | `~/.claude/commands/<name>.md` | flat |
|
||||
| Hooks | `~/.claude/hooks/` | reusable hook scripts |
|
||||
| ECC runtime | `~/.claude/scripts/` | `lib/`, `hooks/` used by the CLI (new in v2.0.0) |
|
||||
| Cross-harness | `~/.claude/.agents/` | shared agent/skill surface for Codex/Cursor/etc. (new) |
|
||||
|
||||
`settings.json` and `.claude.json` are **not** touched by the installer — your hooks config and MCP server registrations are safe.
|
||||
|
||||
The install records state in `~/.claude/ecc/install-state.json` (queryable with `ecc list-installed`).
|
||||
|
||||
## Step 3 — Add Bash to read-only agents (still required in v2.0.0)
|
||||
|
||||
`planner` and `architect` ship with only `Read, Grep, Glob`. To let them use `ast-index`/`vex` and other CLI tools, add `Bash`. Edit the frontmatter `tools:` line in `~/.claude/agents/planner.md` and `~/.claude/agents/architect.md`:
|
||||
|
||||
```yaml
|
||||
# from
|
||||
tools: ["Read", "Grep", "Glob"]
|
||||
# to
|
||||
tools: ["Read", "Grep", "Glob", "Bash"]
|
||||
```
|
||||
|
||||
All other agents already have `Bash` in their tools list.
|
||||
```bash
|
||||
# Bash one-liner:
|
||||
for a in planner architect; do
|
||||
sed -i 's/^tools: \["Read", "Grep", "Glob"\]$/tools: ["Read", "Grep", "Glob", "Bash"]/' ~/.claude/agents/$a.md
|
||||
done
|
||||
```
|
||||
|
||||
All other agents already include `Bash`.
|
||||
|
||||
## Step 4 — Configure Continuous Learning v2
|
||||
|
||||
In v2.0.0 CL-v2 lives at **`~/.claude/skills/ecc/continuous-learning-v2/`**.
|
||||
|
||||
### 4a. Add observation hooks
|
||||
|
||||
Add the following to `~/.claude/settings.json` (merge into existing `hooks` key if one exists):
|
||||
Merge into `~/.claude/settings.json` (combine with any existing `hooks` key):
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -105,166 +131,166 @@ Add the following to `~/.claude/settings.json` (merge into existing `hooks` key
|
||||
"matcher": "*",
|
||||
"hooks": [{
|
||||
"type": "command",
|
||||
"command": "~/.claude/skills/continuous-learning-v2/hooks/observe.sh"
|
||||
"command": "~/.claude/skills/ecc/continuous-learning-v2/hooks/observe.sh"
|
||||
}]
|
||||
}],
|
||||
"PostToolUse": [{
|
||||
"matcher": "*",
|
||||
"hooks": [{
|
||||
"type": "command",
|
||||
"command": "~/.claude/skills/continuous-learning-v2/hooks/observe.sh"
|
||||
"command": "~/.claude/skills/ecc/continuous-learning-v2/hooks/observe.sh"
|
||||
}]
|
||||
}]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4b. Create the directory structure
|
||||
### 4b. Enable the observer (still ships disabled)
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.claude/homunculus/{instincts/{personal,inherited},evolved/{agents,skills,commands},projects}
|
||||
`~/.claude/skills/ecc/continuous-learning-v2/config.json` ships with `"enabled": false`. Set it to `true`:
|
||||
|
||||
```json
|
||||
{ "enabled": true }
|
||||
```
|
||||
|
||||
> **Windows note:** The two historical Windows-only observer bugs are **fixed in v2.0.0** — `observe.sh` now detects the `python3` Microsoft Store stub (`_is_windows_app_installer_stub`) and allows the `claude-vscode`/`claude-desktop` entrypoints. The only manual step left is flipping `enabled` to `true` above. The `~/.claude/homunculus/` instinct store is auto-created/managed by CL-v2 (no manual `mkdir` needed).
|
||||
|
||||
### 4c. Verify the observe script exists
|
||||
|
||||
```bash
|
||||
ls ~/.claude/skills/continuous-learning-v2/hooks/observe.sh
|
||||
ls ~/.claude/skills/ecc/continuous-learning-v2/hooks/observe.sh
|
||||
```
|
||||
|
||||
If missing, re-run the installer from Step 2.
|
||||
If missing, re-run the installer (Step 2).
|
||||
|
||||
## Step 5 — Restart Claude Code
|
||||
|
||||
Hooks and new agents only take effect after restarting Claude Code.
|
||||
|
||||
## Post-install verification
|
||||
|
||||
Run these commands inside Claude Code to verify:
|
||||
|
||||
| Command | Expected result |
|
||||
| --------- | ---------------- |
|
||||
| `/plan "test"` | Should invoke the planner agent |
|
||||
| `/instinct-status` | Should show instinct status (empty on first run) |
|
||||
| `/code-review` | Should invoke the code-reviewer agent |
|
||||
|
||||
## Useful commands
|
||||
|
||||
| Command | Purpose |
|
||||
| --------- | --------- |
|
||||
| `/plan` | Create implementation plan before coding |
|
||||
| `/tdd` | Test-driven development workflow |
|
||||
| `/code-review` | Review code for quality issues |
|
||||
| `/verify` | Run verification loop |
|
||||
| `/learn` | Manually extract patterns mid-session |
|
||||
| `/instinct-status` | View learned instincts |
|
||||
| `/evolve` | Cluster instincts into skills/commands/agents |
|
||||
| `/promote` | Promote project instincts to global scope |
|
||||
| `/projects` | List known projects and instinct counts |
|
||||
|
||||
## Known gotchas
|
||||
|
||||
1. **`/plugin` commands don't exist** — The ECC README references `/plugin marketplace add` and `/plugin install` but Claude Code has no such CLI commands. Use the `install.ps1` / `install.sh` script instead.
|
||||
|
||||
2. **The `extraKnownMarketplaces` entry is cosmetic** — Adding ECC to `extraKnownMarketplaces` in `settings.json` does NOT enable it as a plugin and it will NOT appear in the enabled/disabled plugins list. The manual install is the actual installation method.
|
||||
|
||||
3. **Windows: don't mix WSL and PowerShell** — If npm is installed on Windows, run everything in PowerShell with Windows paths (`C:\Users\...`). If using WSL, run everything in WSL with Linux paths (`~/...`). Mixing causes path resolution failures.
|
||||
|
||||
4. **Windows paths in PowerShell** — Use `C:\Users\<USERNAME>\...`, NOT `/c/Users/...` (that's Git Bash / WSL syntax).
|
||||
|
||||
5. **Agent model selection** — Each agent `.md` file in `~/.claude/agents/` supports a `model` field in frontmatter. Options: `haiku` (fast/cheap), `sonnet` (balanced), `opus` (deep reasoning). Choose based on agent complexity needs.
|
||||
|
||||
### Continuous Learning v2 — Windows fixes (critical)
|
||||
|
||||
The observe hook ships with three bugs that silently prevent all observations on Windows:
|
||||
|
||||
1. **`python3` is the Windows Store stub** — On Windows, `python3` resolves to the Microsoft Store redirect (`AppData/Local/Microsoft/WindowsApps/python3`) which returns exit code 49 instead of running Python. The hook's `resolve_python_cmd()` uses `command -v` which finds the stub. **Fix:** In both `~/.claude/skills/continuous-learning-v2/hooks/observe.sh` and `~/.claude/skills/continuous-learning-v2/scripts/detect-project.sh`, change `resolve_python_cmd()` to test execution (`"$candidate" -c "1"`) instead of just checking presence (`command -v`).
|
||||
|
||||
2. **`claude-vscode` entrypoint rejected** — The hook's Layer 1 filter only allows `cli` and `sdk-ts` entrypoints. VS Code extension sets `CLAUDE_CODE_ENTRYPOINT=claude-vscode`, so every observation is silently skipped. **Fix:** Add `claude-vscode` to the allowed entrypoints case pattern in `observe.sh`.
|
||||
|
||||
3. **Observer disabled by default** — `~/.claude/skills/continuous-learning-v2/config.json` ships with `"enabled": false`. **Fix:** Set `"enabled": true`.
|
||||
Hooks and new/changed agents only take effect after a restart.
|
||||
|
||||
## Step 6 — Configure agent model tiers
|
||||
|
||||
ECC agents ship with `sonnet` as default. For better results, set thinking-heavy agents to `opus` and keep mechanical agents on cheaper models.
|
||||
ECC agents mostly default to `sonnet` (a few ship `opus` already — e.g. `architect`, `chief-of-staff`, `planner`). Policy: **reviewers and thinking-heavy agents → `opus`; build/error resolvers and mechanical agents → `sonnet`; lightweight doc agents → `haiku`.** This applies to the v2.0.0 reviewer additions too (`csharp-`, `react-`, `vue-`, `fastapi-`, `django-`, `swift-`, `php-`, `fsharp-`, `mle-`, `healthcare-reviewer`, etc.).
|
||||
|
||||
Edit the `model:` line in each agent's frontmatter in `~/.claude/agents/`:
|
||||
|
||||
| Model | Agents | Rationale |
|
||||
| ------- | -------- | ----------- |
|
||||
| **opus** | code-reviewer, python-reviewer, typescript-reviewer, rust-reviewer, go-reviewer, java-reviewer, kotlin-reviewer, cpp-reviewer, flutter-reviewer, database-reviewer, security-reviewer, tdd-guide, planner, architect, chief-of-staff | Deep reasoning for code quality, security, architecture |
|
||||
| **sonnet** | build-error-resolver, cpp-build-resolver, go-build-resolver, java-build-resolver, kotlin-build-resolver, rust-build-resolver, pytorch-build-resolver, e2e-runner, harness-optimizer, loop-operator, docs-lookup, refactor-cleaner | Mechanical tasks, error fixing |
|
||||
| **haiku** | doc-updater | Lightweight docs work |
|
||||
|
||||
To bulk-update reviewers and thinking-heavy agents to opus:
|
||||
Bulk-apply with a glob so it covers current and future reviewers:
|
||||
|
||||
```bash
|
||||
# From bash/git bash:
|
||||
for f in ~/.claude/agents/{code,python,typescript,rust,go,java,kotlin,cpp,flutter,database,security}-reviewer.md ~/.claude/agents/tdd-guide.md; do
|
||||
sed -i 's/^model: sonnet/model: opus/' "$f"
|
||||
cd ~/.claude/agents
|
||||
# Every *-reviewer agent -> opus
|
||||
for f in *-reviewer.md; do sed -i 's/^model: sonnet$/model: opus/' "$f"; done
|
||||
# Thinking-heavy non-reviewer agents -> opus
|
||||
for f in planner architect tdd-guide chief-of-staff code-architect performance-optimizer; do
|
||||
[ -f "$f.md" ] && sed -i 's/^model: sonnet$/model: opus/' "$f.md"
|
||||
done
|
||||
```
|
||||
|
||||
## Updating ECC
|
||||
| Tier | Agents (examples) | Rationale |
|
||||
| ------- | -------- | ----------- |
|
||||
| **opus** | all `*-reviewer`, `tdd-guide`, `planner`, `architect`, `code-architect`, `security-reviewer`, `chief-of-staff`, `performance-optimizer` | Deep reasoning: code quality, security, architecture |
|
||||
| **sonnet** | `*-build-resolver`, `e2e-runner`, `refactor-cleaner`, `docs-lookup`, `harness-optimizer` | Mechanical fixes, error resolution |
|
||||
| **haiku** | `doc-updater` | Lightweight docs work |
|
||||
|
||||
The installer overwrites all files in `~/.claude/`, so updating is straightforward — but custom changes (model tiers, hook fixes) will be lost. Back them up first.
|
||||
> These overrides are intentional drift and will show up in `ecc doctor` as "drifted managed files" — that is expected, not an error.
|
||||
|
||||
### Update steps
|
||||
## Post-install verification
|
||||
|
||||
**1. Pull the latest version:**
|
||||
|
||||
**Windows (PowerShell):**
|
||||
|
||||
```powershell
|
||||
cd C:\Users\<USERNAME>\everything-claude-code
|
||||
git pull
|
||||
npm install
|
||||
```bash
|
||||
node scripts/ecc.js list-installed # target, modules, source version
|
||||
node scripts/ecc.js doctor # health: drift / missing files / version mismatch
|
||||
```
|
||||
|
||||
**macOS/Linux (Bash):**
|
||||
Inside Claude Code:
|
||||
|
||||
| Command | Expected result |
|
||||
| --------- | ---------------- |
|
||||
| `/plan "test"` | Invokes the planner agent |
|
||||
| `/code-review` | Invokes the code-reviewer agent |
|
||||
| `/instinct-status` | Shows instinct status (empty on first run) |
|
||||
|
||||
## Useful commands
|
||||
|
||||
**ECC CLI** (`node scripts/ecc.js <command>`):
|
||||
|
||||
| Command | Purpose |
|
||||
| --------- | --------- |
|
||||
| `install` | Install content (`--profile`, `--target`, or bare languages) |
|
||||
| `auto-update` | **Pull latest + reinstall** managed targets in one step |
|
||||
| `doctor` | Diagnose drift / missing / version mismatch |
|
||||
| `repair` | Restore drifted or missing managed files (`--dry-run` to preview) |
|
||||
| `plan` | Preview a resolved install plan (safe, read-only) |
|
||||
| `catalog` | Discover profiles and components |
|
||||
| `consult` | Recommend components/profiles from a NL query |
|
||||
| `list-installed` | Inspect install-state |
|
||||
| `uninstall` | Remove ECC-managed files (`--dry-run` to preview) |
|
||||
| `status` | SQLite state-store summary |
|
||||
|
||||
**Slash commands** (in Claude Code): `/plan`, `/tdd`, `/code-review`, `/verify`, `/learn`, `/instinct-status`, `/evolve`, `/promote`, `/projects`.
|
||||
|
||||
## Updating ECC
|
||||
|
||||
### One-command update (v2.0.0)
|
||||
|
||||
```bash
|
||||
cd ~/everything-claude-code
|
||||
node scripts/ecc.js auto-update
|
||||
```
|
||||
|
||||
`auto-update` runs `git fetch --prune` + `git pull --ff-only`, then reinstalls every managed target using its recorded install request.
|
||||
|
||||
> ⚠️ **Footgun — `--dry-run auto-update` is NOT a dry run.** The global `--dry-run` flag is **not** honored by `auto-update`: it still pulls and performs a **real reinstall** (the flag does not propagate into the child install process). To preview an update safely, use **`node scripts/ecc.js plan`** or **`node scripts/ecc.js install --dry-run --target claude <languages>`** instead — those genuinely make no changes.
|
||||
|
||||
### Manual update (equivalent)
|
||||
|
||||
```bash
|
||||
cd ~/everything-claude-code
|
||||
git pull
|
||||
npm install
|
||||
npm install # if deps changed
|
||||
node scripts/ecc.js install --target claude python typescript
|
||||
```
|
||||
|
||||
**2. Back up your customizations:**
|
||||
### After any update — re-apply customizations
|
||||
|
||||
A reinstall **overwrites flat agents**, so these are lost and must be re-applied:
|
||||
|
||||
1. **Agent model tiers** (Step 6) — reviewers/thinking-heavy back to `opus`.
|
||||
2. **`Bash` on `planner` + `architect`** (Step 3).
|
||||
3. **`"enabled": true`** in CL-v2 `config.json` (Step 4b) if you use the observer.
|
||||
|
||||
Skills and rules live under `ecc/` and are replaced in place, so they need no manual fix-up.
|
||||
|
||||
### Migrating from a pre-2.0 (flat) install
|
||||
|
||||
Old installs put skills/rules **flat** (`~/.claude/skills/<name>`). v2.0.0 writes them under `~/.claude/skills/ecc/<name>` and **does not delete the old flat copies**, leaving stale duplicates. After updating, remove only the flat skills that now exist under `ecc/` (preserves your own skills and any ECC skill whose module wasn't reinstalled):
|
||||
|
||||
```bash
|
||||
# Save agent model overrides
|
||||
grep -l 'model: opus' ~/.claude/agents/*.md > /tmp/ecc-opus-agents.txt
|
||||
|
||||
# Save patched hook files
|
||||
cp ~/.claude/skills/continuous-learning-v2/hooks/observe.sh /tmp/observe.sh.bak
|
||||
cp ~/.claude/skills/continuous-learning-v2/scripts/detect-project.sh /tmp/detect-project.sh.bak
|
||||
cp ~/.claude/skills/continuous-learning-v2/config.json /tmp/cl-config.json.bak
|
||||
cd ~/.claude/skills
|
||||
comm -12 \
|
||||
<(ls -d */ | grep -vx 'ecc/' | xargs -n1 basename | sort) \
|
||||
<(ls -d ecc/*/ | xargs -n1 basename | sort) \
|
||||
| while read s; do rm -rf "./$s"; done
|
||||
```
|
||||
|
||||
**3. Re-run the installer:**
|
||||
|
||||
**Windows (PowerShell):**
|
||||
|
||||
```powershell
|
||||
.\install.ps1 python typescript
|
||||
```
|
||||
|
||||
**macOS/Linux (Bash):**
|
||||
|
||||
```bash
|
||||
./install.sh python typescript
|
||||
```
|
||||
|
||||
**4. Re-apply customizations:**
|
||||
|
||||
- Re-apply agent model tiers (Step 6 above)
|
||||
- Re-apply the three Windows hook fixes (gotchas 6–8 above)
|
||||
- Re-enable observer in `config.json` (`"enabled": true`)
|
||||
- Re-add `Bash` to planner and architect tools (Step 3 above)
|
||||
Then confirm with `node scripts/ecc.js doctor` (expect `WARNING` only for your intentional model-tier overrides).
|
||||
|
||||
### Check current version
|
||||
|
||||
```bash
|
||||
cat ~/.claude/plugin.json | grep version
|
||||
# or from the repo:
|
||||
cat ~/everything-claude-code/VERSION
|
||||
node scripts/ecc.js list-installed # "Source version: X" + recorded modules
|
||||
node scripts/ecc.js doctor # flags repo-version mismatch
|
||||
cat ~/everything-claude-code/VERSION # repo version on disk
|
||||
```
|
||||
|
||||
## Known gotchas
|
||||
|
||||
1. **`--dry-run auto-update` performs a real install** — see the Updating section. Preview with `ecc plan` / `ecc install --dry-run` instead.
|
||||
|
||||
2. **v2.0.0 namespaces skills/rules under `ecc/`** but keeps agents/commands flat. Paths in older notes (`~/.claude/skills/<name>`) are now `~/.claude/skills/ecc/<name>`. Updating from a flat install leaves orphan duplicates (see migration cleanup above).
|
||||
|
||||
3. **Reinstalls overwrite flat agents** — agent model tiers and the `planner`/`architect` Bash addition must be re-applied after every update.
|
||||
|
||||
4. **`/plugin` install path is unreliable** — although v2.0.0 ships plugin/marketplace metadata, the selective-install CLI (`ecc install` / `install.ps1`) is the dependable full-install method. Don't rely on `/plugin marketplace add` / `/plugin install`.
|
||||
|
||||
5. **Windows: don't mix WSL and PowerShell** — pick one. PowerShell → Windows paths (`C:\Users\...`); WSL → Linux paths (`~/...`). Mixing breaks path resolution.
|
||||
|
||||
6. **Windows paths in PowerShell** — use `C:\Users\<USERNAME>\...`, not `/c/Users/...` (that's Git Bash / WSL syntax).
|
||||
|
||||
7. **`npm install` vs yarn** — v2.0.0 declares `packageManager: yarn@4` and ships `yarn.lock`, but also a `package-lock.json`; `npm install` works. If you want the declared toolchain use `corepack yarn install`. Don't commit lockfile churn back to the clone.
|
||||
|
||||
Binary file not shown.
@@ -0,0 +1,203 @@
|
||||
# vex — Hybrid Structural + Semantic Code Search
|
||||
|
||||
> **Current release:** v1.16.0 · Companion doc: [code-search-vex-vs-ast-index.md](code-search-vex-vs-ast-index.md) (vex-vs-ast-index benchmark notes).
|
||||
>
|
||||
> Split out of [claude-code-tools.md](claude-code-tools.md) — that file keeps a short blurb and links here.
|
||||
|
||||
Fast hybrid code search — combines tree-sitter AST parsing, FST symbol lookup, BM25 body search, a persistent call graph, optional ONNX semantic embeddings, and (v1.16) a query-time git-history walker. Ships as a CLI (`vex search`, `vex usages`, `vex callers`, `vex bundle`, `vex history`, `vex pattern`, etc.) plus an optional MCP server (`vex-mcp`) that exposes the same operations to Claude Code as 20+ structured tools. Useful as a peer or replacement for AST Index when you want semantic / concept-level search, call-graph navigation, and symbol-level git archaeology in addition to exact symbol lookup.
|
||||
|
||||
- **Repository:** <https://github.com/tenatarika/vex>
|
||||
- **Current release:** v1.16.0 — verify with `vex self-update --check`, upgrade in place with `vex self-update` (works on Windows/macOS/Linux).
|
||||
- **Languages:** 18+ via tree-sitter — Python, TypeScript/JavaScript, Go, Rust, Java, Kotlin, C#, Ruby, Swift, C++, PHP, Bash, Lua, CSS, HTML, YAML, TOML, SQL, Markdown.
|
||||
|
||||
## Install
|
||||
|
||||
- **Linux / macOS:**
|
||||
|
||||
```bash
|
||||
brew tap tenatarika/tap && brew install vex
|
||||
```
|
||||
|
||||
The [release assets](https://github.com/tenatarika/vex/releases/latest) also ship prebuilt tarballs — as of v1.16.0, both `vex` and `vex-mcp` for `x86_64-unknown-linux-gnu`, `aarch64-apple-darwin`, and `x86_64-pc-windows-msvc`.
|
||||
|
||||
- **Windows (prebuilt, no Rust needed):**
|
||||
|
||||
Recent releases (confirmed through v1.16.0) ship **prebuilt Windows binaries** — `vex-x86_64-pc-windows-msvc.tar.gz` and `vex-mcp-x86_64-pc-windows-msvc.tar.gz`. Download both, drop `vex.exe` + `vex-mcp.exe` onto your PATH (e.g. `%USERPROFILE%\.cargo\bin` or any PATH dir), then keep them current in place:
|
||||
|
||||
```bash
|
||||
vex self-update # --check previews the latest version; -y skips the prompt
|
||||
```
|
||||
|
||||
`vex self-update` replaces the running binary in place on Windows, macOS, and Linux — no package manager required.
|
||||
|
||||
- **Build from source** (fallback — unreleased commits, or a **CUDA-enabled GPU build**; needs Rust ≥1.80):
|
||||
|
||||
```bash
|
||||
git clone https://github.com/tenatarika/vex.git "$HOME/Documents/vex"
|
||||
cd "$HOME/Documents/vex"
|
||||
cargo build --release --workspace # add --features gpu-cuda for CUDA-accelerated embedding
|
||||
cp target/release/vex.exe target/release/vex-mcp.exe "$HOME/.cargo/bin/"
|
||||
```
|
||||
|
||||
`~/.cargo/bin/` (i.e. `%USERPROFILE%\.cargo\bin`) is already on PATH on any system with `cargo` installed, so both binaries become globally callable immediately.
|
||||
|
||||
## GPU / CUDA acceleration
|
||||
|
||||
Semantic indexing (`--semantic`) is the only GPU-accelerated path — the GPU absorbs the heavier embedding cost on cold/large builds. Search queries themselves are CPU-bound and already fast. vex picks an ONNX Runtime **execution provider** at embed time:
|
||||
|
||||
| Provider | Where it comes from | Notes |
|
||||
|---|---|---|
|
||||
| **CPU** | always available | fine for `minilm-l6-v2`; **impractically slow for `jina-code`** |
|
||||
| **CUDA** | **source build only** — `cargo build --release --features gpu-cuda` + NVIDIA CUDA toolkit | the only GPU path that works with `jina-code` |
|
||||
| **DirectML** | Windows prebuilt | **incompatible with `jina-code`** (see warning below) |
|
||||
| **CoreML** | macOS prebuilt | Apple Silicon |
|
||||
|
||||
**Setup (NVIDIA + CUDA, Windows or Linux):**
|
||||
|
||||
1. Build vex with the CUDA feature — **the prebuilt binaries do not include CUDA**:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/tenatarika/vex.git && cd vex
|
||||
cargo build --release --features gpu-cuda
|
||||
cp target/release/vex.exe target/release/vex-mcp.exe "$HOME/.cargo/bin/" # drop .exe on Linux
|
||||
```
|
||||
|
||||
Requires a matching CUDA toolkit and the ONNX Runtime CUDA execution provider available to the binary.
|
||||
|
||||
2. Verify the provider actually engages on this machine:
|
||||
|
||||
```bash
|
||||
vex gpu # actively probes every compiled EP; --enable pins VEX_DEVICE for all projects
|
||||
vex status # should print: GPU: yes (CUDA)
|
||||
```
|
||||
|
||||
3. Index on the GPU:
|
||||
|
||||
```bash
|
||||
vex index --semantic --embedder jina-code --device cuda
|
||||
```
|
||||
|
||||
**⚠️ `jina-code` is incompatible with DirectML (Windows).** The code-specialized `jina-code` embedder has ops the DirectML EP cannot place — forcing `--gpu` / `--device directml` fails with `DML EP can only be used with CPU EPs`. So on Windows, `jina-code` runs on **CUDA (source build)** or **CPU only** — never on the prebuilt DirectML path. The default `device = "auto"` handles this gracefully (falls back to CPU) and is safe for `auto_update` incremental rebuilds.
|
||||
|
||||
**Recommendation — `jina-code` + CUDA is strongly preferred, and CUDA is essential for it:**
|
||||
|
||||
- **Strongly recommended whenever you have (or can build) CUDA on an NVIDIA GPU: `embedder = "jina-code"` + `device = "cuda"`.** The 768-dim, code-specialized model gives **noticeably better code-search results** than the default — this is the setup to aim for, and the GPU absorbs its heavier embed cost.
|
||||
- **CUDA is essential for `jina-code`, not a nice-to-have.** On CPU the model is **too slow to be practical** — the cold embed of a real repo drags badly — and on Windows it can't use DirectML at all. So if a CUDA build is genuinely out of reach, **do not force `jina-code` onto CPU**; fall back to the default `embedder = "minilm-l6-v2"`, which is CPU-fast and good enough for symbol + semantic search.
|
||||
- **Rule of thumb: CUDA → `jina-code`; no CUDA → `minilm-l6-v2`.** Never pair `jina-code` with CPU or DirectML.
|
||||
|
||||
## Per-project setup
|
||||
|
||||
```bash
|
||||
cd <your-project>
|
||||
vex init # creates .vex.toml (add --agents-md to also emit an AGENTS.md for Cursor/Codex/Aider/Cline)
|
||||
vex index --path . # plain index, sub-second, no downloads
|
||||
# or, for semantic / concept-level search:
|
||||
vex index --path . --semantic # downloads ~86 MB ONNX model on first run
|
||||
# optional: bake a git-history sidecar so `vex history` is ~ms instead of shelling to git log:
|
||||
vex index --path . --semantic --history
|
||||
# thousands-of-commits repo? cap the one-time walk so the build stays fast (--history-depth implies --history):
|
||||
vex index --path . --semantic --history-depth 500
|
||||
```
|
||||
|
||||
Recommended `.vex.toml` for serious use:
|
||||
|
||||
```toml
|
||||
semantic = true # enable meaning-based search (vex similar, vex duplicates, --semantic queries)
|
||||
auto_update = true # incrementally refresh the index before each search when stale
|
||||
|
||||
# Embedder — CUDA is the deciding factor (see "GPU / CUDA acceleration" above):
|
||||
# CUDA available → jina-code (STRONGLY recommended: code-specialized 768-dim, best results)
|
||||
# no CUDA (CPU/DML) → minilm-l6-v2 (default, CPU-fast; jina-code is too slow on CPU and can't use DirectML)
|
||||
embedder = "jina-code" # alternatives: minilm-l6-v2 (default), bge-base-en-v1.5, bge-large-en-v1.5, mxbai-large
|
||||
device = "cuda" # essential for jina-code; "auto" (default) falls back to CPU safely. Run `vex gpu` to probe.
|
||||
|
||||
# Git history (v1.16): `vex history <Symbol>` walks git log at QUERY TIME with no
|
||||
# index and no config needed — it works even on a repo vex hasn't indexed yet, so
|
||||
# there is intentionally no .vex.toml key to enable it. To make it FST-fast (~ms)
|
||||
# on long-lived repos, build the opt-in indexed sidecar with `vex index --history`
|
||||
# (adds ~5-30s to a cold build and ~10% to index size); `vex status` then shows a
|
||||
# "History:" line. On a repo with thousands of commits, cap the build with
|
||||
# `vex index --history-depth 500` (global newest-N, like `git log -n500`) so a
|
||||
# full-history walk doesn't blow up index time. Re-run after a `vex self-update`.
|
||||
```
|
||||
|
||||
## Register the MCP server
|
||||
|
||||
- **v1.15.0+ — one idempotent command:**
|
||||
|
||||
```bash
|
||||
vex mcp install --agent claude-code # also: cursor, or `--agent all` to fan out across every supported agent
|
||||
vex mcp list # show current entries across all supported agents
|
||||
vex mcp uninstall --agent claude-code # idempotent removal
|
||||
```
|
||||
|
||||
`vex mcp install` defaults `--binary-path` to the `vex-mcp` sibling of the running `vex` (PATH fallback otherwise) and `--project-root` (→ `VEX_ROOT`) to the cwd. Use `--server-name` to register distinct entries per repo (`vex-api` / `vex-client`); `--dry-run` previews the write; `--force` overwrites a differing entry. Supported agents today: `claude-code`, `cursor` (with `codex-cli`, `windsurf`, `cline`, `continue`, `zed` landing).
|
||||
|
||||
- **Manual equivalent** (still works — e.g. for a custom binary path or non-default scope):
|
||||
|
||||
```bash
|
||||
# Windows
|
||||
claude mcp add vex -s user -- "$HOME/.cargo/bin/vex-mcp.exe"
|
||||
|
||||
# macOS / Linux
|
||||
claude mcp add vex -s user -- "$HOME/.cargo/bin/vex-mcp"
|
||||
```
|
||||
|
||||
`vex-mcp` defaults `VEX_ROOT` to the current working directory, so a single global registration works for every project — individual tool calls can also override per-call via a `project_root` argument.
|
||||
|
||||
## Command reference
|
||||
|
||||
- **Key commands / MCP tools:** `search` (symbol + semantic, with scope/metadata filters — see below), `show` (full body), `usages` (`--strict` for binder-resolved refs), `callers`, `callees`, `implementations`, `outline`, `pattern` (ast-grep–style structural match), `similar` (semantic, requires `--semantic` index), `duplicates`, `check` (fast multi-symbol existence), `grep` (regex fallback, no index needed), `update` (incremental reindex), `status`, `capabilities` (machine-readable feature matrix).
|
||||
|
||||
- **Call-graph & impact (call-graph index, ~ms queries):** `callers` / `callees` (direct), `paths --from A --to B` (all caller chains between two symbols), `reachable --target T` (everything that transitively reaches `T`), `bundle --mode {symbol,pr-impact,project}` (one call replaces the `show → callers → callees → similar` round trip; `pr-impact` bundles changed symbols + transitive callers + reachable tests for review), `diff --base <rev>` (symbol-level git-rev diff).
|
||||
|
||||
- **Git history (v1.16):** `history <Symbol>` walks git log and returns every historical version of a symbol — query-time, no index needed, works even on un-indexed repos. Flags: `--diff` (unified diffs between consecutive versions), `--since` / `--until` (date), `--author`, `--kind`, `--branch`, `--depth <N>` (max commits **per file** — bump down to cap query latency), `--limit <N>` (cap total results). Opt into an indexed sidecar with `vex index --history` for ~ms lookups.
|
||||
|
||||
**Taming history cost on large repos:** the two depth knobs are different. `vex history --depth <N>` limits the *query-time* walk **per file**. `vex index --history-depth <N>` caps the *one-time index build* at the **global** newest-N commits (mirrors `git log -nN`, implies `--history`); both are unbounded by default. On a repo with thousands of commits, build with e.g. `vex index --history-depth 500` so a full-history walk doesn't blow up index time and size.
|
||||
|
||||
- **Search scope & metadata filters:** `vex search` and `vex usages` accept `--kind fn,method`, `--include` / `--exclude '<glob>'` (repeatable), `--since <rev>` / `--since-branched` / `--changed-only` (restrict to git-changed files), plus on `search`: `--visibility pub|priv`, `--async-only` / `--no-async`, `--static-only`, `--sealed-only`, `--context-path <file>` (proximity boost), and `--why` (JSON trace of per-channel FST / BM25 / semantic hit counts — use when results look wrong).
|
||||
|
||||
- **Maintenance / diagnostics:** `self-update` (in-place upgrade), `gpu [device]` (probe which execution provider actually engages; `--enable` pins `VEX_DEVICE`), `watch` (continuous incremental reindex), `completions <shell>`, `init --agents-md` (emit an `AGENTS.md`), `eval` (ranking-regression harness for CI).
|
||||
|
||||
## Wire it into `CLAUDE.md`
|
||||
|
||||
Installing the binaries and building an index isn't enough — Claude won't reliably prefer `vex` over `Grep`/`Read` unless a `CLAUDE.md` tells it to.
|
||||
|
||||
**Start from upstream**, don't duplicate. The vex README maintains a canonical `CLAUDE.md` snippet — see [`README.md` → "CLAUDE.md Integration"](https://github.com/tenatarika/vex#claudemd-integration). Paste it into your **global** `~/.claude/CLAUDE.md` (applies to every project) or a **project-local** `./CLAUDE.md` (overrides global per repo).
|
||||
|
||||
**Then graft on these local additions** — they go beyond what upstream covers and are worth keeping wherever you install vex:
|
||||
|
||||
1. **MCP server line** — add this near the top of the snippet so Claude knows the MCP route exists:
|
||||
|
||||
> Equivalent **MCP tools** are also available via the `vex` MCP server when registered (`vex mcp install --agent claude-code`, or manually `claude mcp add vex -s user`) — prefer them inside a Claude Code session for cheaper token output; use the Bash CLI from subagents, hooks, and scripts (and for CLI-only features like `pattern`, `paths`, `reachable`, `diff`, `history`, and the `--strict` / `--why` flags).
|
||||
|
||||
2. **Skip-vex rule** — add to the Rules block:
|
||||
|
||||
> **Skip vex** for non-code text — config files (YAML/JSON/TOML), docs, log strings, free-form prose — and for files in languages vex doesn't parse. Fall back to the next tool in the priority chain that's actually capable for the case (typically Grep/Glob for free-form text).
|
||||
|
||||
3. **Subagent reminder** — add to the Rules block:
|
||||
|
||||
> **Subagents** (Plan/Explore/general-purpose) don't inherit project CLAUDE.md or the parent's MCP toolset — explicitly tell them in the prompt to use `vex` via Bash for code search.
|
||||
|
||||
4. **`auto_update` accuracy fix** — upstream says "Run `vex update` after modifying source files if `auto_update` is not enabled." With `auto_update = true` it runs before *each search*, so during a Claude session the manual update is rarely needed. Reword as:
|
||||
|
||||
> **Run `vex update` manually after editing** only if `auto_update = false`; with `auto_update = true`, vex auto-refreshes before each search.
|
||||
|
||||
5. **`--semantic` cost note** — append to the `vex index --semantic` line in the Indexing block:
|
||||
|
||||
> downloads ~86 MB ONNX model on first run, enables `vex search --semantic`, `vex similar`, `vex duplicates`.
|
||||
|
||||
**When to put it in global vs project CLAUDE.md:**
|
||||
|
||||
- **Global (`~/.claude/CLAUDE.md`)** — preferred default once `vex-mcp` is registered at user scope. Vex becomes the recommendation for every project as soon as the index is built.
|
||||
- **Project-local (`./CLAUDE.md`)** — for overrides (different fallback chain, monorepo-specific `--filter` paths, language-specific `--kind` defaults, or excluding vex on repos where it isn't set up).
|
||||
|
||||
## Caveats (as of v1.16.0)
|
||||
|
||||
vex is young but maturing fast — several earlier quirks are now fixed: `implementations` detects generic-parameterized subclasses (`class Foo(Base[T])`) since v1.7.0; `usages` is AST-precise by default with binder-resolved `--strict` refs (Rust/TS/Python/C#/C++) since v1.8.0 — no longer the text-flavored matcher it once was; prebuilt Windows binaries removed the build-from-source requirement.
|
||||
|
||||
**Still invisible to `usages` in both modes:** decorator-based dispatch (`@router.get`), string-resolved targets (Celery task names, Uvicorn factory strings), reflection / `getattr`, and dynamic imports — before any rename or delete, backstop with `vex grep '\bName\b'`. Verify load-bearing results against `ast-index` or `Grep`.
|
||||
|
||||
## vex vs AST Index — when each wins
|
||||
|
||||
Both tools cover similar ground, but they're not interchangeable. For a point-in-time head-to-head on a real mixed-language repo (Python / Kotlin / TypeScript / JavaScript) with measured latency, quality differences, and version-pinned findings, see [`code-search-vex-vs-ast-index.md`](code-search-vex-vs-ast-index.md). Headline: keep `vex` as primary, fall back to `ast-index changed --base <branch>` for code-review diffs (no vex equivalent) and to `ast-index symbol`/`usages` when vex's textual matches are too noisy.
|
||||
Reference in New Issue
Block a user