com.knitli/codeweaver

Official

by knitli · Python

Semantic code search built for AI agents. Hybrid, AST-aware, context for 166 languages.

Semantic code search for AI agents with AST-awareness across 166 languages.

Topics

mcpmcp-servervector-searchhybrid-searchllm-agentcodegensearchdiscovery-engineaiai-agentsautomationdeveloper-toolsdevtoolspythonknitlicodeweaveropen-sourceqdrantopenaianthropic-claude

README.md9 KBView on GitHub

WARNING

CodeWeaver is no longer maintained

We're really proud of CodeWeaver and think it's pretty awesome, but we can't maintain it anymore.

We're focused on something else.

CodeWeaver is (was?) a sophisticated, smart, code search tool with wide provider support. and it's still licensed under your choice of MIT or Apache-2.0.

So please, fork it and build something great!

CodeWeaver

Exquisite Context for Agents — Infrastructure that is Extensible, Predictable, and Resilient.

Documentation • Installation • Features • Comparison

</div>

What It Does

CodeWeaver gives Claude and other AI agents precise context from your codebase. Not keyword grep. Not whole-file dumps. Actual structural understanding through hybrid semantic search.

CodeWeaver is Professional Context Infrastructure. With 100% Dependency Injection (DI) and a Pydantic-driven configuration system, it provides the reliability and extensibility required for industrial-grade AI deployments.

Example:

code

Without CodeWeaver:
  Claude: "Let me search for 'auth'... here are 50 files mentioning authentication"
  Result: Generic code, wrong context, wasted tokens

With CodeWeaver:
  You: "Where do we validate OAuth tokens?"
  Claude gets: The exact 3 functions across 2 files, with surrounding context
  Result: Precise answers, focused context, 60-80% token reduction

CodeWeaver is no longer in alpha!

Early Release (0.x): CodeWeaver is in active development. APIs may change between minor versions. It's very well-tested but still in 'it works on my machine' territory. Use it, break it, help shape it.

How CodeWeaver Stacks Up

Quick Reference Matrix

Feature	CodeWeaver	Legacy Search Tools
Search Type	Hybrid (Semantic + AST + Keyword)	Keyword Only
Context Quality	Exquisite / High-Precision	Noisy / Irrelevant
Extensibility	DI-Driven (Zero-Code Provider Swap)	Hardcoded
Reliability	Resilient (Automatic Local Fallback)	Fails on API Timeout
Token Usage	Optimized (60–80% Reduction)	Wasted on Noise

🚀 Getting Started

Quick Install

Using the CLI with uv:

bash

# Add CodeWeaver to your project
uv add code-weaver

# Initialize with a profile (recommended uses Voyage AI)
cw init --profile recommended

# Verify setup
cw doctor

# Start the background daemon
cw start

📝 Note: cw init supports different Profiles:

recommended: High-precision search (Voyage AI + Qdrant)

quickstart: 100% local, private, and free (FastEmbed + Local Qdrant)

Want full offline? See the Local-Only Guide.

🐳 Prefer Docker? See Docker setup guide →

✨ Features

🔍 Exquisite Context

Hybrid search (sparse + dense vectors)
AST-level understanding (27 languages)
Reciprocal Rank Fusion (RRF)
Language-aware chunking (166+ languages)

</td> <td width="50%">

🛡️ Industrial Resilience

Automatic local fallback (FastEmbed)
Circuit breaker pattern for APIs
Works airgapped (no cloud required)
Pydantic-driven validation at boot-time

</td> </tr> <tr> <td>

🧩 Universal Extensibility

100% DI-driven architecture
17+ integrated providers
Custom provider API
Zero-code provider swapping

</td> <td>

🛠️ Developer Experience

Live indexing with file watching
Diagnostic tool (cw doctor)
Multiple CLI aliases (cw / codeweaver)
Selectable profiles for easy setup

</td> </tr> </table>

💭 Philosophy: Context is Oxygen

AI agents face too much irrelevant context, causing token waste, missed patterns, and hallucinations. CodeWeaver addresses this with one focused capability: structural + semantic code understanding that you control.

Curation over Collection: Give agents exactly what they need, nothing more.
Privacy-First: Your code stays local if you want it to.
Infrastructure over Tooling: Built to be the reliable foundation for your AI stack.

