CodeWeaver

The missing abstraction layer between AI and your code

Installation • Features • How It Works • Documentation • Contributing

🎯 What is CodeWeaver?

CodeWeaver gives both humans and AI a deep, structural understanding of your project — not just text search, but real context: symbols, blocks, relationships, intent. MCP is just the delivery mechanism; CodeWeaver is the capability.

If you want AI that actually knows your code instead of guessing, this is the foundation.

⚠️ Alpha Release: CodeWeaver is in active development. Use it, break it, shape it, help make it better.

🔍 Why CodeWeaver Exists

The Problems

Problem	Impact
🔴 Poor Context = Poor Results	Agents are better at generating new code than understanding existing structure
💸 Massive Inefficiency	Agents read the same huge files repeatedly (50%+ context waste is common)
🔧 Wrong Abstraction	Tools built for humans, not for how agents actually work
🔒 No Ownership	Existing solutions locked into specific IDEs or agent clients like Claude Code

The result: Shallow, inconsistent, fragile context. And you don't control it.

CodeWeaver's Approach

✅ One focused capability: Structural + semantic code understanding ✅ Hybrid search built for code, not text ✅ Works offline, airgapped, or degraded ✅ Deploy it however you want ✅ One great tool instead of 30 mediocre ones

📖 Read the detailed rationale →

🚀 Getting Started

Quick Install

Using the CLI with uv:

# Add CodeWeaver to your project
uv add --prerelease allow --dev code-weaver

# Initialize config and MCP setup
cw init

# Verify setup
cw doctor

# Start the server
cw server

📝 Note: cw init defaults to CodeWeaver's recommended profile, which requires:

🔑 Voyage AI API key (generous free tier)

🗄️ Qdrant instance (cloud or local, generous free tier for cloud, free local)

🐳 Prefer Docker? See Docker setup guide →

MCP Configuration

CodeWeaver uses stdio transport by default, which proxies to the HTTP backend daemon. First start the daemon with codeweaver start, then MCP clients can connect via stdio.

cw init will add CodeWeaver to your project's .mcp.json:

{
  "mcpServers": {
    "codeweaver": {
      "type": "stdio",
      "cmd": "uv",
      "args": ["run", "codeweaver", "server"],
      "env": {"SOME_API_KEY_FOR_PROVIDERS": "value"}
    }
  }
}

{
  "mcpServers": {
    "codeweaver": {
      "type": "http",
      "url": "http://127.0.0.1:9328/mcp"
    }
  }
}

✨ Features

🧠 Smart Search

Hybrid search (sparse + dense)
AST-level understanding
Semantic relationships
Context-aware chunking

🌐 Language Support

26 languages with full AST/semantic
166+ languages with intelligent chunking
Family heuristics for smart parsing

🔄 Resilient & Offline

Automatic fallback to local models
Works offline/airgapped
Health monitoring with graceful degradation
Better degraded than others' primary mode

⚙️ Flexible Configuration

~15 config sources (TOML/YAML/JSON)
Cloud secret stores (AWS/Azure/GCP)
Hierarchical merging
Environment overrides

🔌 Provider Support

Multiple embedding providers
Sparse & dense models
Reranking support
See full provider list →

🛠️ Developer Experience

Live indexing with file watching
Low CPU overhead
Full CLI (cw / codeweaver)
Health, metrics, status endpoints

🏗️ How It Works

CodeWeaver combines AST-level understanding, semantic relationships, and hybrid embeddings (sparse + dense) to deliver both contextual and literal understanding of your codebase.

The goal: give AI the fragments it should see, not whatever it can grab.

Architecture Highlights

┌─────────────────────────────────────────────────────────┐
│                    Your Codebase                        │
└────────────────┬────────────────────────────────────────┘
                 │
                 ▼
        ┌────────────────┐
        │  Live Indexing  │ ← AST parsing + semantic analysis
        └────────┬───────┘
                 │
                 ▼
    ┌────────────────────────┐
    │   Hybrid Vector Store   │ ← Sparse + Dense embeddings
    └────────┬───────────────┘
             │
             ▼
    ┌─────────────────┐
    │  Reranking Layer │ ← Relevance optimization (heuristic and reranking model)
    └────────┬────────┘
             │
             ▼
    ┌──────────────────┐
    │   MCP Interface   │ ← Simple "find_code" tool (`find_code("authentication api")`)
    └────────┬─────────┘
             │
             ▼
       ┌─────────┐
       │   AI    │
       └─────────┘

CLI Commands

