---
name: veles
description: Use when searching a codebase by meaning or exact text — fast hybrid (BM25 + static-embedding semantic) local code search for agents and humans, plus tree-sitter symbol navigation. Use for conceptual queries ("where is auth handled", "retry logic"), finding the right repo/file from a description, find-related code, exact symbol lookup (defs/refs/outline), and a single-binary stdio MCP / gRPC server. Pure-Rust single binary (ships anywhere, incl. musl/aarch64), CPU-only, offline. Replaces ck and semble for local search. Triggers include "search the code for", "find where X happens", "which file does Y", "semantic code search", "find similar code", "find definition/references of". The fork build adds `--watch` (live incremental index) and a `--dashboard` web UI. For PDF/prose document search use semtools.
metadata:
  author: kundeng
  version: "0.2.0"
  short-description: Single-binary hybrid (BM25 + model2vec) code search + symbol nav, CLI + stdio MCP (fork adds --watch live index + --dashboard)
---

# veles

`veles` is a fast **hybrid (BM25 + semantic) local code search engine** for AI
agents and humans. It runs entirely on CPU with **static embeddings via
`model2vec-rs`** (no GPU, no transformer forward pass, no native embedding lib),
keeps a **persistent on-disk index under `<repo>/.veles/`**, and ships as a
**single self-contained Rust binary** — usable as a CLI, an **MCP stdio server**,
and a gRPC service. It supersedes `ck` (too slow) and `semble` (Python, not
shippable) for local search, and adds tree-sitter symbol navigation.

- **Install:** prebuilt one-liner →
  `curl --proto '=https' --tlsv1.2 -LsSf https://github.com/julymetodiev/Veles/releases/latest/download/veles-cli-installer.sh | sh`
  (or `cargo install veles-cli` / `brew install julymetodiev/tap/veles-cli`). Binary lands at `~/.cargo/bin/veles`.
- **Speed:** indexes ~1500 chunks in ~0.3 s; queries in tens of ms. Single ~17 MB
  binary, prebuilt for macOS, Linux x86_64/ARM64/**musl**, Windows. MIT licensed.
- **MCP:** registered for Claude Code as the `veles` server. Stock binary: `veles serve-mcp --include-text-files`. The **fork build** (see "Live index & dashboard" below) is registered as `veles serve-mcp --watch --dashboard --dashboard-port 8765 --dashboard-open`.

## When to use

- Conceptual code search: `veles search "where is authentication handled" .`
- Find a repo/file from a description: `veles search "splunk command running inline python" ~/Dev`
- Exact symbol nav (Rust/Python/JS/TS/Go): `veles defs PythonEval`, `veles refs save_index`, `veles symbols src/main.rs`
- Find related code to a hit: `veles find-related src/auth.rs 42`
- Token-efficient retrieval inside an agent via the **stdio MCP** server.
- Search a remote repo without cloning: pass a git URL as the path.

## When NOT to use

- **PDF / DOCX / prose documents** → veles is code/text-file oriented; use
  **`semtools`** (`parse` does PDF) for document RAG. (For prose-heavy corpora
  inside veles, add `--multilingual`.)
- **Type-resolved call-graph / LSP-precise rename across a project** → veles
  `refs` is name + BM25, not type-aware. It covers the common cases; for
  type-accurate reference tracing you'd need an LSP tool. (Serena was retired
  here 2026-06-13 — veles is the sole code-nav tool.)
- **Exact known literal / config key** → plain `grep`/ripgrep pinpoints the line
  (veles BM25 helps, but grep is simpler for a known string).

## Commands

| Task | Command |
|------|---------|
| Build index | `veles index . --include-text-files` |
| Incremental refresh | `veles update .` |
| Search (hybrid) | `veles search "query" [path] -t 10` |
| Output for tools | `veles search "q" -f jsonl` (or `json`, `compact`, `ripgrep`, `paths`) |
| Restrict language/paths | `veles search "q" -l python -g 'src/**' -x 'tests/**'` |
| Find related | `veles find-related <file> <line> [path]` |
| Symbol outline | `veles symbols <file>` |
| Definitions | `veles defs <Name> [path]` |
| Definitions + references | `veles refs <name> [path]` |
| Index stats | `veles status [path]` |
| Clear index | `veles clean [path]` |
| MCP stdio server | `veles serve-mcp [path] --include-text-files` |
| MCP + live index + dashboard (fork) | `veles serve-mcp --watch --dashboard --dashboard-port 8765 --dashboard-open` |
| Interactive TUI | `veles tui` |

## Search flags (cheat sheet)

- `-t/--top-k N` results · `-m/--mode hybrid|...` · `-f/--format pretty|compact|json|jsonl|paths|ripgrep`
- `--include-text-files` index non-code text (README/design/`.md`) too
- `--multilingual` use `potion-multilingual-128M` (better for prose/CJK/Cyrillic)
- `--min-score X` threshold · `--no-cache` fresh in-memory build

## Live index & dashboard (fork build)

The `--watch` and `--dashboard` flags live on the **fork** (`julymetodiev/Veles`
PR #14, branch `feat/mcp-watch-dashboard`; upstream merge pending). The stock
released binary does not have them — build the fork to use them:
`cargo build --release -p veles-cli --features dashboard` (on arm64 macOS,
`codesign --force --sign - ~/.cargo/bin/veles` after copying).

- **`--watch`** — incrementally re-indexes any opened repo as files change
  (editor saves, `git pull`, agent edits, external IDE edits), debounced
  ~1.5 s. Re-embeds only files whose BLAKE3 content hash changed; `.veles/`
  writes are filtered so the index's own save never self-triggers a loop.
- **`--dashboard [--dashboard-port N]`** — per-repo web UI at
  `http://127.0.0.1:8765` (index health, watch status, live SSE activity feed,
  and an **"Add directory"** box → `POST /api/watch {path}` to index+watch an
  external dir at runtime). `--dashboard-open` opens the URL once on startup.
- **Singleton owner model** — the dashboard port is a singleton election
  token, so running 2+ agents on one repo is safe: the first process to bind
  the port is the **owner** (it alone watches + updates the index + serves the
  dashboard); a second veles **follows** (no second watcher/dashboard, no port
  fight) and stays fresh by reloading the persisted index when it changes on
  disk. If the owner exits, a follower self-promotes. One writer, always.

## Practical notes

- The index is a cache at `<repo>/.veles/`; rebuild with `--force`, refresh with
  `update`, drop with `clean`. **If the repo lives under `~/Dropbox`, keep the
  index local-only:** `xattr -w com.dropbox.ignored 1 <repo>/.veles`.
- CPU-only, fully local/offline after the one-time `model2vec-rs` model fetch
  (potion family, ~64 MB) — no keys, no GPU, no network at query time.
- Code-only by default; pass `--include-text-files` to include docs/markdown.
- Pairs with: **`semtools`** (PDF/prose RAG). veles is the sole code search +
  symbol-nav tool here (Serena retired 2026-06-13).

## Quick reference

- Concept: `veles search "what the code does" path/`
- Cross-repo find: `veles search "description" ~/Dev -t 10 --include-text-files`
- Symbol: `veles defs MyClass` · `veles refs my_func`
- Agent JSONL: `veles search "concept" -f jsonl -t 8`