📖 Read the detailed rationale →

Official Documentation: docs.knitli.com/codeweaver/

Built with ❤️ by Knitli

⬆ Back to top

</div>

Install

Configuration

Environment variables

CODEWEAVER_CONFIG_FILE

Specify a custom config file path for CodeWeaver. Only needed if not using the default locations.

CODEWEAVER_DEBUGdefault false

Enable debug mode for CodeWeaver.

CODEWEAVER_EMBEDDING_API_KEYsecret

Specify the API key for the embedding provider, if required. Note: {', '.join([p for p in _providers_for_kind('embedding') if p.])}

CODEWEAVER_EMBEDDING_MODELdefault voyage-code-3

Specify the embedding model to use.

CODEWEAVER_EMBEDDING_PROVIDERdefault voyage

Specify the embedding provider to use.

CODEWEAVER_HOSTdefault localhost

Set the server host for CodeWeaver.

CODEWEAVER_LOG_LEVELdefault WARNING

Set the log level for CodeWeaver (e.g., DEBUG, INFO, WARNING, ERROR).

CODEWEAVER_MCP_PORTdefault 9328

Set the MCP server port for CodeWeaver if using http transport for mcp. Not required if using the default port (9328), or stdio transport.

CODEWEAVER_PORTdefault 9329

Set the port for the codeweaver management server (information and management endpoints).

CODEWEAVER_PROFILE

Use a premade provider settings profile for CodeWeaver.

CODEWEAVER_PROJECT_NAME

Set the project name for CodeWeaver.

CODEWEAVER_PROJECT_PATH

Set the project path for CodeWeaver.

CODEWEAVER_RERANKING_API_KEYsecret

Specify the API key for the reranking provider, if required.

CODEWEAVER_RERANKING_MODELdefault rerank-2.5

Specify the reranking model to use.

CODEWEAVER_RERANKING_PROVIDERdefault voyage

Specify the reranking provider to use.

CODEWEAVER_SPARSE_EMBEDDING_MODELdefault prithivida/Splade_pp_en_v1

Specify the sparse embedding model to use.

CODEWEAVER_SPARSE_EMBEDDING_PROVIDERdefault fastembed

Specify the sparse embedding provider to use.

CODEWEAVER_VECTOR_STORE_API_KEYsecret

Specify the API key for the vector store, if required.

CODEWEAVER_VECTOR_STORE_PORTdefault 6333

Specify the port for the vector store.

CODEWEAVER_VECTOR_STORE_PROVIDERdefault qdrant

Specify the vector store provider to use.

CODEWEAVER_VECTOR_STORE_URLdefault http://localhost

Specify the URL for the vector store.

CODEWEAVER__TELEMETRY__DISABLE_TELEMETRYdefault false

Disable telemetry data collection.

CODEWEAVER__TELEMETRY__TOOLS_OVER_PRIVACYdefault false

Opt-in to potentially identifying collection of query and search result data. This is invaluable for helping us improve CodeWeaver's search capabilities. If privacy is a higher priority, do not enable this setting.

HTTPS_PROXY

HTTP proxy for requests (Used by: Azure, Azure, Voyage)

OPENAI_API_KEYsecret

API key for OpenAI-compatible services (not necessarily an API key *for* OpenAI). The OpenAI client also requires an API key, even if you don't actually need one for your provider (like local Ollama). So provide a dummy key if needed. (Used by: Azure, Cerebras, Deepseek, Fireworks, Github, Groq, Heroku, Moonshot, Ollama, Openai, Openrouter, Perplexity, Together, Vercel, X Ai)

OPENAI_LOG

One of: 'debug', 'info', 'warning', 'error' (Used by: Azure, Cerebras, Deepseek, Fireworks, Github, Groq, Heroku, Moonshot, Ollama, Openai, Openrouter, Perplexity, Together, Vercel, X Ai)

SSL_CERT_FILE

Path to the SSL certificate file for requests (Used by: Azure, Azure, Voyage)

AI_GATEWAY_API_KEYsecret

API key for Vercel service

AWS_ACCOUNT_ID

AWS Account ID for Bedrock service

AWS_REGION

AWS region for Bedrock service

AWS_SECRET_ACCESS_KEYsecret

AWS Secret Access Key for Bedrock service

AZURE_COHERE_API_KEYsecret

API key for Azure Cohere service (cohere models on Azure)

AZURE_COHERE_ENDPOINT

Endpoint for Azure Cohere service (cohere models on Azure)

AZURE_COHERE_REGION

Region for Azure Cohere service

AZURE_OPENAI_API_KEYsecret

API key for Azure OpenAI service (OpenAI models on Azure)

AZURE_OPENAI_ENDPOINT

Endpoint for Azure OpenAI service (OpenAI models on Azure)

AZURE_OPENAI_REGION

Region for Azure OpenAI service (OpenAI models on Azure)

COHERE_API_KEY

Your Cohere API Key

CO_API_URL

Host URL for Cohere service

DEEPSEEK_API_KEYsecret

API key for DeepSeek service

GEMINI_API_KEY

Your Google Gemini API Key

GOOGLE_API_KEY

Your Google API Key

HF_HUB_VERBOSITY

Log level for Hugging Face Hub client

HF_TOKEN

API key/token for Hugging Face service

INFERENCE_KEYsecret

API key for Heroku service

INFERENCE_URL

Host URL for Heroku service

MISTRAL_API_KEY

Your Mistral API Key

QDRANT__LOG_LEVEL

Log level for Qdrant service

QDRANT__SERVICE__API_KEYsecret

API key for Qdrant service

QDRANT__SERVICE__ENABLE_TLS

Enable TLS for Qdrant service, expects truthy or false value (e.g. 1 for on, 0 for off).

QDRANT__SERVICE__HOST

Hostname of the Qdrant service; do not use for URLs with schemes (e.g. 'http://')

QDRANT__SERVICE__HTTP_PORT

Port number for the Qdrant service

QDRANT__TLS__CERT

Path to the TLS certificate file for Qdrant service. Only needed if using a self-signed certificate. If you're using qdrant-cloud, you don't need this.

TAVILY_API_KEY

Your Tavily API Key

TOGETHER_API_KEYsecret

API key for Together service

VERCEL_OIDC_TOKENsecret

OIDC token for Vercel service

VOYAGE_API_KEYsecret

API key for Voyage service

Arguments

--project

path

--config

file_path

--hostdefault 127.0.0.1

host

--portdefault 9328

port

--transportdefault streamable-http

--verbose

--debug

--rm

-vdefault {workspace}:/workspace:ro

-edefault CODEWEAVER_PROJECT_PATH=/workspace

-pdefault {host_port}:9328

--networkdefault {network}

claude_desktop_config.json

