{"id":50478670,"url":"https://github.com/uwuclxdy/claudix","last_synced_at":"2026-06-01T15:31:53.530Z","repository":{"id":354632925,"uuid":"1224026250","full_name":"uwuclxdy/claudix","owner":"uwuclxdy","description":"Semantic search plugin for Claude Code using LMStudio, Ollama or any OpenAI-compatible API","archived":false,"fork":false,"pushed_at":"2026-05-31T11:14:28.000Z","size":1707,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"mommy","last_synced_at":"2026-05-31T13:09:10.886Z","etag":null,"topics":["claude-code","claude-code-plugin","semantic-search","vibecoded"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/uwuclxdy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-28T22:21:00.000Z","updated_at":"2026-05-31T11:14:32.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/uwuclxdy/claudix","commit_stats":null,"previous_names":["uwuclxdy/claudix"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/uwuclxdy/claudix","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uwuclxdy%2Fclaudix","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uwuclxdy%2Fclaudix/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uwuclxdy%2Fclaudix/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uwuclxdy%2Fclaudix/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/uwuclxdy","download_url":"https://codeload.github.com/uwuclxdy/claudix/tar.gz/refs/heads/mommy","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uwuclxdy%2Fclaudix/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33782314,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-01T02:00:06.963Z","response_time":115,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude-code","claude-code-plugin","semantic-search","vibecoded"],"created_at":"2026-06-01T15:31:52.911Z","updated_at":"2026-06-01T15:31:53.524Z","avatar_url":"https://github.com/uwuclxdy.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n![claudix banner](media/claudix.png)\n\n![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/uwuclxdy/claudix/.github%2Fworkflows%2Frelease.yml?style=for-the-badge\u0026cacheSeconds=60)\n![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/uwuclxdy/claudix/total?style=for-the-badge\u0026color=%2343ABE5\u0026cacheSeconds=60)\n![Claude Code](https://img.shields.io/badge/Claude%20Code-D97757?style=for-the-badge)\n\n# Claude Index: claudix\n\n\u003c/div\u003e\n\nCopilot's Codebase Index but for Claude Code. Automatically indexes your repo, embeds with the embedding model of choice and provides semantic search through Claude's slash commands, MCP tools, and grep interception.\n\n## What It Does\n\nclaudix is a Claude Code plugin that gives the agent local semantic search over any repository. A single Rust binary acts as MCP server, hook handler, and CLI. When Claude Code starts, claudix warmly bootstraps the index if missing. When you edit files, chunks are re-embedded automatically. When grep would be less useful than semantic search, the plugin intercepts and uses dense vectors instead. Configuration lives next to `settings.json` with optional per-project overrides. First-class language support includes Python, JavaScript, Java, C, C++, C#, SQL, Rust, TypeScript, and Go.\n\nCore design goal: never break the session, always recover gracefully.\n\n## Requirements\n\n- **macOS 11+ (Apple Silicon)** or **Linux x86_64** (glibc 2.28+ or musl) or **Windows 10+ x86_64**\n- **Rust 1.83+**\n- **Optional**: LM Studio or Ollama for custom embedding backends (\n  - bundled `bge-small-en-v1.5` requires `libonnxruntime` or `onnxruntime.dll`)\n\n## Installation\n\n**Requires**: Claude Code 2.0.12+.\n\nclaudix ships the bundled `bge-small-en-v1.5` embedder and uses it as the fallback when no embedding provider is configured. Set `embedding.provider = \"http\"` if you prefer LM Studio, Ollama, or another OpenAI-compatible embedding server.\n\n### Linux / macOS\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/uwuclxdy/claudix/mommy/install.sh | bash\n```\n\n### Windows\n\n```powershell\nirm https://raw.githubusercontent.com/uwuclxdy/claudix/mommy/install.bat | iex\n```\n\n### Manual\n\n```bash\nclaude plugin marketplace add uwuclxdy/claudix\nclaude plugin install claudix@claudix\n```\n\nThe native binary downloads on first session (~150MB). Restart Claude Code, then run `/claudix:doctor` to verify.\n\nTargets without a prebuilt (e.g. linux-aarch64, darwin-x86_64) fall back to `cargo install claudix@\u003cversion\u003e`. Install [Rust](https://rustup.rs) first if you are on one of those.\n\n## Configuration\n\nConfiguration lives in two TOML files (project overrides global):\n\n- **Global**: `~/.claude/claudix.toml`\n- **Project**: `\u003crepo\u003e/.claude/claudix.toml`\n\nBoth optional. If neither file sets an embedding provider, bundled defaults and the `bge-small-en-v1.5` embedder are used. Run `/claudix:doctor` to see active configuration.\n\n### Full Schema (defaults)\n\n```toml\n[embedding]\nprovider = \"bundled\"                # bundled | http\nendpoint = \"\"                       # required if provider = http (e.g., http://localhost:1234)\nmodel = \"bge-small-en-v1.5\"\ndimensions = 384\nbatch_size = 32\ntimeout_ms = 30000\n\n[indexing]\nrespect_gitignore = true\nfollow_symlinks = false\nmax_file_size_kb = 512              # skip files larger than this\nchunk_overlap_lines = 5             # lines overlapped between chunks\nreindex_after_hours = 24            # background reindex interval\n\n[search]\ntop_k = 10                          # results per search\nhybrid_weights = { dense = 0.55, bm25 = 0.30, rrf = 0.15 }  # hybrid retrieval weights\nidentifier_boost = 1.4              # boost exact identifier matches\nsimilarity_threshold = 0.30         # minimum relevance score\n\n[hooks]\nintercept_grep = true               # replace grep with semantic search when useful\nauto_reembed_on_edit = true         # re-embed after Write/Edit\nsession_start_warmup = true         # ping embedding endpoint on startup\n\n[paths]\nindex_dir = \".claudix/index\"        # relative to repo root; committed to .gitignore\nlog_dir = \"~/.claude/claudix/logs\"\n```\n\nConfiguration is validated at every entry point (MCP, hook, CLI). Invalid config exits early with field-level error messages.\n\n## Slash Commands\n\nAll commands are available as `/claudix:\u003cname\u003e`:\n\n| Command | Description | Arguments |\n|---------|-------------|-----------|\n| `/claudix:search` | Semantic code search | `\u003cquery\u003e [--top-k N] [--language rust --language python] [--path-prefix src/]` |\n| `/claudix:index` | Build or refresh index | (none) |\n| `/claudix:status` | Show index metadata | (none) |\n| `/claudix:doctor` | Diagnose health | (none) |\n| `/claudix:reindex-file` | Re-embed one file | `\u003cpath\u003e` |\n| `/claudix:clear` | Delete index | (none) |\n\n### Search Example\n\n```\n/claudix:search authentication flow --language rust --top-k 5\n```\n\nResults show file path, line range, language, definition kind, name, and relevance score.\n\n## How It Works\n\n### SessionStart Hook\n\nOn first session or after plugin upgrade, the `SessionStart` hook:\n\n1. Checks that plugin files and global config are present\n2. Emits `claudix ready` via `systemMessage` when setup is complete\n3. Tells the user to rerun the install script if setup is incomplete\n4. Kicks off the background update check\n\nIf anything fails, the hook exits 0 (fail-open): session continues unaffected.\n\n### PostToolUse Hook (File Edit)\n\nAfter `Write`, `Edit`, or `MultiEdit` tools, the hook:\n\n1. Reads edited file path from tool input\n2. Invokes `claudix hook PostToolUse \u003cpath\u003e`\n3. Atomically upserts new chunks, removes stale ones\n4. Index stays live without a watcher\n\n### PreToolUse Hook (Grep Intercept)\n\nBefore `Grep` or `Bash` tools (with `rg`, `grep`, `ag` commands), the hook:\n\n1. Analyzes query for regex patterns, globs, short length\n2. Checks if index is stale or missing\n3. If index is fresh and query looks conceptual, returns:\n   ```json\n   {\n     \"hookSpecificOutput\": {\n       \"hookEventName\": \"PreToolUse\",\n       \"permissionDecision\": \"deny\",\n       \"permissionDecisionReason\": \"Use the claudix.search_code MCP tool for semantic queries; this query looks conceptual.\",\n       \"additionalContext\": \"Original query was '\u003cquery\u003e'. The claudix search index has \u003cN\u003e chunks across \u003cM\u003e files.\"\n     }\n   }\n   ```\n4. Otherwise allows grep to proceed\n\nHeuristics for passthrough: regex anchors/character classes, explicit file globs, \u003c3 tokens, stale index, `intercept_grep = false`.\n\n### MCP Tool: `search_code`\n\nClaude invokes `claudix.search_code(query, language_filter, path_prefix)` directly. Uses hybrid retrieval: dense vector (55%), BM25 (30%), reciprocal rank fusion (15%). Returns ranked list with file location, definition kind, name, line range, and score.\n\n## Embedding Backends\n\n### Bundled (Default)\n\n`bge-small-en-v1.5` runs via ONNX Runtime on CPU. No external dependencies. ~100ms/chunk on modern hardware.\n\nRequires: `libonnxruntime` (Linux) or `onnxruntime.dll` (Windows) installed in system library path, or downloaded automatically.\n\n### LM Studio\n\nLocal LLM inference server. Download [lm-studio.ai](https://lm-studio.ai), load an embedding model (e.g., `nomic-ai/nomic-embed-text-v1.5`), start the server.\n\n```toml\n[embedding]\nprovider = \"http\"\nendpoint = \"http://localhost:1234\"\nmodel = \"your-model-name\"\n```\n\n### Ollama\n\nLocal inference. Install [ollama.ai](https://ollama.ai), pull embedding model:\n\n```bash\nollama pull nomic-embed-text\n```\n\nConfigure:\n\n```toml\n[embedding]\nprovider = \"http\"\nendpoint = \"http://localhost:11434\"\nmodel = \"nomic-embed-text\"\n```\n\nAll three backends return 384-dimensional vectors (for bge-small); other models may differ. Dimension mismatch triggers reindex.\n\n## Building from Source\n\nRequires **Rust 1.83+** and **Cargo**.\n\n```bash\ngit clone \u003crepo\u003e\ncd claudix\ncargo build --release\n```\n\nTest suite:\n\n```bash\ncargo test --lib                    # unit tests only\ncargo test --test integration       # integration tests (~10s)\ncargo test --all -- --include-ignored  # all tests including e2e (~30s)\n```\n\nBinary is `target/release/claudix`. Strip for distribution:\n\n```bash\nstrip target/release/claudix\n```\n\nLinux musl builds are statically linked:\n\n```bash\ncargo build --release --target x86_64-unknown-linux-musl\n```\n\n## Troubleshooting\n\n### Check Plugin Health\n\n```\n/claudix:doctor\n```\n\nDiagnostic output:\n\n- Project root\n- Index present (yes/no)\n- Chunk and file counts\n- Active embedding model\n- Embedding provider and health (reachable or error)\n- Configuration errors\n\n### Index Missing or Stale\n\n```\n/claudix:index\n```\n\nFull reindex takes ~1-5 minutes depending on repo size. Incremental updates (on file edit) take milliseconds.\n\n### Embedding Endpoint Unreachable\n\nIf using LM Studio or Ollama:\n\n1. Verify server is running: `curl http://localhost:1234/health` (LM Studio) or `curl http://localhost:11434/api/embeddings` (Ollama)\n2. Check configuration: `/claudix:doctor` shows `endpoint` in use\n3. Switch to bundled: set `provider = \"bundled\"` in `~/.claude/claudix.toml`, then run `/claudix:index` to reindex\n\n### Hooks Don't Trigger or Fail Silently\n\nSessionStart hook exits 0 even on error. Check logs:\n\n```bash\ntail -f ~/.claude/claudix/logs/claudix.log\n```\n\nLogs are created on first run. Enable debug logging:\n\n```bash\nRUST_LOG=debug /claudix:status  # or any other command\n```\n\n### Schema Mismatch After Upgrade\n\nIf the binary is newer than indexed chunks, SessionStart triggers background reindex and emits `additionalContext`. You can manually reindex with `/claudix:clear` then `/claudix:index`.\n\n## Fail-Open Guarantee\n\n**Hooks never fail the session.**\n\n- Binary missing → hook exits 0, session proceeds\n- Embedding endpoint down → hook exits 0, grep proceeds normally\n- Index corrupted → hook exits 0, search MCP tool returns error with recovery hint\n- Configuration invalid → caught at startup; MCP tool returns error message\n\nMCP tool errors are structured JSON with a `recovery` field Claude can act on:\n\n```json\n{\n  \"error\": \"embedding_endpoint_unreachable\",\n  \"message\": \"LM Studio at http://localhost:1234 did not respond.\",\n  \"recovery\": \"Run /claudix:doctor to diagnose, or set [embedding] provider = \\\"bundled\\\" in ~/.claude/claudix.toml.\"\n}\n```\n\n## Development\n\nArchitecture is domain-driven (chunking, embedding, store, search, mcp, hooks) rather than kind-driven. Each domain module owns types, traits, and tests. Cross-domain coupling goes through small interface traits.\n\nKey modules:\n\n- `src/chunking/` — tree-sitter code splitting\n- `src/embedding/` — bundled (ONNX) and http (LM Studio, Ollama) providers\n- `src/store/` — LanceDB for vector + FTS\n- `src/search/` — hybrid retrieval\n- `src/mcp/` — Model Context Protocol\n- `src/hooks/` — SessionStart, PostToolUse, PreToolUse handlers\n- `src/cli/` — slash command entry points\n\nTests live next to code (`#[cfg(test)]`) or in `tests/integration/` with fixtures in `tests/fixtures/`.\n\n## License\n\nMIT\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuwuclxdy%2Fclaudix","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fuwuclxdy%2Fclaudix","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuwuclxdy%2Fclaudix/lists"}