Skip to main content
Glama
codebaxing

codebaxing

by duysolo

Codebaxing

npm version License: MIT

English | Tiếng Việt

MCP server for semantic code search. Index your codebase once, then search using natural language.

How It Works

Your Code → Tree-sitter Parser → Symbols → Embedding Model → Vectors → ChromaDB
                                                                           ↓
"find auth logic" → Embedding → Query Vector → Similarity Search → Results

Traditional search matches exact text. Codebaxing understands meaning:

Query

Finds (even without exact match)

"authentication"

login(), validateCredentials(), authMiddleware()

"database connection"

connectDB(), prismaClient, repository.query()

Related MCP server: code-context-mcp

Quick Start

1. Start ChromaDB

docker run -d -p 8000:8000 --name chromadb chromadb/chroma

2. Index Your Codebase (CLI)

npx codebaxing@latest index /path/to/your/project

This creates a .codebaxing/ folder with the index. Only needs to be done once per project.

Performance note: Local embedding is slow (~4 min for ~4,000 files). For faster indexing, use Gemini embedding (free) — see Cloud Embedding below.

3. Install MCP Server for AI Editors

npx codebaxing install              # Claude Desktop
npx codebaxing install --cursor     # Cursor
npx codebaxing install --windsurf   # Windsurf
npx codebaxing install --all        # All editors

Restart your editor. Now you can ask: "Find the authentication logic"

CLI Commands

Command

Description

npx codebaxing@latest index <path>

Index a codebase (required first)

npx codebaxing search <query>

Search indexed code

npx codebaxing stats [path]

Show index statistics

npx codebaxing clean [path]

Remove index (reset)

npx codebaxing install [--editor]

Install MCP server

npx codebaxing uninstall [--editor]

Uninstall MCP server

Tip: Use @latest for index to ensure you have the newest version.

Search Options

npx codebaxing search "auth middleware" --path ./src --limit 10
  • --path, -p - Codebase path (default: current directory)

  • --limit, -n - Number of results (default: 5)

MCP Tools (for AI Agents)

After installing, AI agents can use these tools:

Tool

Description

search

Semantic code search

stats

Index statistics

languages

Supported file extensions

remember

Store project memory

recall

Retrieve memories

forget

Delete memories

Note: The index tool is disabled for AI agents. Use CLI: npx codebaxing@latest index <path>

Configuration

Cloud Embedding (Fastest)

Local embedding runs on CPU and can be slow for large codebases (~4 min for ~4,000 files). Cloud embedding is ~25x faster and recommended for any project with 1,000+ files.

# Gemini (FREE - recommended, 1500 RPM free tier)
CODEBAXING_EMBEDDING_PROVIDER=gemini GEMINI_API_KEY=... npx codebaxing@latest index /path

# OpenAI (text-embedding-3-small, 384 dims)
CODEBAXING_EMBEDDING_PROVIDER=openai OPENAI_API_KEY=sk-... npx codebaxing@latest index /path

# Voyage (voyage-code-3, 1024 dims, code-optimized)
CODEBAXING_EMBEDDING_PROVIDER=voyage VOYAGE_API_KEY=va-... npx codebaxing@latest index /path

Provider

Model

Speed

Cost

Gemini

text-embedding-004 (768 dims)

~10,000 texts/sec

Free (1500 RPM)

OpenAI

text-embedding-3-small (384 dims)

~10,000 texts/sec

~$0.02 / 1M tokens

Voyage

voyage-code-3 (1024 dims)

~10,000 texts/sec

~$0.06 / 1M tokens

Local

all-MiniLM-L6-v2 (384 dims)

~200 texts/sec

Free (CPU)

Note: Switching between providers requires full re-index (npx codebaxing@latest index <path>) due to dimension differences.

Environment Variables

Variable

Description

Default

CHROMADB_URL

ChromaDB server URL

http://localhost:8000

CODEBAXING_EMBEDDING_PROVIDER

Embedding backend: local, gemini, openai, voyage

local

CODEBAXING_DEVICE

Compute device (local only): cpu, cuda

cpu

CODEBAXING_DTYPE

Model quantization (local only): fp32, fp16, q8, q4

q8

CODEBAXING_WORKERS

Worker threads for parallel embedding (local only, 0=off)

2

CODEBAXING_MAX_FILE_SIZE

Max file size in MB

1

CODEBAXING_MAX_CHUNKS

Max chunks to index

500000

CODEBAXING_FILES_PER_BATCH

Files per batch (lower = less RAM)

100

CODEBAXING_PARALLEL_BATCHES

Concurrent batches

3

CODEBAXING_METADATA_SAVE_INTERVAL

Save progress every N batches

10

CODEBAXING_MODEL_CACHE

Model cache directory (local only)

~/.cache/codebaxing/models

CODEBAXING_OPENAI_API_KEY

OpenAI API key (or use OPENAI_API_KEY)

-

