BeaconBay/ck

📦 ck – Semantic Code Search

ck (pronounced “seek”) is a Rust‑based command‑line tool that lets you search source code by meaning instead of just literal text. It builds local embeddings of your code, caches them incrementally, and then answers queries like “error handling” or “authentication logic” with the relevant functions, classes, or code blocks—even when those exact words don’t appear.

---

🎯 What it does

Feature	What you get
Semantic search	Finds code concepts via vector embeddings (BGE‑Small, Mixedbread, Nomic, Jina‑Code, etc.).
Hybrid search	Combines semantic relevance with traditional regex/keyword matching using Reciprocal Rank Fusion.
Grep‑compatible CLI	Same flags you know from grep/ripgrep (-n, -R, -l, etc.).
Interactive TUI	Full‑screen terminal UI with live results, preview modes, multi‑select, and editor integration.
AI‑agent (MCP) server	Exposes tools (semantic_search, regex_search, …) over the Model Context Protocol so Claude Desktop, Cursor, or other agents can call ck programmatically.
Incremental, chunk‑level indexing	Only changed chunks are re‑embedded; cache hit rates of 80‑90 % on typical edits.
Smart file filtering	Respects .gitignore, a dedicated .ckignore, and command‑line exclude flags.
Structured output	--json (single array) or --jsonl (line‑delimited) for scripts and LLM pipelines.
Multi‑language support	Python, JavaScript/TypeScript, Rust, Go, C/C++, C#, Ruby, Haskell, Dart, Markdown, plus generic text formats.
Offline‑only	All embedding models run locally; no network traffic after the initial model download.

---

⚙️ How it works (high‑level)

1. Indexing – ck --index <root> walks the source tree, splits files into language‑aware chunks (functions, classes, etc.) using Tree‑sitter, and computes embeddings via FastEmbed. Index data lives in a .ck/ directory (or a custom location via CK_INDEX_DIR).
2. Search – A query is embedded with the same model; similarity scores are computed against the stored vectors. For hybrid mode, a traditional regex search runs in parallel and the two result lists are merged.
3. Serving – ck --serve starts an MCP server exposing the search tools as JSON‑RPC endpoints, enabling AI assistants to call them directly.

---

🚀 Quick start (CLI)

# Install the binary from crates.io
cargo install ck-search

# Semantic search (index is built automatically on first run)
ck --sem "error handling" src/

# Hybrid search (semantic + keyword)
ck --hybrid "connection timeout" src/

# Traditional grep‑style search
ck -R "TODO|FIXME" .

# Interactive terminal UI
ck --tui "authentication logic"

---

🤖 AI‑agent integration (MCP)

# Start the server
ck --serve

The server registers tools such as semantic_search that agents can call:

{
  "tool": "semantic_search",
  "args": {"query": "authentication logic", "path": "/my/project", "top_k": 25}
}

Responses are streamed as JSONL, making them easy to consume in LLM‑driven workflows.

---

📚 Typical use cases

• Developer productivity – Jump to the implementation of a concept without remembering exact identifiers.
• Code review preparation – List all functions that implement a security‑critical pattern.
• CI/CD automation – Scan a repo for insecure patterns (ck --json --sem "password|secret" . | my_scanner).
• Team onboarding – Quickly locate related test files or duplicated logic.
• LLM‑augmented tooling – Feed structured search results to Claude, Cursor, or custom agents.

---

📦 Installation

Method	Command
Crates.io (recommended)	cargo install ck-search
From source	git clone https://github.com/BeaconBay/ck && cd ck && cargo install --path ck-cli
Future package managers	Brew / apt packages are planned but not yet released.

---

📄 License

Dual‑licensed under MIT and Apache‑2.0 (see LICENSE-MIT / LICENSE-APACHE).

---

🙏 Where to learn more

• Full docs: https://beaconbay.github.io/ck/
• TUI guide: TUI.md in the repo
• Model selection & indexing details are in the README tables.

---

ck is a genuine, actively maintained open‑source project that brings modern AI‑powered semantic search to the familiar world of command‑line code grepping. It stays offline, respects your .gitignore, and integrates cleanly with both human workflows and AI agents.