██████╗██╗██╗  ██╗
██╔════╝██║╚██╗██╔╝
██║     ██║ ╚███╔╝
██║     ██║ ██╔██╗
╚██████╗██║██╔╝ ██╗
 ╚═════╝╚═╝╚═╝  ╚═╝  Code IndeX

Search your codebase by meaning, not just text. Self-hosted, embeddings-based, works with any agent or terminal — with a full web dashboard and multi-repo workspace search.

cix search "authentication middleware"
cix search "database retry logic" --in ./api --lang go
cix symbols "UserService" --kind class

Or open http://localhost:21847/dashboard in your browser.

Grep and fuzzy file search work fine for small projects. At scale they break down:

• You have to know what a thing is called to find it
• Results flood with noise from unrelated files
• Agents waste tokens scanning files that aren't relevant

cix indexes your code into a vector store using CodeRankEmbed — a model purpose-built for code retrieval. Search queries return ranked snippets with file paths and line numbers, not raw file lists.

• cix-server — Go HTTP API with embedded llama.cpp sidecar for embeddings, SQLite for symbols + metadata, chromem-go for vectors, FTS5 BM25 mirror for hybrid ranking. Ships as a single distroless container.
• Web dashboard at /dashboard — projects, search, users + API keys, runtime sidecar control, drift indicator. Embedded in the server binary. See doc/DASHBOARD.md.
• cix CLI — cix search/symbols/files/workspace … for terminal + agent use. See doc/CLI_REFERENCE.md.
• File watcher — cix watch keeps the index fresh as you edit.
• Workspaces — group multiple repos into one named corpus; cix clones them server-side, indexes them, and runs hybrid BM25 + dense search across the union. GitHub webhooks auto-reindex on push. See workspaces.md.
• Pluggable embeddings — local llama.cpp by default; Voyage AI or any OpenAI-compatible endpoint optional. See Embedding providers.
• Ownership + view-group sharing — every project/workspace has an owner; admins share to named groups. Private by default. See doc/DASHBOARD.md.
• Claude Code plugin — install once and cix becomes the agent's default reflex for code search. See Agent integration.

                  ┌────────────────────────────────────┐
                  │  Browser  →  http://host:21847     │
                  │  • /dashboard  • /docs  • /openapi │
                  └────────────┬───────────────────────┘
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│  cix-server (Go, single distroless binary)                      │
│  HTTP/REST + cookie sessions + Bearer API keys                  │
│  ├── auth, admin, api-keys, projects, indexing, search          │
│  ├── workspaces, github-tokens, webhooks                        │
│  └── embedded React dashboard + Swagger UI                      │
│                                                                 │
│  Indexing pipeline                                              │
│  ├── tree-sitter/wasm (AST chunking, 30+ langs)  (wazero)       │
│  ├── embedding provider (local llama.cpp / Voyage / OpenAI)     │
│  ├── chromem-go (cosine similarity vector store)                │
│  └── SQLite FTS5 mirror (BM25) + metadata (modernc/sqlite)      │
└────────────┬─────────────────────────────────────┬──────────────┘
             │ HTTP                                │ Unix socket
             ▼                                     ▼
   cix CLI (Go)                       ┌──────────────────────────┐
   search · symbols · workspace       │  llama-server child proc │
                                      └──────────────────────────┘

Pure-Go static binary; CUDA-image variants add a CUDA runtime layer for GPU embeddings. Workspace clones live in <data-dir>/repos/.

git clone https://github.com/dvcdsys/code-index && cd code-index
cp .env.example .env
# Edit .env — set CIX_API_KEY, CIX_BOOTSTRAP_ADMIN_EMAIL, CIX_BOOTSTRAP_ADMIN_PASSWORD
docker compose up -d                              # CPU
# docker compose -f docker-compose.cuda.yml up -d # NVIDIA GPU
curl http://localhost:21847/health                # → {"status":"ok"}

For Apple Silicon with full Metal acceleration, run natively (Docker Desktop has no Metal access) — see doc/SETUP_MACOS_NATIVE.md. For shared/team deployment, see doc/TEAM_DEPLOYMENT.md.

Open http://localhost:21847/dashboard, sign in with the bootstrap admin, change the password when prompted. (What's on each page.)

curl -fsSL https://raw.githubusercontent.com/dvcdsys/code-index/main/install.sh | bash
cix config set api.url http://localhost:21847
cix config set api.key $(grep CIX_API_KEY .env | cut -d= -f2)

From source: cd cli && make build && make install. Pre-release develop channel: doc/UPDATES.md.

cd /path/to/your/project
cix init                            # registers + indexes + starts the file watcher
cix status                          # wait for: Status: ✓ Indexed

cix search "authentication middleware"
cix symbols "handleRequest" --kind function
cix summary

Full command surface: doc/CLI_REFERENCE.md. Same five modes are on the dashboard's Search page.

cix is self-hosted first: out of the box it embeds with a bundled llama.cpp sidecar and never sends your code anywhere. The backend is pluggable — switched at runtime from Dashboard → Server (admin only).

