contextd

Local-first semantic search meets AI context.

A privacy-preserving daemon that transforms your codebase into queryable intelligence for AI assistants.

Why contextd?

🔒 100% Local - Your code never leaves your machine
🤖 MCP Native - Universal backend for Claude, Cline, Roo Code, Continue, & more
🔍 Hybrid Search - Combines semantic understanding with keyword precision (FTS5)
⚡ Lightning Fast - Query caching and optimized indexing
🌍 Polyglot - Native support for Rust, Python, JS/TS, Go, Markdown, PDF
🎯 Smart Chunking - Tree-sitter based semantic code splitting
🔌 Extensible - Plugin system for any file format

Quick Start

0. Playground (Try in 30 Seconds)

curl -fsSL https://raw.githubusercontent.com/sandy-sachin7/contextd/main/scripts/playground.sh | bash

This downloads contextd, indexes your current directory, and runs a semantic search — no setup needed.

1. Install

One-line installer (Linux/macOS):

curl -sSL https://raw.githubusercontent.com/sandy-sachin7/contextd/main/scripts/install.sh | sh

Homebrew (macOS/Linux):

brew install sandy-sachin7/tap/contextd

Docker:

docker run -v $PWD:/workspace ghcr.io/sandy-sachin7/contextd

From source:

git clone https://github.com/sandy-sachin7/contextd.git
cd contextd
cargo run -- setup
cargo build --release

2. Run as Daemon

# Start the daemon (watches your configured directories)
./target/release/contextd daemon

# Or use the CLI for one-off queries
./target/release/contextd query "authentication system"

3. Connect your AI Tools (Automatic)

# Auto-detect AI tools and configure MCP for all of them
contextd connect --all

contextd supports 8 AI tools out of the box:

Tool	Config Format	Detection
Claude Desktop	Object (`mcpServers`)	Binary in PATH
Claude Code	Object (`mcpServers`)	Binary in PATH
Cursor	Object (`mcpServers`)	Binary or `.cursor/` dir
VSCode Copilot	Object (`servers`)	Always detected
Copilot CLI	Object (`mcpServers`)	Binary in PATH
OpenCode	Object (`mcp` + `$schema`)	Binary or `~/.config/opencode/`
Continue	Array (`mcpServers[]`)	`~/.continue/` directory
Antigravity (agy)	Object (`mcpServers`)	Binary in PATH

Each contextd connect run:

Detects installed tools
Reads existing config (preserves other entries)
Adds or updates contextd MCP server entry
Writes config atomically

See MCP Integration Guide for manual setup.

Features in Detail

🔍 Hybrid Search

contextd combines vector embeddings with full-text search (SQLite FTS5) for superior results:

Semantic: Understands meaning and context
Keyword: Fast exact matches
Weighted: Automatically balances both approaches

🧩 Smart Code Chunking

Tree-sitter based parsing for:

Python: Functions, classes, methods
JavaScript/TypeScript: Functions, classes, arrow functions
Go: Functions, methods, structs
Rust: Functions, structs, impls, traits
Markdown: Header-based sections
PDF: Page-level extraction

⚡ Performance

Query Caching: Repeated queries use cached embeddings
Adaptive Debouncing: Batches file changes to avoid CPU spikes
Incremental Updates: Only re-indexes changed files

🎯 Search Intelligence (v1.0.0+)

Recency Boost: Recently modified files rank higher (configurable recency_weight)
Frequency Ranking: Frequently queried files get priority (configurable frequency_weight)
Smart Blending: Combines semantic, keyword, recency, and frequency signals

🔌 Plugin System

Extend support to any file format:

[plugins]
docx = ["pandoc", "-t", "plain"]
ipynb = ["jupyter", "nbconvert", "--to", "markdown", "--stdout"]

Usage

Daemon Mode (Background Service)

# Start daemon with default config
contextd daemon

# With custom config
contextd daemon --config /path/to/contextd.toml

CLI Mode (One-off Queries)

# Basic query
contextd query "authentication"

# With filters
contextd query "database schema" --limit 10 --min-score 0.7

# Filter by time range
contextd query "API changes" --after 2024-12-01

REST API

# Query endpoint
curl -X POST http://localhost:3030/query \
  -H "Content-Type: application/json" \
  -d '{
    "query": "How does auth work?",
    "limit": 5,
    "min_score": 0.5,
    "file_types": [".rs", ".py"]
  }'

# Health check
curl http://localhost:3030/health

# Status/stats
curl http://localhost:3030/status

MCP Server Mode

# Run as MCP server (for Claude Desktop integration)
contextd mcp

Configuration

[server]
host = "127.0.0.1"
port = 3030

[storage]
db_path = "contextd.db"
model_path = "models"
model_type = "all-minilm-l6-v2"  # See available models below

Available Embedding Models

Model	Dimensions	Best For
`all-minilm-l6-v2` (default)	384	General purpose, fast
`all-mpnet-base-v2`	768	Higher quality, recommended for code
`bge-small-en-v1.5`	384	Good quality/speed balance

To switch models, change model_type in config and run:

contextd setup

Full Configuration

[server]
host = "127.0.0.1"
port = 3030

[storage]
db_path = "contextd.db"
model_path = "models"
model_type = "all-minilm-l6-v2"

[search]
enable_cache = true
cache_ttl_seconds = 3600
hybrid_weight = 0.7  # 70% semantic, 30% keyword

