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.
| 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.
✅ 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 →
# 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 initdefaults to CodeWeaver'srecommendedprofile, 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 →
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"
}
}
}
|
|
|
|
|
|
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.
┌─────────────────────────────────────────────────────────┐
│ 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 │
└─────────┘
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 configurationInstall CodeWeaver to start automatically on login:
cw init service # Install and enable (systemd/launchd)
cw init service --uninstall # Remove the service| 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
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
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.
- 💭 Product Decisions – transparency matters
- 🤔 Why CodeWeaver? – detailed rationale
PRs, issues, weird edge cases, feature requests — all welcome!
This is still early, and the best time to help shape the direction.
- 🍴 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.
🐛 Report it here – include as much detail as possible!
- 📦 Repository: github.com/knitli/codeweaver
- 🐛 Issues: Report bugs & request features
- 📋 Changelog: View release history
- 🏢 Knitli: knitli.com
- ✍️ Blog: blog.knitli.com
- 🐦 X/Twitter: @knitli_inc
- 💼 LinkedIn: company/knitli
- 💻 GitHub: @knitli
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 😄
- 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
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.
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
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