🚀 What is Coraline?

Coraline is a Rust implementation that combines the best ideas from two powerful coding tools:

• CodeGraph - Semantic code knowledge graphs for efficient AI exploration
• Serena - Symbol-level code understanding and editing tools

Built from the ground up in Rust, Coraline provides:

• ⚡ Native performance - Fast indexing and queries without Node.js overhead
• 🧠 Semantic search - Find code by meaning using vector embeddings
• 🔧 Symbol-level tools - IDE-like precision for AI assistants
• 🔒 100% local - All processing happens on your machine
• 🌐 MCP integration - Works with Claude Desktop, Claude Code, and other MCP clients

✨ Key Features

From CodeGraph

• Semantic Knowledge Graph - Pre-indexed symbol relationships and call graphs
• Multi-language Support - 33 languages including TypeScript, Rust, Python, Go, C#, Java, C/C++, Ruby, Bash, PHP, Swift, Kotlin, Markdown, TOML
• Vector Embeddings - Semantic code search using local ONNX models
• Impact Analysis - Understand what code changes will affect
• Git Integration - Auto-sync on commits to keep index fresh

From Serena

• Symbol-level Operations - Find, read, and edit code at the function/class/method level
• Reference Resolution - Find all references to a symbol across the codebase
• Precise Editing - Insert before/after symbols, replace symbol bodies
• Project Memories - Persistent knowledge storage for project context
• Smart Context Building - Gather relevant code for AI assistants efficiently

📦 Installation

From crates.io (recommended)

cargo install coraline

This builds and installs the coraline binary to your Cargo bin directory and adds it to your PATH.

Windows note: After installation completes the binary is at %USERPROFILE%\.cargo\bin\coraline.exe.
This directory is automatically added to PATH by the Rust installer (rustup). Open a new terminal
and run coraline --version to confirm it's working. If you see "command not found", add
%USERPROFILE%\.cargo\bin to your PATH manually via System Properties → Environment Variables.

Pre-built binaries

Download the latest release archive for your platform from the
Releases page:

Extract the archive and move the binary somewhere on your PATH:

# Linux / macOS
tar xzf coraline-*.tar.gz
sudo mv coraline /usr/local/bin/

# Windows (PowerShell)
Expand-Archive coraline-windows-x86_64.exe.zip .
# Move coraline.exe to a directory on your PATH, e.g.:
Move-Item coraline.exe "$env:USERPROFILE\.cargo\bin\"

Build from Source

git clone https://github.com/greysquirr3l/coraline.git
cd coraline
cargo install --path crates/coraline --force

Semantic Search / LLM Embeddings

Semantic search is included by default — cargo install coraline bundles ONNX/vector-embedding support (via the embeddings feature). No extra flags required.

After running coraline init, you will be prompted to download the embedding model (~137 MB) if stdin is a TTY:

Download embedding model for semantic search? (~137 MB) [Y/n]

You can always download or re-download the model manually:

# Download the int8-quantised model (~137 MB) from HuggingFace
coraline model download

# Generate embeddings for the indexed project
coraline embed

# Combine both steps
coraline embed --download

# Check which model files are present
coraline model status

Models are stored per-project in .coraline/models/. If no model is present, coraline_semantic_search is simply not registered as an MCP tool — all other tools remain fully functional.

Note: Pre-built release binaries do not include the embeddings feature (to keep them statically linkable). Build from source for semantic search in pre-built environments.

Older Linux / HPC systems (glibc issues)

If the embeddings feature fails to compile due to glibc incompatibility (e.g., Rocky Linux, CentOS, HPC nodes), use embeddings-dynamic instead — it links against a system-installed libonnxruntime.so at runtime:

cargo install coraline --no-default-features --features embeddings-dynamic

You must have ONNX Runtime installed and on your library path (LD_LIBRARY_PATH or /usr/local/lib).

Alternatively, download the musl static binary from the Releases page — zero glibc dependency (embeddings not included).

🚀 Quick Start

1. Initialize a Project

cd your-project
coraline init

This creates a .coraline/ directory with:

• SQLite database for the code graph
• Configuration file
• Project memories

2. Index Your Code

coraline index

Coraline will:

• Parse source files using tree-sitter
• Extract symbols (functions, classes, methods, types)
• Build the call graph and reference map