cw start     # Start daemon in background (or --foreground)
cw stop      # Stop the daemon
cw server    # Run the MCP server (stdio by default)
cw doctor    # Full setup diagnostic
cw index     # Run indexing without server
cw init      # Set up MCP + config
cw list      # List providers, models, capabilities
cw status    # Live server status, health, index state
cw search    # Test the search engine
cw config    # View resolved configuration

Running as a System Service

Install CodeWeaver to start automatically on login:

cw init service          # Install and enable (systemd/launchd)
cw init service --uninstall  # Remove the service

📖 Full CLI Guide →

📊 Current Status (Alpha)

Stability Snapshot: Strong Core, Prickly Edges

Component	Status	Notes
🔄 Live indexing & file watching	⭐⭐⭐⭐	Runs continuously; reliable
🌳 AST-based chunking	⭐⭐⭐⭐	Full semantic/AST for 26 languages
📝 Context-aware chunking	⭐⭐⭐⭐	166+ languages, heuristic AST-lite
🔌 Provider integration	⭐⭐⭐	Voyage/FastEmbed reliable, others vary
🛡️ Automatic fallback	⭐⭐⭐	Seamless offline/degraded mode
💻 CLI	⭐⭐⭐⭐	Core commands fully wired and tested
🐳 Docker build	⭐⭐⭐	Skip local Qdrant setup entirely
🔗 MCP interface	⭐⭐⭐	Core ops reliable, some edge cases
🌐 HTTP endpoints	⭐⭐⭐	Health, metrics, state, versions stable

Legend: ⭐⭐⭐⭐ = solid | ⭐⭐⭐ = works with quirks | ⭐⭐ = experimental | ⭐ = chaos gremlin

🗺️ Roadmap

The enhancement issues describe detailed plans. Short version:

📚 Way better docs – comprehensive guides and tutorials
🤖 AI-powered context curation – agents identify purpose and intent
🔧 Data provider integration – Tavily, DuckDuckGo, Context7, and more
💉 True DI system – replace existing registry
🕸️ Advanced orchestration – integrate pydantic-graph

What Will Stay: One Tool

One tool. We give AI agents one simple tool: find_code.

Agents just need to explain what they need. No complex schemas. No novella-length prompts.

📚 Documentation

For Users

🐳 Docker Setup Notes
🚀 Getting Started Guide

For Developers

Product Philosophy

💭 Product Decisions – transparency matters
🤔 Why CodeWeaver? – detailed rationale

🤝 Contributing

PRs, issues, weird edge cases, feature requests — all welcome!

This is still early, and the best time to help shape the direction.

How to Contribute

🍴 Fork the repository
🌿 Create a feature branch
✨ Make your changes
✅ Add tests if applicable
📝 Update documentation
🚀 Submit a PR

You'll need to agree to our Contributor License Agreement.

Found a Bug?

🐛 Report it here – include as much detail as possible!

🔗 Links

Project

📦 Repository: github.com/knitli/codeweaver
🐛 Issues: Report bugs & request features
📋 Changelog: View release history

Company

🏢 Knitli: knitli.com
✍️ Blog: blog.knitli.com
🐦 X/Twitter: @knitli_inc
💼 LinkedIn: company/knitli
💻 GitHub: @knitli

Support the Project

We're a one-person company at the moment... and make no money... if you like CodeWeaver and want to keep it going, please consider sponsoring me 😄

📦 Package Info

Python package: code-weaver 👈❗ note the hyphen
CLI commands: cw / codeweaver
Python requirement: ≥3.12 (tested on 3.12, 3.13, 3.14)
Entry point: codeweaver.cli.app:main

📄 License

Licensed under MIT OR Apache 2.0 — you choose! Some vendored code is Apache 2.0 only and some is MIT only. Everything is permissively licensed.

The project follows the REUSE specification. Every file has detailed licensing information, and we regularly generate a software bill of materials.

📊 Telemetry

The default includes very anonymized telemetry to improve CodeWeaver. See the implementation or read the README.

Opt out: export CODEWEAVER__TELEMETRY__DISABLE_TELEMETRY=true

Opt in to detailed feedback (helps us improve): export CODEWEAVER__TELEMETRY__TOOLS_OVER_PRIVACY=true

📋 See our privacy policy

⚠️ API Stability

Warning: The API will change. Our priority right now is giving you and your coding agent an awesome tool.

To deliver on that, we can't get locked into API contracts while we're in alpha. We also want you to be able to extend and build on CodeWeaver — once we get to stable releases.

Built with ❤️ by Knitli

⬆ Back to top

codeweaver

Documentation