xindex

is a semantic search.

grep matches text. xindex matches meaning. Fully local, no cloud, no API keys, instant response.

Ask "where is auth handled?" — get the right files, even when they don't contain the word auth.

Local semantic code search for your codebase, w/ an MCP so Claude Code searches your repo directly.

Fewer hallucinations, fewer round-trips.

Install

Requires Node ≥22.

npm i -g xindex

First run downloads a small embedding model (~23MB). After that, fully offline.

Quick start

cd /path/to/your/project
xindex-index .                         # build the index
xindex-search "where is auth handled"  # ask a question

Index lives in ./.xindex/ — add it to .gitignore.

Use with Claude Code (MCP)

Zero-install, all projects

claude mcp add --scope user xindex -- npx -y xindex
# remove later: claude mcp remove xindex --scope user

Use npx -y so npx does not wait for confirmation when it must fetch the package (MCP often runs without a TTY). If npm still errors on peer resolution, install globally with npm i -g xindex --legacy-peer-deps and point MCP at xindex-mcp instead (see below).

Per-project

Drop this into .mcp.json at the repo root — npx fetches on demand:

{
  "mcpServers": {
    "xindex": {
      "command": "npx",
      "args": ["-y", "xindex"]
    }
  }
}

With a global install

1. npm i -g xindex
2. In .mcp.json, set "command": "xindex-mcp" with "args": [].

Open the project in Claude Code — it picks up the xindex MCP server and can call xindex_search, xindex_index, and xindex_reset directly.

Features

• Local — everything runs on your machine; embeddings cached on disk
• Semantic search — natural-language queries, not substring match
• MCP server — plugs into Claude Code via .mcp.json
• Watch mode — keeps the index warm while you code
• Gitignore-aware — respects .gitignore + custom ignore rules
• Zero config — works with defaults; .xindex.json is optional
• Tolerant — unreadable, oversize, empty, binary files and symlinks are skipped;

Claude Code skills (@xi)

Two optional Claude Code skills wrap the MCP tools so you don't have to think about them:

• ask-xi — read-only discovery. @xi where is auth handled drafts several focused queries, runs xindex_search for each, and returns ranked file paths with matched keywords. Use it as a cheap first step before grepping or asking a heavier model.
• xindex — index management (xindex_index, xindex_reset). Reset requires explicit confirmation every time.

Keeping them separate keeps @xi safe to fire casually while destructive ops stay behind the xindex skill.

Install

Pick a scope — project (checked in, shared with the repo) or user-global (available in every project):

# project-scoped
SKILLS=.claude/skills

# OR user-global
SKILLS=~/.claude/skills

Then copy-paste the block below to create both skills:

mkdir -p "$SKILLS/ask-xi" "$SKILLS/xindex"

cat > "$SKILLS/ask-xi/SKILL.md" <<'EOF'
---
name: ask-xi
description: Discovers relevant files via xindex semantic search — preps queries, auto-indexes on empty, returns file links with keywords. Triggered by @xi.
argument-hint: "[question]"
---
Surface-level codebase discovery via xindex. Tool: `xindex_search` (natural-language, meaning-based). Must trigger search when a session starts, a new task starts, or any codebase lookup is needed.

**Steps:**
1. Draft 3–5 queries from $ARGUMENTS (entry points, routing, config, tests, patterns); run `xindex_search` in parallel.
2. If empty/sparse/stale → scoped `xindex_index` on relevant root folders (one path per call, e.g. `src`, `skills`, `agents`), then re-search. Prefer scoped over full-repo.
3. Think, then run 3+ narrower follow-ups in parallel based on round-1 hits.
4. Return file paths + brief keywords showing why each matched.

Output = file links + keywords, not analysis. **Escalate to `/ask-cursor` by default** (cheap codebase reasoning); only go to `/ask-claude` for multi-file/pattern analysis or `/ask-claude-opus` for trade-offs. For reset or full re-index, delegate to `/xindex` (owns safety rules).
EOF