[watch]
paths = ["/path/to/code", "/path/to/docs"]
debounce_ms = 200

[chunking]
max_chunk_size = 512
overlap = 50

[plugins]
docx = ["pandoc", "-t", "plain"]
py = ["cat"]  # Or use native parser

Ignoring Files

contextd respects .gitignore by default. You can also create a .contextignore file to exclude specific files from indexing without affecting git:

# .contextignore
*.log
temp/
secret_keys.json

Use Cases

1. AI-Powered Code Understanding

Ask Claude "Show me how authentication is implemented" and get actual code from your project.

2. Documentation Search

Index your Markdown docs and query them semantically: "deployment process" finds relevant sections even without exact keywords.

3. Research Notes

Turn your Zettelkasten or Obsidian vault into a queryable knowledge base.

4. Legacy Codebase Exploration

Point contextd at that scary old project and let AI help you understand it.

Architecture

┌─────────────┐
│  File Watch │ → Debouncer → .contextignore Filter
└─────────────┘
       │
       ▼
┌─────────────┐
│   Parser    │ → Plugin System / Native Parsers
└─────────────┘
       │
       ▼
┌─────────────┐
│   Chunker   │ → Tree-sitter (Rust/Py/JS/TS/Go) / Header-based (MD) / Pages (PDF)
└─────────────┘
       │
       ▼
┌─────────────┐
│  Embedder   │ → ONNX Runtime (Local, no cloud!)
└─────────────┘
       │
       ▼
┌─────────────┐
│   Storage   │ → SQLite + FTS5 (Hybrid search)
└─────────────┘
       │
       ▼
┌─────────────┐
│ Query Layer │ → REST API / CLI / MCP Server
└─────────────┘

Integrations

contextd works with any tool that supports the Model Context Protocol:

Claude Desktop: Setup Guide
Cline / Roo Code: Setup Guide
Continue: Setup Guide

VSCode Extension

Full-featured extension with webview search panel, QuickPick, sidebar, and daemon lifecycle management. Install from marketplace or search "contextd" in VSCode extensions.

Obsidian Plugin

Community contribution welcome!

Performance

Benchmarks on a typical codebase (10K files, ~500K LOC):

Initial indexing: ~2-3 minutes
Query latency: <50ms p99
Memory usage: ~150MB for 100K chunks
Re-index on file change: <100ms

Comparison

Feature	contextd	Sourcegraph	GitHub Copilot	Cursor	Roo Code
Local-first	✅	❌	❌	❌	✅
MCP Native	✅	❌	❌	❌	✅
Hybrid Search	✅	✅	❌	✅	❌
Open Source	✅	Partial	❌	❌	✅
Self-hosted	✅	✅ ($$$)	❌	❌	✅
Auto-configure 8 tools	✅	❌	❌	❌	❌
VSCode Extension	✅	✅	✅	❌	✅

Testing

contextd includes a comprehensive test suite ensuring rock-solid reliability:

Test Coverage

28 Unit Tests: Core functionality (chunking, plugins, database, ranking)
8 Integration Tests: Load testing, file watcher reliability
25+ E2E Tests: MCP protocol compliance, error handling, edge cases
Memory Stress Testing: 10K files, 1K queries with profiling

Running Tests

# Unit tests (fastest - 30s)
cargo test --bin contextd

# Integration tests
cargo test --test load_test
cargo test --test watcher_test

# MCP end-to-end tests
python3 scripts/test_mcp_local.py

# Memory stress test (requires psutil)
pip install psutil
python3 scripts/memory_stress_test.py

See tests/README.md for detailed testing documentation.

Contributing

See CONTRIBUTING.md

Roadmap

License

MIT - see LICENSE

Acknowledgments

Tree-sitter for AST parsing
ONNX Runtime for local inference
SQLite FTS5 for hybrid search
The MCP community for the protocol

Star ⭐ this repo if contextd helps you understand your code better!

Name		Name	Last commit message	Last commit date
Latest commit History 99 Commits
.cargo		.cargo
.github		.github
benches		benches
completions		completions
docs		docs
homebrew		homebrew
scripts		scripts
src		src
tests		tests
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
Dockerfile		Dockerfile
LICENSE		LICENSE
Personal_plan.md		Personal_plan.md
README.md		README.md
SECURITY.md		SECURITY.md
contextd.example.toml		contextd.example.toml
docker-compose.yml		docker-compose.yml
rust-toolchain.toml		rust-toolchain.toml

Folders and files

Latest commit

History

Repository files navigation

contextd

Why contextd?

Quick Start

0. Playground (Try in 30 Seconds)

1. Install

2. Run as Daemon

3. Connect your AI Tools (Automatic)

Features in Detail

🔍 Hybrid Search

🧩 Smart Code Chunking

⚡ Performance

🎯 Search Intelligence (v1.0.0+)

🔌 Plugin System

Usage

Daemon Mode (Background Service)

CLI Mode (One-off Queries)

REST API

MCP Server Mode

Configuration

Available Embedding Models

Full Configuration

Ignoring Files

Use Cases

1. AI-Powered Code Understanding

2. Documentation Search

3. Research Notes

4. Legacy Codebase Exploration

Architecture

Integrations

VSCode Extension

Obsidian Plugin

Performance

Comparison

Testing

Test Coverage

Running Tests

Contributing

Roadmap

License

Acknowledgments

About

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 11

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages