xindex 1.0.10 → 1.0.12

package/README.md

@@ -1,8 +1,13 @@
 # xindex
 
 **grep matches text. xindex matches meaning.**
+Fully local, no cloud, no API keys, instant response.
 
-Local semantic code search for your codebase — plus an MCP server so Claude Code (and any MCP client) can search your repo directly. Fully local, no cloud, no API keys.
+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 server so Claude Code searches your repo directly. 
+Fewer hallucinations, fewer round-trips.
 
 ## Install
 
@@ -12,7 +17,7 @@ Requires **Node ≥22**.
 npm i -g xindex
 ```
 
-First run downloads a small embedding model (`all-MiniLM-L6-v2`, ~23MB). After that, fully offline.
+First run downloads a small embedding model (~23MB). After that, fully offline.
 
 ## Quick start
 
@@ -26,7 +31,16 @@ Index lives in `./.xindex/` — add it to `.gitignore`.
 
 ## Use with Claude Code (MCP)
 
-Drop this into `.mcp.json` at your project root — **no install required**, `npx` fetches and runs it on demand:
+### Zero-install, all projects
+
+```bash
+claude mcp add --scope user xindex -- npx xindex
+# remove later: claude mcp remove xindex --scope user
+```
+
+### Per-project
+
+Drop this into `.mcp.json` at the repo root — `npx` fetches on demand:
 
 ```json
 {
@@ -39,12 +53,12 @@ Drop this into `.mcp.json` at your project root — **no install required**, `np
 }
 ```
 
-Prefer a global install? Two steps:
+### With a global install
 
-1. Install: `npm i -g xindex`
-2. Use: set `"command": "xindex-mcp"` with `"args": []` in `.mcp.json`.
+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. Fewer hallucinations, fewer round-trips.
+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
 
@@ -54,11 +68,11 @@ Open the project in Claude Code — it picks up the xindex MCP server and can ca
 - **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** — tolerates unreadable files, oversize files, empty files, binary files, and symlinks; each is skipped with a log line so the run always finishes
+- **Tolerant** — unreadable, oversize, empty, binary files and symlinks are skipped;
 
 ## Claude Code skills (`@xi`)
 
-Two optional [Claude Code skills](https://docs.claude.com/en/docs/claude-code/skills) wrap the MCP tools so you don't have to think about them:
+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.
@@ -67,21 +81,23 @@ Keeping them separate keeps `@xi` safe to fire casually while destructive ops st
 
 ### Install
 
-Pick one — project-scoped or user-global:
+Pick a scope — project (checked in, shared with the repo) or user-global (available in every project):
 
 ```bash
-# Project (checked in, shared with the repo)
-mkdir -p .claude/skills/ask-xi .claude/skills/xindex
-
-# Or user-global (available in every project)
-mkdir -p ~/.claude/skills/ask-xi ~/.claude/skills/xindex
+# project-scoped
+SKILLS=.claude/skills
+```
+```bash
+# OR user-global
+SKILLS=~/.claude/skills
 ```
 
-Then drop these two files in.
+Then copy-paste the block below to create both skills:
 
-`ask-xi/SKILL.md`:
+```bash
+mkdir -p "$SKILLS/ask-xi" "$SKILLS/xindex"
 
-````md
+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.
@@ -96,11 +112,9 @@ Surface-level codebase discovery via xindex. Tool: `xindex_search` (natural-lang
 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).
-````
-
-`xindex/SKILL.md`:
+EOF
 
-````md
+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.
@@ -118,9 +132,10 @@ Full xindex tool management. For research, use `/ask-xi`. Install: `npm i -g xin
 **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 skills.
+Both skills assume the `xindex` MCP server is registered (see the section above). Restart Claude Code after adding.
 
 ---
 
@@ -129,46 +144,50 @@ Both skills assume the `xindex` MCP server is registered (see the section above)
 All five binaries run from any directory; they index/search the current working directory.
 
 ### `xindex-index [paths...]`
-Build or update the index. Defaults to `.` if no paths given.
+
+Build or update the index. Defaults to `.`.
+
 ```bash
 xindex-index .
 xindex-index apps features
 ```
 
 ### `xindex-search <query...>`
-Search the index. All args are joined into one query. Default limit: 7.
+
+Search the index. Args are joined into one query. Default limit: 7.
+
 ```bash
 xindex-search "database migration logic"
 xindex-search file watcher debounce
 ```
 
 ### `xindex-watch [paths...]`
-Initial index + filesystem watch for incremental updates. Uses a lock file so only one watcher owns updates at a time. Ctrl+C releases cleanly.
+
+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.
+
 ```bash
 xindex-watch .
 ```
 
 ### `xindex-reset`
+
 Wipe and recreate the index. Destructive.
+
 ```bash
 xindex-reset
 ```
 
 ### `xindex-mcp`
-Run as an MCP stdio server. Starts a background watcher by default.
-```bash
-xindex-mcp                   # with watch
-xindex-mcp --watch-disabled  # no watch
-xindex-mcp --watch-dir=./src # watch a specific dir
-```
 
-## MCP tools
+MCP stdio server; background watcher by default. Flags: `--watch-disabled`, `--watch-dir=./src` — rare use cases; defaults are fine for most setups.
 
-- **`xindex_search`** — semantic search. `query: string`, `limit?: number` (default 7, max 50)
-- **`xindex_index`** — index paths. `inputs: string[]` (at least one)
-- **`xindex_reset`** — wipe index (destructive). No input
+## MCP tools
 
-Note: both CLI `xindex-search` and MCP `xindex_search` default to 7 results; MCP caps at 50.
+- **`xindex_search`** — semantic search. `query: string`, `limit?: number` (default 7, max 50).
+- **`xindex_index`** — index paths. `inputs: string[]` (at least one).
+- **`xindex_reset`** — wipe index (destructive). No input.
 
 ## Configuration
 
@@ -177,29 +196,33 @@ Note: both CLI `xindex-search` and MCP `xindex_search` default to 7 results; MCP
 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 `[]`. Extra globs excluded during walk/watch, on top of `.gitignore` — add vendored/generated folders.
+- **`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.
 - **`maxFileBytes`** — `number`, default `50000`. Skip files over this (50 KB) — raise to index larger generated files.
-- **`followSymlinks`** — `boolean`, default `false`. When `false`, symbolic links encountered during walk/watch are skipped with a log line. Set `true` to follow them (cycles are broken via `realpath` dedup).
+- **`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):
 
 ```json
 {
   "ignoreKeywords": ["import", "export", "function", "const"],
-  "ignoreFiles": ["dist/**", "node_modules/**", ".xindex"]
+  "ignoreFiles": [".xindex", "node_modules", "dist/**"],
+  "maxLines": 30,
+  "maxFileBytes": 50000,
+  "followSymlinks": false
 }
 ```
 
-Override only what you need; re-run `xindex-index .` (or let the watcher pick it up). Invalid JSON throws; wrong-typed fields fall back silently.
+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
 
-Created automatically. Contains:
-- `semantic/` — the vectra index (vectors + metadata)
-- `lock.json` — watcher lock (coordinates watch/MCP processes)
+Auto-created. Contains:
 
-**Always gitignore it.**
+- `semantic/` — the semantic index (vectors + metadata)
+- `lock.json` — watcher lock (coordinates watch/MCP processes)
 
-### `.gitignore` minimum
+**Always gitignore it** — it's already excluded from the walk by default, this is just for git:
 
 ```
 .xindex
@@ -211,10 +234,10 @@ node_modules/
 ```
   your repo                      xindex
   ─────────                      ──────
-  *.ts / *.md  ──►  walk  ──►  keywords  ──►  embed  ──►  .xindex/
-  .gitignore                                              (vectra index)
-                                                              ▲
-  CLI / MCP  ◄──  search  ◄──  embed query  ◄──  "question"  ┘
+  *.ts / *.md  ──►  walk  ──►  embed  ──►  .xindex/
+  .gitignore                                (semantic index)
+                                                ▲
+  CLI / MCP  ◄──  search  ◄──  embed  ◄──  "question"  ┘
 ```
 
 ## Project layout
@@ -222,7 +245,7 @@ node_modules/
 ```
 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, vectra adapter, logger
+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)
@@ -234,21 +257,19 @@ See [CLAUDE.md](CLAUDE.md) for contributor conventions (HOF pattern, logger rule
 
 ## Development
 
-Working on xindex itself? Clone and link:
-
-```bash
-git clone <repo-url> xindex
-cd xindex
-yarn install   # or npm install
-npm link       # exposes xindex-* binaries from your working copy
-```
-
-Check TypeScript compilation:
+Working on xindex itself? From your working copy:
 
 ```bash
+yarn install        # or npm install
+npm link            # exposes xindex-* binaries from this checkout
 yarn test.compilation
 ```
 
 ## License
 
 MIT
+
+## Links
+
+- [Claude Code skills](https://docs.claude.com/en/docs/claude-code/skills)
+

package/apps/mcpApp.ts

@@ -39,8 +39,11 @@ export function McpApp({
         // --- search ---
 
         server.registerTool("xindex_search", {
-            title: "Search codebase",
-            description: "Semantic search over indexed codebase files. Returns scored results with file paths and keywords.",
+            title: "Search codebase (semantic)",
+            description: "Semantic codebase search — finds files by meaning, not substring. " +
+                "For discovery, run 3–7 parallel queries then narrower follow-ups. " +
+                "Returns ranked file paths + matched keywords (links, not analysis). " +
+                "If sparse, run `xindex_index` on relevant roots first (scoped, one path per call).",
             inputSchema: z.object({
                 query: z.string()
                     .describe("Natural language search query"),
@@ -65,11 +68,12 @@ export function McpApp({
 
         server.registerTool("xindex_index", {
             title: "Index files or directories",
-            description: "Index files or directories for semantic search. " +
-                "Accepts file paths or directory paths. Directories are walked recursively, respecting .gitignore.",
+            description: "Index files/directories for semantic search; recursive, respects .gitignore. " +
+                "Prefer scoped paths (one per call, e.g. `src`, `apps`) over full-repo `['.']` — " +
+                "reserve the latter for first-time setup or cross-cutting discovery.",
             inputSchema: z.object({
                 inputs: z.array(z.string()).min(1)
-                    .describe("File or directory paths to index"),
+                    .describe("File or directory paths to index (one path per call preferred; scoped over full-repo)"),
             }),
         }, async ({inputs}) => {
             try {
@@ -89,9 +93,9 @@ export function McpApp({
         // --- reset ---
 
         server.registerTool("xindex_reset", {
-            title: "Reset index",
-            description: "Delete and recreate the search index. " +
-                "Always ask the user for explicit confirmation before running this tool.",
+            title: "Reset index (destructive)",
+            description: "Wipe and recreate the semantic index. **Destructive** — MUST get explicit user confirmation; " +
+                "if ambiguous, don't run. Recovery / reindex flow: confirm → `xindex_reset` → `xindex_index(['.'])` → `xindex_search`.",
             inputSchema: z.object({}),
             annotations: {destructiveHint: true},
         }, async () => {

package/componets/config/loadConfig.ts

@@ -24,7 +24,8 @@ export function LoadConfig({configPath, log}: { configPath: string, log: ILogger
             raw = await readFile(configPath, "utf8");
         } catch (e: any) {
             if (e?.code === "ENOENT") return {...DEFAULTS};
-            throw new Error(`Cannot read ${configPath}: ${e?.message ?? e}`);
+            log(`warning: cannot read ${configPath}: ${e?.message ?? e} — using defaults`);
+            return {...DEFAULTS};
         }
 
         if (!raw.trim()) return {...DEFAULTS};
@@ -33,7 +34,8 @@ export function LoadConfig({configPath, log}: { configPath: string, log: ILogger
         try {
             parsed = JSON.parse(raw);
         } catch (e) {
-            throw new Error(`Failed to parse ${configPath}: ${e instanceof Error ? e.message : e}`);
+            log(`warning: failed to parse ${configPath}: ${e instanceof Error ? e.message : e} — using defaults`);
+            return {...DEFAULTS};
         }
 
         const toStrings = (v: unknown) => Array.isArray(v) ? v.filter((e): e is string => typeof e === "string") : [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xindex",
-  "version": "1.0.10",
+  "version": "1.0.12",
   "description": "Local semantic code search — index codebase, search by meaning or keywords",
   "type": "module",
   "main": "xindex.ts",