semantic-code-agents-rs

Semantic code search engine powered by embeddings and vector databases. Find code by meaning, not just keywords.

Primary command: sca (alias: semantic-code).

Why This?

Traditional code search (grep, ripgrep) finds exact matches. Semantic search understands meaning:

• Ask questions: "How is authentication handled?" → finds auth code
• Explore unfamiliar codebases: "database connection setup" → finds DB init
• Find patterns: "error handling and recovery" → finds Result/error flows

Features

• Embedding providers: ONNX (local), OpenAI, Gemini, Voyage, Ollama, Apple Neural Engine (feature-gated)
• Local vector kernels: HNSW by default, experimental DFRR, and exact flat-scan ground truth
• Snapshot v2 + quantization: mmap-backed local bundles, subset/tile tooling, and storage preflight
• AST-aware splitting: Tree-sitter parsing with line-based fallback
• Change-aware reindex: Snapshot-driven change detection with WAL-backed local durability
• CLI-first: Deterministic output for automation and AI agents, including estimate-storage, calibrate, snapshot-subset, search --stdin-batch, and structured tracing

Quick Start

1. Install

Choose one install method:

• brew install luiz-frias/tap/semantic-code
• curl -fsSL https://github.com/Luiz-Frias/semantic-code-agents-rs/releases/latest/download/install.sh | sh
• winget install --id Luiz-Frias.SemanticCode -e (Windows)
• scoop bucket add semantic-code https://github.com/Luiz-Frias/semantic-code-agents-rs && scoop install semantic-code (Windows)
• mise use -g github:Luiz-Frias/semantic-code-agents-rs@latest
• cargo install semantic-code-cli --locked

This installs the sca and semantic-code commands.

For the full install matrix, see docs/release.md.

2. Initialize

From the root of your codebase:

sca init

This creates .context/manifest.json and a default .context/config.toml.

3. Index

Optional preflight:

sca estimate-storage

Then index:

sca index --init

4. Search

sca search --query "error handling and recovery"

Agent-friendly CLI

Use --agent for NDJSON output, no prompts, and quiet stderr:

sca --agent search --query "error handling"

Documentation

Full documentation is available in docs/:

• Getting Started
• Release & Install
• Architecture
• Configuration
• CLI Reference
• Troubleshooting
• FAQ

Development

Prerequisites

• Rust 1.96+
• mise (optional)
• just

Setup

git clone https://github.com/Luiz-Frias/semantic-code-agents-rs.git
cd semantic-code-agents-rs
mise install
just setup

Common Commands

Command	Description
just pc	Pre-commit checks (staged files)
just pc-full	Full pre-commit gate
just test-unit	Fast unit tests
just test-all	Full test suite
cargo run --bin sca -- --help	Run the CLI

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT license (LICENSE)

at your option.