Semantic search: run coraline embed after indexing to generate vector embeddings (model download is prompted automatically on coraline init).

3. Use as MCP Server

Configure your MCP client to use Coraline:

For Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "coraline": {
      "command": "/path/to/coraline",
      "args": ["serve", "--mcp"],
      "env": {}
    }
  }
}

For Claude Code (.claude/mcp.json in your workspace):

{
  "mcpServers": {
    "coraline": {
      "command": "coraline",
      "args": ["serve", "--mcp"]
    }
  }
}

💻 CLI Usage

coraline init [path]              # Initialize project
coraline index [path]             # Build code graph
coraline sync [path]              # Incremental update (git-diff based)
coraline status [path]            # Show project status and paths
coraline stats [path]             # Show index statistics
coraline query <search>           # Search symbols
coraline context <task>           # Build AI context
coraline callers <node-id>        # Find what calls a symbol
coraline callees <node-id>        # Find what a symbol calls
coraline impact <node-id>         # Analyze change impact
coraline config [--set key=val]   # Read or update configuration
coraline hooks install|remove     # Manage git post-commit hook
coraline serve --mcp              # Start MCP server

See docs/CLI_REFERENCE.md for full documentation.

🔌 MCP Tools

When running as an MCP server, Coraline exposes 26 tools prefixed with coraline_ (coraline_semantic_search requires the embedding model to be downloaded — see Semantic Search).
See docs/MCP_TOOLS.md for the full reference.

Graph Tools

Context Tool

File & Config Tools

Memory Tools

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        AI Assistant (MCP Client)                 │
│                    (Claude, VS Code, etc.)                       │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│                     Coraline MCP Server                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │ Graph Tools  │  │ Symbol Tools │  │ Memory Tools │          │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘          │
│         └──────────────────┼──────────────────┘                 │
│                            ▼                                     │
│              ┌─────────────────────────┐                         │
│              │   Core Engine (Rust)    │                         │
│              │   • tree-sitter parser  │                         │
│              │   • SQLite database     │                         │
│              │   • Vector embeddings   │                         │
│              │   • Reference resolver  │                         │
│              └─────────────────────────┘                         │
└─────────────────────────────────────────────────────────────────┘

Data Flow

1. Parsing: tree-sitter extracts AST and symbols
2. Storage: Nodes and edges stored in SQLite
3. Resolution: References resolved to definitions
4. Embeddings: Symbols embedded for semantic search (ONNX)
5. Query: Graph traversal + vector similarity
6. Serve: Results returned via MCP protocol

🌐 Supported Languages

Coraline uses tree-sitter for fast, accurate code parsing. Current support:

✅ Fully Implemented

🔄 In Progress

Note: Language support requires tree-sitter grammar integration. Some parsers require older tree-sitter versions and will be added when updated parsers are available.

⚙️ Configuration

Configuration lives in .coraline/config.toml. A commented template is created by coraline init.

[indexing]
max_file_size = 1048576   # 1 MB
batch_size    = 100

[context]
max_nodes          = 20
max_code_blocks    = 5
max_code_block_size = 1500
traversal_depth    = 1

[sync]
git_hooks_enabled = true

[vectors]
enabled = false   # ONNX embedding support (pending stable ort 2.0)

See docs/CONFIGURATION.md for the full reference.

📊 Testing

# Run all tests
cargo test --all-features

# Run with output
cargo test --all-features -- --nocapture

# Run specific integration test file
cargo test --test context_test

Current status: 38/38 tests passing
See docs/DEVELOPMENT.md for the full test structure.

📚 Documentation

🤝 Contributing

Contributions welcome! See docs/DEVELOPMENT.md for build setup, coding style, and how to add new tools and language parsers.

📄 License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

🙏 Acknowledgements

Coraline is inspired by and built upon ideas from:

• CodeGraph by Colby McHenry - Semantic code graphs for AI
• Serena by Oraios AI - Symbol-level code intelligence
• tree-sitter - Fast, incremental parsing library

🔗 References

• CodeGraph: https://github.com/colbymchenry/codegraph
• Serena: https://github.com/oraios/serena
• MCP: https://modelcontextprotocol.io/
• tree-sitter: https://tree-sitter.github.io/