GitHub - dvcdsys/code-index: Self-hosted semantic code search platform — Go server with web dashboard, CLI, and AI-agent skills. Search code by meaning, not text: hybrid BM25 + dense embeddings via llama.cpp.

 ██████╗██╗██╗  ██╗
██╔════╝██║╚██╗██╔╝
██║     ██║ ╚███╔╝
██║     ██║ ██╔██╗
╚██████╗██║██╔╝ ██╗
 ╚═════╝╚═╝╚═╝  ╚═╝  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.

Manual Docker setup (what the installer automates)

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`
OpenAI / compatible	`openai`	`text-embedding-3-small`	Sent to the configured `base_url` (OpenAI or any compatible endpoint).	`CIX_OPENAI_API_KEY`

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.

Agent Integration

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:

# Run in a terminal — NOT inside a Claude Code session.
claude plugin marketplace add dvcdsys/code-index
claude plugin install cix@code-index
# Activates automatically on the next `claude` start — no reload needed.

# Update later (marketplace first, then the plugin):
claude plugin marketplace update code-index
claude plugin update cix@code-index

(The /plugin … slash commands work inside an interactive session too, but the terminal form is the dependable path.)

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

Configuration

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

Variable	Default	Purpose
`CIX_API_KEY`	—	Bearer token for CLI/agents. Required.
`CIX_BOOTSTRAP_ADMIN_EMAIL` / `_PASSWORD`	—	Required on a fresh DB; seeds the first admin.
`CIX_PORT`	`21847`	Listen port.
`CIX_EMBEDDING_MODEL`	`awhiteside/CodeRankEmbed-Q8_0-GGUF`	Local GGUF repo or absolute path.
`CIX_N_GPU_LAYERS`	`-1` macOS / `0` else / `99` Docker CUDA	`99` = full offload, `0` = CPU.
`CIX_EMBEDDINGS_ENABLED`	`true`	`false` boots without the llama sidecar.
`CIX_VECTORS_DIR`	sibling of the chroma dir, i.e. `<data>/vectors`	Where the vector databases live. Must be on a persistent volume — this is your index.
`CIX_SECRET_KEY` / `_KEYFILE`	auto-generated keyfile	AES-256-GCM key for `github_tokens` encryption. Back this up.
`CIX_PUBLIC_URL`	—	Public origin for webhook URLs. Trumped by a live Managed Tunnel.

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.

Deploying & operating

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:

Tag	Architecture	Use case
`dvcdsys/code-index:latest`	linux/amd64 + linux/arm64	CPU
`dvcdsys/code-index:cu128`	linux/amd64	NVIDIA GPU (CUDA 12.8)
`dvcdsys/code-index:<version>` / `<version>-cu128`	—	Version-pinned variants

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

Documentation map

Doc	Purpose
`doc/CLI_REFERENCE.md`	Full CLI command surface + per-project config (`.cixignore`, `.cixconfig.yaml`)
`doc/CLI_CONFIG.md`	Everything the CLI lets you configure (servers, defaults, output)
`doc/DASHBOARD.md`	Dashboard pages, authentication, authorization model, drift indicator
`doc/MACOS_APP.md`	The macOS menu bar app — install, first run, updates, uninstall
`doc/TEAM_DEPLOYMENT.md`	Self-hosting cix for a team — production / shared-infrastructure deployment for DevOps
`doc/TROUBLESHOOTING.md`	Common issues + search-quality tuning (`--min-score`)
`workspaces.md`	User-facing workspace guide (when to use, agent trust rules, query patterns)
`doc/WORKSPACES.md`	Operator setup (encryption keys, Cloudflare tunnel, workers, REST API)
`doc/SEARCH_ALGORITHM.md`	How per-project + hybrid workspace search rank results
`doc/VECTORSTORE.md`	The SQLite vector store — layout, tuning, migration from chromem-go
`doc/DATABASE_MAINTENANCE.md`	Reclaim, compaction, scheduled maintenance
`doc/WEBHOOKS.md`	GitHub webhook lifecycle, modes, HMAC validation
`doc/POLLING.md`	Git polling sync, for repos where a webhook is not an option
`doc/COWORK_MCP.md`	Using cix from Claude Desktop / Cowork over MCP (`cix mcp install`, multi-server)
`doc/UPDATES.md`	Release-poll banner + stable vs develop install channels
`doc/CONFIG_REFERENCE.md`	Complete env-var reference
`doc/RELEASES.md`	Cutting CLI + server + app releases, CVE scans, make targets
`doc/DEPRECATION_POLICY.md`	How long a removed feature is announced before it goes
`doc/SETUP_MACOS_NATIVE.md`	Building the macOS server from a checkout (the app is the normal path)
`mac/README.md`	How the macOS app and its runtime are built and signed
`doc/SECURITY_DEPLOYMENT.md`	Production hardening
`doc/DOCKER_TAGS.md`	Docker Hub tag lifecycle
`doc/LANGUAGES.md`	Supported chunker languages
`doc/MIGRATION_FROM_PYTHON.md`	Python → Go server migration notes
`doc/benchmarks.md`	Index of dated benchmark snapshots
`doc/openapi.yaml`	REST API source of truth
`CONTRIBUTING.md`	Contributor workflow
`plugins/cix/README.md`	Claude Code plugin reference
`plugins/cix-cowork/README.md`	Cowork skills plugin (MCP-based) reference

Acknowledgements

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 31 languages, run via wazero (pure-Go WASM runtime).
modernc.org/sqlite — cgo-free SQLite for project metadata, symbols, the FTS5/BM25 mirror, and (since v0.13.0) the vectors themselves.
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.
gronx — the crontab expressions behind scheduled database maintenance.
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), with validator checking what lands there.
go-gitignore — .cixignore and .gitignore matching, so the watcher and the indexer agree with git about what is source.

Dashboard (web UI)

React + Vite — the embedded dashboard served at /dashboard, routed by React Router.
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.
sonner — toast notifications.

No longer in the stack, still owed thanks

chromem-go — the embedded vector store cix shipped through v0.12.x, and the model its collection semantics still follow. It is why the early versions worked at all; it is kept as a dependency only to read a pre-0.13 index during the one-time import.
gotreesitter — the Go tree-sitter binding cix's AST chunking first grew from, before the move to WASM grammars on wazero. Thank you for the head start.

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

License

MIT

Navigation Menu

Repository files navigation

Why

What you get

Architecture

Quick Start

1. Start the server

2. Log in and mint an API key

3. Install + configure the CLI

4. Index a project and search

Embedding providers

Agent Integration

Configuration

Deploying & operating

Documentation map

Acknowledgements

License

About

Releases

Packages

Used by

Contributors

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 617 Commits
.claude-plugin		.claude-plugin
.github		.github
cli		cli
doc		doc
mac		mac
plugins		plugins
poc/wasm-treesitter		poc/wasm-treesitter
server		server
site		site
skills		skills
.cixignore		.cixignore
.env.example		.env.example
.gitignore		.gitignore
CITATION.cff		CITATION.cff
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
Makefile		Makefile
ONBOARDING.md		ONBOARDING.md
README.md		README.md
SECURITY.md		SECURITY.md
docker-compose.cuda.yml		docker-compose.cuda.yml
docker-compose.yml		docker-compose.yml
install-develop.sh		install-develop.sh
install-server.sh		install-server.sh
install.sh		install.sh
portainer-stack-cuda.yml		portainer-stack-cuda.yml
portainer-stack.yml		portainer-stack.yml
workspaces.md		workspaces.md

Folders and files

Latest commit

History

Repository files navigation

Why

What you get

Architecture

Quick Start

1. Start the server

2. Log in and mint an API key

3. Install + configure the CLI

4. Index a project and search

Embedding providers

Agent Integration

Configuration

Deploying & operating

Documentation map

Acknowledgements

License

About

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages