CogniCode

CogniCode is a Rust-based code intelligence server that provides deep analysis, call graphs, semantic search, and safe refactoring to AI agents via the Model Context Protocol (MCP). Think IntelliJ IDEA's capabilities — exposed as tools your AI can call.

Built with Domain-Driven Design and Clean Architecture, it supports six languages out of the box.

Features

• 32+ MCP tools — call graphs, impact analysis, semantic search, safe refactoring, complexity metrics, and more
• 6 languages — Rust, Python, TypeScript, JavaScript, Go, Java (via Tree-sitter)
• 4 graph strategies — full, lightweight, on_demand, per_file
• Persistent graph cache — RedbGraphStore survives across sessions (embedded redb database)
• Safe refactoring — rename, extract, inline, move, change signature with impact preview
• LSP navigation — go-to-definition, hover, find references
• Architecture analysis — cycle detection (Tarjan SCC), risk assessment, hot-path identification, dead code detection
• Mermaid export — generate call graph diagrams as code or rendered SVG
• Context compression — return natural language summaries instead of raw JSON
• Sandbox orchestrator — automated scenario testing and benchmarking
• Zero-config startup — works out of the box with cognicode-mcp --cwd /your/project
• OpenTelemetry integration — metrics and observability support

Installation

Pre-built binary

Download the latest release from GitHub Releases:

# Linux (x86_64)
chmod +x cognicode-mcp
./cognicode-mcp --cwd /path/to/your/project

From source

git clone https://github.com/Rubentxu/CogniCode.git
cd CogniCode
cargo build --release -p cognicode-mcp
./target/release/cognicode-mcp --cwd /path/to/your/project

Claude Desktop / Cursor / Windsurf

Add CogniCode as an MCP server in your AI client configuration:

{
  "mcpServers": {
    "cognicode": {
      "command": "cognicode-mcp",
      "args": ["--cwd", "/path/to/your/project"]
    }
  }
}

Quick Start

1. Build the graph — CogniCode needs to analyze your project first:

{ "tool": "build_graph", "arguments": { "directory": "/path/to/project" } }

1. Analyze impact of changing a symbol:

{ "tool": "analyze_impact", "arguments": { "symbol_name": "my_function" } }

1. Trace execution path between two symbols:

{ "tool": "trace_path", "arguments": { "source": "main", "target": "handle_request" } }

1. Find hot paths — most-called functions:

{ "tool": "get_hot_paths", "arguments": { "limit": 10, "min_fan_in": 3 } }

1. Refactor safely with impact preview:

{
  "tool": "safe_refactor",
  "arguments": {
    "action": "rename",
    "new_name": "new_function_name",
    "file_path": "src/lib.rs",
    "line": 42,
    "column": 4
  }
}

MCP Tools

Graph Analysis (12 tools)

Graph Operations (5 tools)

Symbols & Semantics (9 tools)

LSP Navigation (3 tools)

File Operations (5 tools)

Refactoring (1 tool)

CLI

CogniCode ships with a full-featured CLI (cognicode) for direct terminal use:

cognicode analyze [path]                          # Full code analysis
cognicode doctor [--format text|json]             # Check environment setup

cognicode index build [path] [--strategy full|lightweight|per_file|on_demand]
cognicode index query <symbol> [path]
cognicode index outline <file>
cognicode index symbol-code <file> <line> <col>

cognicode graph full [--rebuild] [path]
cognicode graph hot-paths [-n 10] [path]
cognicode graph trace-path <from> <to> [path]
cognicode graph mermaid [path] [--format svg|txt]
cognicode graph complexity [path]
cognicode graph impact <symbol> [path]

cognicode refactor rename|extract|inline|move <symbol> [new_name]

cognicode navigate definition|hover|references <file:line:col> [path]

Graph Strategies

Choose the right strategy for your use case:

Supported Languages

Architecture

CogniCode follows Domain-Driven Design with Clean Architecture and 4 bounded contexts:

┌──────────────────────────────────────────────────────────────┐
│                      COGNICODE                               │
│                                                               │
│  ┌────────────────┐  ┌────────────────┐  ┌──────────────┐  │
│  │   DOMAIN       │  │  APPLICATION   │  │ INFRASTRUCTURE│ │
│  │   (Core)       │  │   (Services)   │  │  (Impl)       │ │
│  └───────┬────────┘  └───────┬────────┘  └──────┬───────┘  │
│          │                    │                   │          │
│          └────────────────────┼───────────────────┘          │
│                               │                              │
│                    ┌──────────┴──────────┐                    │
│                    │     INTERFACE       │                    │
│                    │   (MCP, LSP, CLI)  │                    │
│                    └────────────────────┘                    │
└──────────────────────────────────────────────────────────────┘

Domain Context (Core business logic):

• Aggregates: Symbol, CallGraph, Refactor
• Value Objects: Location, SourceRange, DependencyType
• Domain Services: ImpactAnalyzer, CycleDetector, ComplexityCalculator
• Traits: CodeIntelligenceProvider, DependencyRepository, RefactorStrategy

Application Context (Orchestration):

• Services: NavigationService, RefactorService, AnalysisService
• DTOs: Request/response contracts
• Commands: Use case orchestrators

Infrastructure Context (Implementations):

• Parsers: TreeSitterParser
• Graph Stores: PetGraphStore, RedbGraphStore
• LSP: LspClient
• Persistence: RedbGraphStore (embedded redb database)

Interface Context (External protocols):

• MCP Server (Model Context Protocol)
• CLI Commands
• LSP Server

Key design decisions:

• Trait-based strategies — Graph building, refactoring, and parsing are pluggable via traits
• ArcSwap graph cache — Atomic, lock-free reads across async tasks
• Rayon parallelism — Heavy computation runs on a dedicated thread pool (8MB stack per thread)
• Workspace sandboxing — All file operations are restricted to the declared workspace
• Cancellation propagation — MCP cancellation tokens flow through all handlers
• OpenTelemetry metrics — Built-in observability with OTLP export

Workspace Crates

Configuration

Environment Variables

Feature Flags (cognicode-core)

Development

# Build all crates
cargo build --workspace

# Run tests
cargo test --workspace

# Build release binary
cargo build --release -p cognicode-mcp

# Check environment
cargo run -p cognicode-cli -- doctor

Using with AI Agents

CogniCode is designed to be the code intelligence backbone for AI agents. Instead of asking an agent to read files and guess at structure, you give it tools that return precise, structured answers.

📖 docs/agent-prompts.md contains 20 ready-to-use prompt scenarios with full reasoning chains and tool call sequences. Here's a taste:

Onboarding a New Codebase

"I just cloned this repo. Help me understand what it does, what the main entry points are, and which functions are called the most."

Agent reasoning: Build the full graph first, then get entry points (public API surface), leaf functions (low-level primitives), and hot paths (most interconnected code). Together these three give a 360° view of any unfamiliar codebase.

1. build_graph      → strategy: "full"
2. get_entry_points → the public API surface
3. get_leaf_functions → low-level primitives
4. get_hot_paths    → min_fan_in: 3  (the load-bearing functions)

Analyzing Change Impact Before a PR

"I'm about to change UserRepository.find_by_email. What will break?"

1. build_lightweight_index
2. query_symbol_index  → symbol_name: "find_by_email"
3. analyze_impact      → symbol_name: "UserRepository.find_by_email"
4. get_call_hierarchy  → direction: "incoming", depth: 3

The agent gets a risk level (low / medium / high), a list of impacted files, and the full call chain — before touching a single line of code.

These are just 2 of 20 scenarios. The full guide covers dead code detection, safe rename refactoring, complexity audits, execution path tracing, and more.

👉 Read the full Agent Prompt Guide → · Versión en español →

License

See LICENSE for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.