CODEBAXING_VOYAGE_API_KEY

Voyage API key (or use VOYAGE_API_KEY)

-

CODEBAXING_GEMINI_API_KEY

Gemini API key (or use GEMINI_API_KEY)

-

CODEBAXING_EMBEDDING_MODEL

Override embedding model name

per-provider default

CODEBAXING_EMBEDDING_DIMENSIONS

Override embedding dimensions

per-provider default

CODEBAXING_EMBEDDING_BASE_URL

Custom API endpoint for cloud providers

provider default

Manual Editor Config

~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "codebaxing": {
      "command": "npx",
      "args": ["-y", "codebaxing"],
      "env": { "CHROMADB_URL": "http://localhost:8000" }
    }
  }
}

~/.cursor/mcp.json

{
  "mcpServers": {
    "codebaxing": {
      "command": "npx",
      "args": ["-y", "codebaxing"],
      "env": { "CHROMADB_URL": "http://localhost:8000" }
    }
  }
}

Windsurf: ~/.codeium/windsurf/mcp_config.json Zed: ~/.config/zed/settings.json (use context_servers key) VS Code + Continue: ~/.continue/config.json

Supported Languages

Python, JavaScript, TypeScript, Go, Rust, Java, C/C++, C#, Ruby, PHP, Kotlin, Swift, Scala, Lua, Dart, Elixir, Haskell, OCaml, Zig, Perl, Bash, HTML, CSS, Vue, JSON, YAML, TOML, Makefile

Requirements

  • Node.js >= 20.0.0

  • Docker (for ChromaDB)

  • ~500MB disk space (embedding model)

Technical Details

Component

Technology

Local Embedding

all-MiniLM-L6-v2 (384 dims, ONNX, q8 quantized)

Cloud Embedding

Gemini text-embedding-004 (free), OpenAI, or Voyage

Model Cache

~/.cache/codebaxing/models/ (local only, downloaded once)

Vector Database

ChromaDB

Code Parser

Tree-sitter (28 languages)

MCP SDK

@modelcontextprotocol/sdk

Local mode: The embedding model is downloaded from HuggingFace on first run and cached at ~/.cache/codebaxing/models/. Uses q8 quantization (~3x faster than fp32). No network access after initial download.

Cloud mode: Sends code chunks to OpenAI/Voyage API for embedding. ~25x faster than local CPU. Requires API key.

License

MIT

Available Tools

9 tools
cleanA
DestructiveIdempotent

Clean all indexed data for a codebase. Deletes ChromaDB collection and .codebaxing/ data. Preserves user config (ignore.json). Use this to fix corrupted indexes or start fresh.

Inputs: path (required).

forgetA
DestructiveIdempotent

DESTRUCTIVE: Remove memories matching specified criteria.

Delete by: memory_id, memory_type, tags, older_than (1d, 7d, 30d, 1y)

Inputs: path, tags, memory_id, older_than, +1 more.

indexA
Idempotent

Index a codebase for semantic search. REQUIRED FIRST STEP.

Modes:

  • auto (default): Smart detection. If index exists, updates incrementally.

  • full: Force complete re-index.

  • load-only: Just load existing index without any indexing.

Creates a .codebaxing/ folder in the codebase directory.

Inputs: path (required), mode, embedding_model, file_extensions.

languagesA
Read-onlyIdempotent

List all supported programming languages and file extensions.

Inputs: no named parameters.

memory-statsA
Read-onlyIdempotent

Get statistics about stored memories for the current project.

Inputs: path.

recallA
Read-onlyIdempotent

Retrieve memories using semantic search.

Filters: memory_type, tags, time_range (today, week, month, all)

Inputs: query (required), path, tags, n_results, +2 more.

rememberB

Store a memory for later retrieval.

Memory types: conversation, status, decision, preference, doc, note TTL options: session (24h), day, week, month, permanent (default)

Inputs: content (required), memory_type (required), ttl, path, +1 more.

statsB
Read-onlyIdempotent

Get statistics about the currently loaded codebase index.

Inputs: path.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 9 tools

    Disambiguation5/5

    Each tool has a distinct purpose: index, search, stats, languages, memory-stats, clean, remember, recall, forget. No overlapping or ambiguous tools; even stats and memory-stats are clearly scoped to different domains.

    Naming Consistency5/5

    All tool names are single-word lowercase verbs or nouns that clearly indicate their action (e.g., index, search, remember, forget). This is consistent and predictable, though not verb_noun, the pattern is uniform and intuitive.

    Tool Count5/5

    With 9 tools, the server is well-scoped, covering indexing, searching, memory management, and cleanup. Each tool is necessary for the core workflows, and the count is within the ideal range (3-15).

    Completeness4/5

    The toolset covers the full lifecycle: index creation/update, search, stats, memory CRUD (create, read, delete), and cleanup. A minor gap is the lack of a tool to list all memories or update a specific memory, but the core functionality is well covered.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers