██  ██
         ██  ██  ██    ██████ █████▄  ▄████▄
         ██  ██  ██      ██   ██▄▄██▄ ██▄▄██
         ██  ██  ██      ██   ██   ██ ██  ██
         ██  ██  ██████  ██   ██   ██ ██  ██
         ▀████▀          ▄████ ▄████▄ █████▄ █████
                         ██    ██  ██ ██  ██ ██▄▄▄
                         ▀████ ▀████▀ █████▀ ██▄▄▄

Codebase RAG for Fast and Accurate Code Work

🌐 Language: [EN] | RU

MCP server for AI coding agents. Builds a complete code structure graph (entities, relationships, control flow, complexity) and a semantic vector index. AI agents query the graph instead of reading files — and get precise, exhaustive answers with line references.

Why this matters

Without a structural index, an AI agent exploring a codebase has to grep → read file → follow imports → grep again → read more files. Each step costs tokens and time. Missed connections lead to incomplete fixes. The agent breaks code, checks, fixes, breaks again — a cycle that can repeat 10-20 times for a single task.

With UltraCode, the same agent makes one MCP call and gets back all affected entities, their relationships, callers, and impact — in a single response. No file-reading loop, no missed connections.

What changes in practice

Indexing speed

Full indexing of a medium project (~500 files) completes in 3-5 seconds (parallel parsing + batch SQL + streaming embeddings). Large projects like VS Code (~1.8M LOC, 7000+ files) — ~82 seconds including full embedding generation. After that, GitWatcher indexes only changed files — typically under 200ms per change.

Installation

The project is optimized for Bun (an alternative JavaScript runtime) and runs 50% faster with it.

Bun + UltraCode (recommended — install + setup):

# macOS / Linux
curl -fsSL https://bun.sh/install | bash && ~/.bun/bin/bun i -g ultracode --trust && ultracode-setup

# Windows (PowerShell)
irm bun.sh/install.ps1 | iex; bun i -g ultracode --trust; ultracode-setup

UltraCode only (Bun already installed):

bun i -g ultracode --trust && ultracode-setup

npm (alternative — install + setup):

npm install -g ultracode && ultracode-setup

If ultracode-setup fails after npm install (path conflict with bun), use: node "$(npm root -g)/ultracode/dist/cli/setup-command.js"

Why --trust for Bun? Bun blocks postinstall scripts by default. --trust allows native addon builds (better-sqlite3, cbor-extract, protobufjs) — all legitimate dependencies.

Note: For full code analysis on different languages, runtimes are required:

• TypeScript/JavaScript — built-in (TypeScript Compiler API)

• Python — requires Python 3.8+ (python --version)

• Java/Kotlin — requires JRE 11+ (java --version)

• Go — requires Go 1.18+ (go version)

• Rust — requires Rust toolchain (rustc --version)

• C# — requires .NET SDK 8+ (dotnet --version)

• Zig — built-in (regex-based, no Zig toolchain required)

• C/C++ — requires Clang 12+ (clang --version)

Claude Code Config (~/.claude.json):

{
  "mcpServers": {
    "ultracode": {
      "command": "ultracode"
    }
  }
}

Configuration: .autodoc/claude.cfg/add-to-CLAUDE.md

Local Model Setup

Local models are used for intelligent tasks: embedding model for semantic search and LLM for AutoDoc. This removes token costs from your main AI agent.

After installation, a setup wizard will launch and download and configure everything needed.

Step 1: Embedding Provider (semantic search)

Note for GTX xx50/xx60 laptops (GPU thermal throttling)

Budget NVIDIA GPUs (GTX 1650/1660, RTX 3050/3060, RTX 4050/4060) on laptops often suffer from power limit throttling, which drops TEI/vLLM embedding throughput by ~1000 emb/s. The GPU hits its power limit (PL1) and clocks down mid-batch.

Fix via ThrottleStop (Windows):

