fsq-codebase

Zero-config codebase indexer with FSQ embeddings for fast semantic code search. Why Finite Scalar Quantization to compress? Because nobody has tried it before, that's why. Also FSQ still loosely maintains the shape of the vector and does not need a codebook, in case I ever wanted to round trip the embeddings back to code (for example for previewing purposes, like a jpg thumbnail).

Features

• Fast semantic search: 10x compression with int8 embeddings, 2.7x faster search
• Multi-language: Python, JavaScript, TypeScript, Go, Rust, Java, and more
• Zero-config: Just point at a directory and search
• MCP server: Claude Code integration via Model Context Protocol

Installation

Work in progress. For now you would need to build the model yourself. ANd

Quick Start

Python API

from fsq_codebase import CodebaseIndex, FSQEmbedder

# Index a codebase
index = CodebaseIndex.create("./my-project")
results = index.query("add rate limiting", top_k=10)
print(results.tree())

# Or use the embedder directly
embedder = FSQEmbedder.from_bundled("codet5plus-96d")
embeddings = embedder.encode(["def hello(): pass", "function greet() {}"])

MCP Server (Claude Code)

# Start the MCP server
fsq-codebase --index ./codebase.index

Configure in Claude Code's .mcp.json:

{
  "mcpServers": {
    "fsq-codebase": {
      "command": "fsq-codebase",
      "args": ["--index", "./codebase.index", "--verbose"]
    }
  }
}

Bundled Models

Model	Encoder	FSQ Dim	Size
codet5plus-96d	CodeT5+ 110M	96	268 KB
unixcoder-96d	UniXcoder	96	652 KB

The encoder (CodeT5+ or UniXcoder) downloads automatically from HuggingFace on first use (~440MB).

Performance

Compared to CodeT5+ baseline on CoIR benchmark:

Model	MRR	Storage	Search Speed
CodeT5+ baseline	0.9699	1024B	0.39ms
fsq-codebase	0.9706	96B	0.14ms

10.7x compression with 2.7x faster search while maintaining accuracy.

License

MIT