code-index

 ██████╗██╗██╗  ██╗
██╔════╝██║╚██╗██╔╝
██║     ██║ ╚███╔╝
██║     ██║ ██╔██╗
╚██████╗██║██╔╝ ██╗
 ╚═════╝╚═╝╚═╝  ╚═╝  CodeIndeX

cix — CodeIndeX. Search your codebase by meaning, not just text. A self-hosted semantic code-search platform — server with a web dashboard, CLI, agent skills, and multi-repo workspace search. Works with any agent or terminal. Website: codeindex.app

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:

---

Why

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.

---

What you get

• cix-server — Go HTTP API with embedded llama.cpp sidecar for embeddings, SQLite for symbols, metadata and vectors, FTS5 BM25 mirror for hybrid ranking. Vectors are read from disk per query rather than held in RAM, so an idle server sits at tens of megabytes regardless of index size (doc/VECTORSTORE.md). Ships as a single distroless container.
• Web dashboard at /dashboard — projects, search, users + API keys, runtime settings, resource + database maintenance, drift indicator. Embedded in the server binary. See doc/DASHBOARD.md.
• macOS menu bar app — cix.app, a drag-to-install launcher that runs and self-updates a local server on Apple Silicon. See doc/MACOS_APP.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.

---

Architecture

                  ┌────────────────────────────────────┐
                  │  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, 31 langs)   (wazero)       │
│  ├── embedding provider (local llama.cpp / Voyage / OpenAI)     │
│  ├── SQLite vector store (float32 BLOBs, streamed cosine scan)  │
│  └── 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/.

Why vectors live in SQLite. Through v0.12.x cix used chromem-go, an in-memory vector database. It decodes every document of every collection into the heap at startup and never evicts, so memory was proportional to the index rather than to the work: a real 312k-document index cost 2.2 GB resident while idle and 47 seconds before it could answer anything. v0.13.0 replaced it with a SQLite store that keeps embeddings as float32 BLOBs and scans them per query — the same index now idles at tens of megabytes and answers about a millisecond after boot. The trade is search latency, roughly 4× higher and far less sensitive to how many results you ask for. Existing indexes are imported automatically on first boot; nothing is re-embedded. Numbers, layout and the migration: doc/VECTORSTORE.md.

---

Quick Start

Mode	Best for	GPU	Prerequisites
macOS app	Apple Silicon Macs — the default on a Mac	Metal	macOS 13+, Apple Silicon
Docker (CPU)	any OS, dev / small repos	none	Docker
Docker (CUDA)	NVIDIA GPU servers	CUDA 12.x	Docker + NVIDIA Container Toolkit
Native from source (macOS)	hacking on cix itself	Metal	Go 1.25+, Node.js, Xcode CLT

1. Start the server

On a Mac, install the app. cix.app is a menu bar launcher: download cix-<version>-arm64.dmg from the releases page, drag it to Applications, and open it. It downloads the server, the CLI and a Metal-accelerated llama-server into ~/.cix/runtime/, creates your admin account and an API key, points the cix CLI at it, and keeps the server updated in place — so steps 2 and 3 below are already done and you can go straight to step 4. macOS blocks an ad-hoc-signed app twice on first launch; clearing that and everything else the app does is in doc/MACOS_APP.md.

Everywhere else, one command — the installer detects your platform, asks a few questions (deployment mode, admin email, password, port — every one has a sensible default), and brings the server up:

curl -fsSL https://raw.githubusercontent.com/dvcdsys/code-index/main/install-server.sh | bash

(Equivalent from a clone: git clone https://github.com/dvcdsys/code-index && cd code-index && ./install-server.sh.)

At the end it prints the dashboard URL and your admin login — and offers to install the cix CLI and connect it to the new server, so cix init works immediately (steps 2–3 below happen automatically on a fresh install). Re-running after a git pull upgrades in place; --uninstall removes the server but keeps your data. Building the macOS server from a checkout instead of installing the app: doc/SETUP_MACOS_NATIVE.md. For shared/team deployment, see doc/TEAM_DEPLOYMENT.md.

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 pull                               # `up -d` alone reuses any local image, however old
docker compose up -d                              # CPU
# docker compose -f docker-compose.cuda.yml pull && docker compose -f docker-compose.cuda.yml up -d # NVIDIA GPU
curl http://localhost:21847/health                # → {"status":"ok"}

[!IMPORTANT] On a fresh database the server refuses to start unless both CIX_BOOTSTRAP_ADMIN_EMAIL and CIX_BOOTSTRAP_ADMIN_PASSWORD are set. The admin is created with must_change_password=true — you change it on first login, then can drop the env vars.

2. Log in and mint an API key

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

Then go to API Keys → New key, name the key, and copy the revealed cix_… value — it is shown exactly once. The dialog also gives you a ready-to-paste cix config connect command for step 3.

3. Install + configure the CLI

curl -fsSL https://raw.githubusercontent.com/dvcdsys/code-index/main/install.sh | bash
# paste the connect command from the API-key dialog, or:
cix config set server.local.url http://localhost:21847
cix config set server.local.key cix_<key-from-step-2>
cix config set default_server local

(Legacy alternative: set CIX_API_KEY=cix_… in .env before first boot and the server imports it as an API key.)

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

4. Index a project and search

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.

---

Embedding providers

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).

Provider	Kind	Default model	Where code goes	API key
Local (default)	ollama	awhiteside/CodeRankEmbed-Q8_0-GGUF	Stays on your machine — bundled llama-server, fully offline. GPU via CUDA/Metal.	none
Voyage AI	voyage	voyage-code-3	Sent to api.voyageai.com. Code-specialized, retrieval-tuned, Matryoshka dims 256–2048, int8.	CIX_VOYAGE_API_KEY