1. TPL button → set PL1 to max (55–75 W for laptops), PL2 to max (90–120 W), Turbo Time Limit → 28 sec (max), enable Clamp PL1/PL2 (TPL button turns green)

2. Main window → Speed Shift - EPP → 0 (max performance, reduces CPU throttle)

3. BD PROCHOT Offset → 0 (disables CPU thermal trigger for GPU)

4. Limit Reasons → check what's blocking (if "MS Platform" — ignore)

5. Apply → save profile. CPU yields thermal budget to GPU, TEI batches stabilize.

This typically gives +1000 emb/s on affected hardware.

Step 2: LLM Provider (AutoDoc, refactoring)

The wizard automatically:

• Detects your GPU (NVIDIA Turing/Ampere/Ada/Hopper/Blackwell*)

• Suggests optimal models for your hardware

• Installs selected providers

• Saves configuration to system directory

Re-run wizard:

# Bun
bunx ultracode setup

# Node.js
npx ultracode setup

*For Blackwell (RTX 50xx), an unofficial TEI fork is used

AUTODOC Setup

To activate auto-documentation mode - create a .autodoc folder in the project root and enable LLM usage (easiest to use the same claude).

After running UltraCode with Autodoc mode enabled:

1. In all folders with source code (from supported languages), AUTODOC.md files will be created with a template listing files in the directory.

2. LLM will go through these files and generate descriptions in AUTODOC.md — what the code in the files specifically does.