{
  "mcpServers": {
    "codeweaver": {
      "command": "uvx",
      "args": [
        "code-weaver",
        "server",
        "--project",
        "--config",
        "--host",
        "127.0.0.1",
        "--port",
        "9328",
        "--transport",
        "streamable-http",
        "--verbose",
        "--debug"
      ],
      "env": {
        "CODEWEAVER_CONFIG_FILE": "<YOUR_CODEWEAVER_CONFIG_FILE>",
        "CODEWEAVER_DEBUG": "false",
        "CODEWEAVER_EMBEDDING_API_KEY": "<YOUR_CODEWEAVER_EMBEDDING_API_KEY>",
        "CODEWEAVER_EMBEDDING_MODEL": "voyage-code-3",
        "CODEWEAVER_EMBEDDING_PROVIDER": "voyage",
        "CODEWEAVER_HOST": "localhost",
        "CODEWEAVER_LOG_LEVEL": "WARNING",
        "CODEWEAVER_MCP_PORT": "9328",
        "CODEWEAVER_PORT": "9329",
        "CODEWEAVER_PROFILE": "<YOUR_CODEWEAVER_PROFILE>",
        "CODEWEAVER_PROJECT_NAME": "<YOUR_CODEWEAVER_PROJECT_NAME>",
        "CODEWEAVER_PROJECT_PATH": "<YOUR_CODEWEAVER_PROJECT_PATH>",
        "CODEWEAVER_RERANKING_API_KEY": "<YOUR_CODEWEAVER_RERANKING_API_KEY>",
        "CODEWEAVER_RERANKING_MODEL": "rerank-2.5",
        "CODEWEAVER_RERANKING_PROVIDER": "voyage",
        "CODEWEAVER_SPARSE_EMBEDDING_MODEL": "prithivida/Splade_pp_en_v1",
        "CODEWEAVER_SPARSE_EMBEDDING_PROVIDER": "fastembed",
        "CODEWEAVER_VECTOR_STORE_API_KEY": "<YOUR_CODEWEAVER_VECTOR_STORE_API_KEY>",
        "CODEWEAVER_VECTOR_STORE_PORT": "6333",
        "CODEWEAVER_VECTOR_STORE_PROVIDER": "qdrant",
        "CODEWEAVER_VECTOR_STORE_URL": "http://localhost",
        "CODEWEAVER__TELEMETRY__DISABLE_TELEMETRY": "false",
        "CODEWEAVER__TELEMETRY__TOOLS_OVER_PRIVACY": "false",
        "HTTPS_PROXY": "<YOUR_HTTPS_PROXY>",
        "OPENAI_API_KEY": "<YOUR_OPENAI_API_KEY>",
        "OPENAI_LOG": "<YOUR_OPENAI_LOG>",
        "SSL_CERT_FILE": "<YOUR_SSL_CERT_FILE>",
        "AI_GATEWAY_API_KEY": "<YOUR_AI_GATEWAY_API_KEY>",
        "AWS_ACCOUNT_ID": "<YOUR_AWS_ACCOUNT_ID>",
        "AWS_REGION": "<YOUR_AWS_REGION>",
        "AWS_SECRET_ACCESS_KEY": "<YOUR_AWS_SECRET_ACCESS_KEY>",
        "AZURE_COHERE_API_KEY": "<YOUR_AZURE_COHERE_API_KEY>",
        "AZURE_COHERE_ENDPOINT": "<YOUR_AZURE_COHERE_ENDPOINT>",
        "AZURE_COHERE_REGION": "<YOUR_AZURE_COHERE_REGION>",
        "AZURE_OPENAI_API_KEY": "<YOUR_AZURE_OPENAI_API_KEY>",
        "AZURE_OPENAI_ENDPOINT": "<YOUR_AZURE_OPENAI_ENDPOINT>",
        "AZURE_OPENAI_REGION": "<YOUR_AZURE_OPENAI_REGION>",
        "COHERE_API_KEY": "<YOUR_COHERE_API_KEY>",
        "CO_API_URL": "<YOUR_CO_API_URL>",
        "DEEPSEEK_API_KEY": "<YOUR_DEEPSEEK_API_KEY>",
        "GEMINI_API_KEY": "<YOUR_GEMINI_API_KEY>",
        "GOOGLE_API_KEY": "<YOUR_GOOGLE_API_KEY>",
        "HF_HUB_VERBOSITY": "<YOUR_HF_HUB_VERBOSITY>",
        "HF_TOKEN": "<YOUR_HF_TOKEN>",
        "INFERENCE_KEY": "<YOUR_INFERENCE_KEY>",
        "INFERENCE_URL": "<YOUR_INFERENCE_URL>",
        "MISTRAL_API_KEY": "<YOUR_MISTRAL_API_KEY>",
        "QDRANT__LOG_LEVEL": "<YOUR_QDRANT_LOG_LEVEL>",
        "QDRANT__SERVICE__API_KEY": "<YOUR_QDRANT_SERVICE_API_KEY>",
        "QDRANT__SERVICE__ENABLE_TLS": "<YOUR_QDRANT_SERVICE_ENABLE_TLS>",
        "QDRANT__SERVICE__HOST": "<YOUR_QDRANT_SERVICE_HOST>",
        "QDRANT__SERVICE__HTTP_PORT": "<YOUR_QDRANT_SERVICE_HTTP_PORT>",
        "QDRANT__TLS__CERT": "<YOUR_QDRANT_TLS_CERT>",
        "TAVILY_API_KEY": "<YOUR_TAVILY_API_KEY>",
        "TOGETHER_API_KEY": "<YOUR_TOGETHER_API_KEY>",
        "VERCEL_OIDC_TOKEN": "<YOUR_VERCEL_OIDC_TOKEN>",
        "VOYAGE_API_KEY": "<YOUR_VOYAGE_API_KEY>"
      }
    }
  }
}