Set the API-key env var on the server, then select the provider + model in the dashboard. Switching providers (or a provider's model/dimensions) changes the embedding space, so cix treats it as a new identity and a full reindex is required — vectors aren't comparable across providers.

Choosing: Local for air-gapped / privacy-sensitive repos and zero per-query cost. Voyage AI (voyage-code-3) for top-tier code retrieval without hosting a GPU. OpenAI / compatible to reuse an existing endpoint or internal gateway.

cix is designed to be called by AI agents (Claude, GPT, Cursor, custom agents) as a shell tool — they run cix search instead of Grep/Glob and get ranked snippets rather than raw file dumps.

Claude Code (plugin, recommended). Bundles the cix + cix-workspace skills, the cix-workspace-investigator sub-agent, CLI auto-install hooks, and a grep-nudge:

/plugin marketplace add dvcdsys/code-index
/plugin install cix@code-index
/reload-plugins

Then invoke the skill paired with the actual task (not a search query) — /cix <fix / implement / investigate / refactor …>. cix becomes the agent's IDE (goto-def, find-refs, "what calls this") while it works. Manual install: cp -r skills/cix ~/.claude/skills/cix. For multi-repo work: /cix-workspace <task>. Full hook list + configuration: plugins/cix/README.md.

Claude Desktop & Cowork (MCP). These don't load Claude Code plugins, so cix ships a built-in stdio MCP server exposing the same search as cix_* tools:

cix mcp install claude-desktop      # restart Claude Desktop; cix_* tools appear
/plugin install cix-cowork@code-index   # optional: Cowork skills

The model is server-centric and multi-server (no "current project" — the agent names projects/workspaces explicitly). Full guide: doc/COWORK_MCP.md.

Other agents. Give the agent shell execution and describe the command:

Usage: cix search "what you're looking for" [--in ./subdir] [--lang python]
Returns: ranked code snippets with file paths and line numbers

Most common environment variables (full surface in doc/CONFIG_REFERENCE.md; most are runtime-editable from Dashboard → Server):

The REST surface (auth, users, projects, indexing, search, workspaces, webhooks) is documented at http://<host>:21847/docs (Swagger UI) and in doc/openapi.yaml — the single source of truth the Go interface and TypeScript types are generated from.

• Team / production deployment — topology, volumes, UID/permissions, TLS, backups, upgrades: doc/TEAM_DEPLOYMENT.md.
• GPU (CUDA) — host requirements, VRAM footprint, image base: doc/DOCKER_TAGS.md, doc/vram-profiling.md. Inference runs on GPU automatically with the cu128 image.
• Security hardening — trusted-proxy posture, rate limits, body-size caps, what cix deliberately doesn't do: doc/SECURITY_DEPLOYMENT.md.
• Releases — tagging, CVE scans, Scout workflow, make targets: doc/RELEASES.md.
• Troubleshooting — common errors + search tuning: doc/TROUBLESHOOTING.md.

Pre-built images on Docker Hub:

docker compose logs -f          # tail logs
docker compose down             # stop
docker compose down -v          # stop AND wipe data + models (destructive)

cix stands on a lot of excellent open-source work. Thank you to the projects and teams that make it possible:

Embeddings & models

• llama.cpp — the llama-server sidecar that runs embeddings locally on CPU/GPU.
• CodeRankEmbed by Nomic AI — the default code-retrieval embedding model — and awhiteside/CodeRankEmbed-Q8_0-GGUF for the GGUF quantization cix ships with.
• Voyage AI — voyage-code-3 and the code-specialized embedding API, supported as a first-class provider.
• OpenAI — the text-embedding-3 family and the OpenAI-compatible provider shape.

Indexing & storage

• tree-sitter — AST-aware chunking across 30+ languages, run via wazero (pure-Go WASM runtime).
• gotreesitter — the Go tree-sitter binding cix's AST chunking first grew from; thank you for the head start.
• chromem-go — the embedded cosine-similarity vector store.
• modernc.org/sqlite — cgo-free SQLite for project metadata, symbols, and the FTS5/BM25 mirror.
• go-git — server-side repository cloning for workspaces.

Server & API

• chi — HTTP router.
• kin-openapi + oapi-codegen — OpenAPI-as-source-of-truth codegen for the Go interface and TypeScript dashboard types.
• brotli and the Go standard library and golang.org/x ecosystem.

CLI

• Cobra — the command framework behind every cix subcommand.
• Charm — Bubble Tea, Bubbles, and Lip Gloss power the interactive cix config TUI.
• MCP Go SDK — the Model Context Protocol server that exposes cix to Claude Desktop & Cowork.
• notify — cross-platform filesystem watching for the index-on-change watcher.
• koanf — layered configuration (flags → env → ~/.cix/config.yaml).

Dashboard (web UI)

• React + Vite — the embedded dashboard served at /dashboard.
• Radix UI + Tailwind CSS — accessible component primitives and styling (the shadcn/ui pattern).
• TanStack Query — server-state and data fetching.
• openapi-typescript — generates the dashboard's API types from the OpenAPI spec.
• lucide and sonner — icons and toast notifications.

Full dependency lists with versions live in server/go.mod, cli/go.mod, and server/dashboard/package.json.

MIT