cat > "$SKILLS/xindex/SKILL.md" <<'EOF'
---
name: xindex
description: Manages xindex semantic search — index, search, reset via MCP tools. For research questions, use /ask-xi.
argument-hint: "[search query | index | reset]"
---
Full xindex tool management. For research, use `/ask-xi`. Install: `npm i -g xindex`, or user MCP `claude mcp add --scope user xindex -- npx -y xindex` ([npm](https://www.npmjs.com/package/xindex)).

**Tools:**
- `xindex_search` — find files by meaning (synonyms, semantics). Try before grepping blindly.
- `xindex_index` — index a path (recursive, respects .gitignore). **MUST** run one path per call.
- `xindex_reset` — destructive wipe+rebuild. **MUST** get explicit user confirmation every time; if ambiguous, don't run.

**Workflow:** stale/corrupt → confirm → `xindex_reset` → `xindex_index(["."])` → `xindex_search`. Incremental → one-path `xindex_index(["changed/path"])` calls.

**Scoped indexing (preferred):** index only task-relevant content-heavy folders, sequentially. Full-repo `xindex_index(["."])` only for cross-cutting discovery.

$ARGUMENTS
EOF

Both skills assume the xindex MCP server is registered (see the section above). Restart Claude Code after adding.

CLI reference

All six binaries run from any directory; they index/search the current working directory.

xindex-index [paths...]

Build or update the index. Defaults to ..

xindex-index .
xindex-index apps features

xindex-search <query...>

Search the index. Args are joined into one query. Default limit: 7 (capped by searchMaxLimit, default 12).

xindex-search "database migration logic"
xindex-search file watcher debounce

xindex-watch [paths...]

Initial index + filesystem watch for incremental updates. Lockfile coordinates concurrent watchers; Ctrl+C releases cleanly.

Bundled inside xindex-mcp — no need to run separately in the primary MCP use case.

xindex-watch .

xindex-reset

Wipe and recreate the index. Destructive.

xindex-reset

xindex-reindex [paths...]

Reset the index, then build it again. Same as xindex-reset followed by xindex-index. Defaults to ..

xindex-reindex
xindex-reindex apps features

xindex-mcp

MCP stdio server; background watcher by default. Flags: --watch-disabled, --watch-dir=./src — rare use cases; defaults are fine for most setups.

MCP tools

• xindex_search — semantic search. query: string, limit?: number (default 7, capped at searchMaxLimit from .xindex.json, default 12).
• xindex_index — index paths. inputs: string[] (at least one).
• xindex_reset — wipe index (destructive). No input.

Configuration

.xindex.json (optional)

Project-root file. All fields optional; unknown keys ignored; missing/empty → defaults.

• ignoreKeywords — string[], default []. Tokens stripped before embedding — add project slang/boilerplate polluting results. Entries ≤1 char warn.
• ignoreFiles — string[], default ['.xindex', 'node_modules']. Extra globs excluded during walk/watch, on top of .gitignore. Setting this replaces the default — re-include .xindex and node_modules if you still want them skipped.
• maxLines — number, default 30. Lines per chunk — tune if chunks feel over/under-sized.
• searchDefaultLimit — number, default 7. Results per search when no limit is passed.
• searchMaxLimit — number, default 12. Hard cap on limit (MCP and CLI); values above this are clamped. searchDefaultLimit cannot exceed this.
• searchPrefetchMultiplier — number, default 2. Candidate over-fetch factor: candidates ≈ limit × this. Lower = fewer per-query embeddings (faster) at some cost to recall.
• queryConcurrency — number, default 6. Max search queries running at once; further queries queue.
• embedConcurrency — number, default ≈ CPU core count. Parallel embeddings within a query. Embedding is CPU-bound — keep near core count to avoid thrash.
• searchConcurrency — deprecated. If set (and the two knobs above are absent), it seeds both queryConcurrency and embedConcurrency for backward compatibility.
• maxFileBytes — number, default 50000. Skip files over this (50 KB) — raise to index larger generated files.
• followSymlinks — boolean, default false. When false, symlinks are skipped with a log line. true follows them (cycles broken via realpath dedup).

Full example with every option (copy-paste and trim what you don't need):

{
  "ignoreKeywords": ["import", "export", "function", "const"],
  "ignoreFiles": [".xindex", "node_modules", "dist/**"],
  "maxLines": 30,
  "searchDefaultLimit": 7,
  "searchMaxLimit": 12,
  "searchPrefetchMultiplier": 2,
  "queryConcurrency": 6,
  "embedConcurrency": 8,
  "maxFileBytes": 50000,
  "followSymlinks": false
}

Override only what you need; re-run xindex-index . (or let the watcher pick it up on restart). Invalid JSON or unreadable config warns and falls back to defaults; wrong-typed fields fall back silently.

.xindex/ folder

Auto-created. Contains:

• semantic/ — the semantic index (vectors + metadata)
• lock.json — watcher lock (coordinates watch/MCP processes)

Always gitignore it — it's already excluded from the walk by default, this is just for git:

.xindex
node_modules/

How it fits together

  your repo                      xindex
  ─────────                      ──────
  *.ts / *.md  ──►  walk  ──►  embed  ──►  .xindex/
  .gitignore                                (semantic index)
                                                ▲
  CLI / MCP  ◄──  search  ◄──  embed  ◄──  "question"  ┘

Project layout

apps/        entry points (run.*.ts) + app composers (IndexApp, SearchApp, McpApp, ...)
bin/         shebang wrappers invoked by npm and .mcp.json
componets/   shared building blocks: config, walk, watch, embed, index adapter, logger
features/    domain operations: indexContent, searchIndex, removeContent, resetIndex
packages/    small internal libs (streamx, fun)
.xindex/     runtime data (gitignored)
.xindex.json optional config
.mcp.json    MCP registration for Claude Code / compatible clients

See CLAUDE.md for contributor conventions (HOF pattern, logger rules, task workflow).

Development

Working on xindex itself? From your working copy:

yarn install        # or npm install
npm link            # exposes xindex-* binaries from this checkout
yarn test.compilation

License

MIT

Links

• Claude Code skills