code-intelligence

A local, privacy-first code intelligence system. Indexes your codebase using AST parsing, stores embeddings in a local Qdrant vector database, and exposes search + graph tools over an MCP server that VS Code Copilot can use as an agent tool.

No cloud APIs, no API keys. Everything runs on your machine.

---

What It Does

• AST-aware indexing — extracts functions, classes, and methods as individual chunks (TypeScript/JavaScript via ts-morph, PHP via php-parser)
• Semantic search — embeds code locally using BGE-small-en-v1.5 (~33 MB, ~384-dim vectors)
• Call graph — builds outbound + inbound call edges across all symbols so retrieval can follow dependencies
• Differential indexing — only re-embeds files that changed since the last run (manifest + mtime tracking)
• Plain-file indexing — also indexes .json, .yaml, .md, Dockerfile, etc. as whole-file chunks
• MCP server — exposes tools that VS Code Copilot agent can call to explore any indexed project

---

Requirements

• Node.js ≥ 20
• Qdrant running locally on port 6333

Start Qdrant (Docker)

docker run -d -p 6333:6333 qdrant/qdrant

---

Setup

# 1. Clone and install
git clone https://github.com/your-username/code-intelligence.git
cd code-intelligence
npm install

# 2. Install the CLI globally
npm link
# → `code-intel` is now available system-wide

# 3. Start the MCP HTTP server (keep this running)
npm start
# → Listening on http://localhost:3737/mcp

The embedding model (~33 MB) is downloaded automatically on first use to ~/.cache/code-intelligence/models/ and reused across all projects.

---

CLI Usage

Index a project

code-intel index /path/to/your/project
# or from inside the project:
code-intel index .

Output:

Scanning /path/to/project...
  Embedding   [█████████████████████████] 100%  1274/1274
  Storing     [█████████████████████████] 100%  312/312
  5810 chunks extracted
  2245 symbols, 1274 files in graph
Indexing complete.

Re-running only re-embeds changed files. First run takes longer (model load + full embed).

Query a project

code-intel query "how does authentication work" --dir /path/to/project
code-intel query "where is the database connection configured" --dir .

Custom Qdrant URL

code-intel index . --qdrant http://localhost:6333
code-intel query "..." --dir . --qdrant http://localhost:6333

---

MCP Server

The MCP server exposes 6 tools to VS Code Copilot agent.

Start the server

npm start
# or in the background:
npm start &

Runs on http://localhost:3737/mcp.

Available MCP Tools

Tool	Description
index_project	Parse and index a codebase. Runs differential update — only re-embeds changed files.
index_status	Check if a project is indexed and show stats (chunks, symbols, call graph edges).
query_project	Semantic search with natural language. Returns code + file + call graph context.
get_symbol	Look up a specific symbol by name — returns source, callers, and callees.
list_symbols	List all symbols grouped by file. Supports file path filter.
get_file_chunks	Get all indexed chunks (functions, classes, methods) from a specific file.

VS Code Integration

The MCP server is registered globally in VS Code settings.json:

"mcp": {
  "servers": {
    "code-intelligence": {
      "type": "sse",
      "url": "http://localhost:3737/mcp"
    }
  }
}

With the server running, VS Code Copilot agent can call these tools automatically when you ask questions about any indexed project.

Recommended agent workflow:

1. index_project — index your project (once; re-run after large changes)
2. index_status — confirm it's ready
3. query_project — semantic search
4. get_symbol / get_file_chunks — drill into specific code

---

Language Support

Language	Functions	Classes	Methods	Call Graph
TypeScript / TSX	✅	✅	✅	✅
JavaScript / JSX	✅	✅	✅	✅
PHP	✅	✅	✅	✅
JSON / YAML / TOML	—	—	—	whole-file
Markdown / MDX	—	—	—	whole-file
Dockerfile / shell	—	—	—	whole-file

---

Storage Layout

Location	Contents
~/.cache/code-intelligence/models/	BGE embedding model (shared, downloaded once)
<project>/.code-intelligence/manifest.json	File mtimes + chunk IDs (differential indexing state)
<project>/.code-intelligence/cache.json	Embedding vector cache (avoid re-embedding unchanged files)
<project>/.code-intelligence/graph.json	Call graph: symbols → callees, callers, file locations
Qdrant collection code-<hash>	Vector embeddings + payloads, one collection per project

Add .code-intelligence to your project's .gitignore.

---

Development

# Type-check
npm run typecheck

# Run CLI without installing
npx tsx src/cli.ts index .
npx tsx src/cli.ts query "..." --dir .

# Run MCP server in stdio mode (for debugging)
npm run mcp

# Run MCP server in HTTP mode
npm start

---

License

MIT — see LICENSE.