After this, you can yourself (or with an AI agent's help) create needed files with project overview in the .autodoc directory and add "human descriptions" in AUTODOC.md files where needed. There you can use direct references to code lines in files (for describing start and end of code block, use two numbers. Example: FILE:XX-ZZ). UltraCode will track code changes and automatically update all code references to keep them current. It won't touch documentation text.

macOS Apple Silicon (MLX Embeddings)

Native embedding support via Apple MLX framework (Metal GPU):

• MLX provider auto-detects macOS ARM64 and uses Metal GPU

• Setup wizard offers MLX as the default on Apple Silicon

• Models: intfloat/multilingual-e5-base (768d), intfloat/multilingual-e5-small (384d), BAAI/bge-m3 (1024d, 8K context)

• Auto-installs Python venv with dependencies, downloads models from HuggingFace

# Re-run wizard to switch to MLX:
bunx ultracode setup
# Select "MLX" → auto-setup venv + model + server on port 8087

GPU Acceleration (CUDA/WebGPU/Metal)

# macOS: Metal backend for CUDA-like acceleration
# Build requirements:
#   - Xcode Command Line Tools: xcode-select --install
#   - Homebrew: https://brew.sh
#   - CMake: brew install cmake
./node_modules/ultracode/scripts/build-native-libs-macos.sh

Features

MCP server provides 78 tools for code analysis and modification.

Related MCP server: Axon.MCP.Server

Search and Navigation

Code Analysis

Static Tracing and Debugging

All tracing and diagnostic tools support highlightRecentChanges=true — cross-references found entities with Prolly Tree commit history and annotates recently modified code. This helps identify the likely root cause: a recently changed entity in a crash call chain or a decision point is the first place to look.

Architecture Diagrams

Code Modification

Code Validation

Documentation (AutoDoc)

Git Integration

Multi-Agent Worktree Support

Multiple AI agents can work in parallel, each in its own git worktree on a separate branch. UltraCode detects that all worktrees belong to the same repository via repoIdentity — a stable hash of git-common-dir. All worktrees share one index, one database, and one server process.

Launching from an Agent Orchestrator

Any orchestrator (Claude Code, custom scripts, CI/CD) can spin up parallel agents with full code intelligence. Each agent gets its own MCP connection via the lightweight ultracode.com proxy (~700KB, cross-platform).

Step 1: Create worktrees

cd /path/to/your/project

# Create a worktree per agent (each on its own branch)
git worktree add ../wt-auth   -b feature/auth   main
git worktree add ../wt-pay    -b feature/payments main
git worktree add ../wt-tests  -b feature/tests    main

Step 2: Launch agents with UltraCode MCP

Each agent connects to the same running UltraCode server via Named Pipe (Windows) or Unix socket (Linux/macOS). The proxy binary handles connection, auto-start, and init handshake.

# Agent 1: auth feature
ultracode.com --pipe \
  --directory ../wt-auth \
  --branch feature/auth \
  --agent-id auth-agent

# Agent 2: payments feature
ultracode.com --pipe \
  --directory ../wt-pay \
  --branch feature/payments \
  --agent-id pay-agent

# Agent 3: test writing
ultracode.com --pipe \
  --directory ../wt-tests \
  --branch feature/tests \
  --agent-id test-agent

Step 3: Configure in claude_desktop_config.json or MCP client

{
  "mcpServers": {
    "ultracode-auth": {
      "command": "ultracode.com",
      "args": ["--pipe", "--directory", "/path/to/wt-auth",
               "--branch", "feature/auth", "--agent-id", "auth-agent"]
    },
    "ultracode-pay": {
      "command": "ultracode.com",
      "args": ["--pipe", "--directory", "/path/to/wt-pay",
               "--branch", "feature/payments", "--agent-id", "pay-agent"]
    }
  }
}

How It Works

┌─────────────┐   ┌─────────────┐   ┌─────────────┐
│  Agent #1   │   │  Agent #2   │   │  Agent #3   │
│  wt-auth    │   │  wt-pay     │   │  wt-tests   │
└──────┬──────┘   └──────┬──────┘   └──────┬──────┘
       │                 │                 │
       │ stdin/stdout    │ stdin/stdout    │ stdin/stdout
       ▼                 ▼                 ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ ultracode.com│ │ ultracode.com│ │ ultracode.com│
│   (proxy)    │ │   (proxy)    │ │   (proxy)    │
└──────┬───────┘ └──────┬───────┘ └──────┬───────┘
       │                │                │
       └────────┬───────┘────────┬───────┘
                │  Named Pipe    │
                ▼                ▼
        ┌───────────────────────────────┐
        │     UltraCode MCP Server      │
        │   (single process, shared)    │
        │                               │
        │  repoIdentity: same for all   │
        │  Index: shared base + deltas  │
        │  Locks: per branch            │
        └───────────────────────────────┘

• Shared index: all worktrees use one repoIdentity → one database, one FAISS index pool

• Branch isolation: each agent indexes its own branch delta; parallel indexing of different branches is safe

• Lock coordination: if two agents are on the same branch, only one indexes — the other waits and skips

• Session discovery: agents can see each other via list_worktree_agents — useful for task handoff

• Submodule/subtree aware: submodules get their own repoIdentity; subtrees are detected as part of the parent repo

Cleanup

# Remove worktrees when done
git worktree remove ../wt-auth
git worktree remove ../wt-pay
git worktree remove ../wt-tests

# Or via MCP tool (from any agent):
# cleanup_worktree({ branch: "feature/auth" })

Version History (Prolly Tree)

Prolly Tree stores full entity history with commit-level granularity. Beyond time travel, it powers the Recent Changes Context feature: 10 diagnostic tools (analyze_stacktrace, detect_patterns, analyze_state_chaos, trace_flow, trace_backwards, trace_data_flow, analyze_state_impact, find_decision_points, analyze_code_impact, analyze_hotspots) can annotate their results with recently-changed entity status via highlightRecentChanges=true. This means the AI agent sees not just "what's broken" but "what changed recently that could have caused it."

Semantic Merge

Snapshots and Safety

Code Graph and Indexing

Metrics and Monitoring

Additional Features

Performance

• SIMD/WebAssembly — built-in CPU acceleration

• CUDA/FAISS — GPU acceleration for large projects

• WebGPU/Dawn — cross-platform GPU acceleration

• Streaming indexing — parsing and indexing in parallel

• Local embeddings — TEI/Ollama/vLLM/MLX without external APIs

Language Support

Legend:

• Entities — functions, classes, interfaces, types, enums, variables

• Relationships — imports, calls, extends, implements, references

• Metrics — cyclomatic, cognitive complexity, control flow, documentation

• Types — type inference, type references, generics

Full details per language: .autodoc/features/language-parsers.md

Low-Resource Languages Initiative

0b00000001 lives matter!

We deliberately invest in first-class support for lesser-known yet promising languages and frameworks — so their communities get the same powerful code intelligence that mainstream ecosystems enjoy.

Currently supported: Zig — full entity extraction, relationships, control flow, and complexity metrics. Swift — full entities including SwiftUI property wrappers, inheritance/protocol conformance split, control flow.

More languages coming. If your favorite niche language deserves better tooling — open an issue.

Frameworks

Built-in Documentation (MCP Prompts)

You can add a short prompt to your system prompts that will help the AI agent learn about UltraCode capabilities.

• quick-start — quick start and tool selection

• tool-reference — complete reference of 72 tools

• workflows — ready scenarios: analysis, refactoring, duplicate detection

• tracing-guide — tracing and debugging guide

UltraCode Agent

• Task delegation — hand over complex tasks to /ultracode agent

• Maximum efficiency — agent selects optimal tools itself

• Comprehensive analysis — search, tracing, refactoring in one request

• Natural language — describe the task in your own words

Client-Server Architecture

• One process per machine — when running multiple AI agents, only one UltraCode instance runs

• Save 10+ GB RAM — instead of N copies of indexes in memory — one shared

• Instant connection — new agents connect to running server in milliseconds

• Session isolation — each agent gets independent MCP session

Configuration

Data Structure

All UltraCode data is stored in system directory:

• Windows: %LOCALAPPDATA%\UltraCode\

• macOS: ~/Library/Application Support/UltraCode/

• Linux: ~/.local/share/UltraCode/

UltraCode/
├── config/
│   ├── semantic-config.json      # Embedding/LLM providers (setup wizard)
│   └── parser-config.json        # Runtime paths (Java, Kotlin)
├── config.yaml                   # Advanced configuration
├── graph.db                      # Entities, relationships (composite keys)
├── semantic.db                   # Embeddings metadata
├── versioning.db                 # Branch history, snapshots
├── cache.db                      # Parser and query cache
├── autodoc.db                    # AutoDoc documentation database
├── projects/
│   └── {hash}/                   # Per-project data (xxHash of path)
│       ├── faiss-{branch}.bin    # FAISS vector index per branch
│       ├── faiss-{branch}.idmap.json  # FAISS ID → entity ID mapping
│       ├── faiss-{branch}-hot.bin     # Hot buffer (delta before merge)
│       └── layered/
│           ├── deltas.db         # Branch delta persistence (Layer 1)
│           └── vector-deltas.db  # Vector delta persistence
├── logs/                         # Server logs (daily rotation)
├── models/                       # Downloaded embedding models
├── hf-cache/                     # GGUF models for llama.cpp / TEI / vLLM
└── cache/
    ├── tree-sitter/              # Tree-sitter grammar cache
    └── ast/                      # AST parse cache

Configuration Parameters

Advanced parameters can be set in config/default.yaml (for developers) or via environment variables. Embedding/LLM are configured via setup wizard and stored in semantic-config.json.

Main parameters:

For AI Agents

LLM_INSTRUCTIONS.md — Why using UltraCode makes you a good boy.

Story

The project story: STORY.md

Contributing

Repository: https://github.com/faxenoff/ultracode

License

Dual License — see LICENSE

• Open Source: AGPL-3.0 — free to use, modify, and distribute with source code disclosure

• Commercial: for proprietary/closed-source use or SaaS without AGPL obligations — contact faxenoff@gmail.com