Codebaxing

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()

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

<details> <summary>Claude Desktop</summary>

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

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

</details>

<details> <summary>Cursor</summary>

~/.cursor/mcp.json

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

</details>

<details> <summary>Other Editors</summary>

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

</details>

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