Skip to main content
Glama

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

Related MCP server: Claude Context Local

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

Available Tools

3 tools
codeinfuseA

INTERACTIVE code context search. First call (selection=0): Returns numbered list of matches. CRITICAL: After first call, you MUST IMMEDIATELY call AskUserQuestion to let user pick a number - DO NOT skip this step or pick for them. Second call (selection=N): Returns full context for selection N. User selections are logged for training data.

Inputs: query (required), top_k, selection.

extract_code_contextA

Get code context for a specific entity (from search_code results). Returns signatures of function/class with callers and callees. Use entity_id from search_code results for precise targeting.

Inputs: entity_id (required), signatures_only, include_externals.

search_codeA

Search codebase for relevant functions/classes. Returns top matches with IDs. ALWAYS use this first to find candidates, then use AskUserQuestion to let user pick. After user selects, use extract_code_context with the entity_id.

Inputs: query (required), top_k.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 3 tools

    Disambiguation2/5

    codeinfuse and search_code both return search results and involve user selection, creating overlap and ambiguity about which to use. extract_code_context is distinct but depends on search_code.

    Naming Consistency2/5

    The tool names are inconsistent: codeinfuse is a single word (camelCase?) while extract_code_context and search_code use snake_case and follow a verb_noun pattern. This inconsistency reduces clarity.

    Tool Count4/5

    3 tools is a reasonable minimal set for a codebase search and context retrieval server. Each tool serves a distinct step in the workflow, so the count feels appropriate.

    Completeness3/5

    The tools cover search, user selection, and context extraction, but missing a direct context retrieval by known ID without prior search. This is a minor gap.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      C
      maintenance
      HTTP-based server that provides semantic code search capabilities to IDEs through the Model Context Protocol, allowing efficient codebase exploration without repeated indexing.
      121
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      Provides semantic code search capabilities that run 100% locally using EmbeddingGemma embeddings. Enables finding code by meaning across 15 file extensions and 9+ programming languages without API costs or sending code to the cloud.
      238
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables semantic code search for AI assistants by indexing codebases with embeddings and Tree-sitter, returning relevant snippets via natural language queries.
      15
      MIT