ultracode

v5.15.0

Published

a month ago

Codebase RAG MCP server for code understanding - semantic search, duplicate detection, impact analysis for TS/JS/Python/C#/Go/Rust/Java/C++/Kotlin/Swift/Zig/Bash

0High
0Medium
0Low

faxenoff

mcp model-context-protocol code-analysis graph rag llm agents coderag typescript vector-search semantic-search claude

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

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

| | Without UltraCode | With UltraCode | | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Search | Agent greps for keywords, reads files one by one, follows import chains manually. On a large project, finding all usages of a pattern takes dozens of agent turns and 1M+ tokens. Indirect references are often missed. | Agent calls semantic_search or query — gets all matches (including semantic: similar logic, related concepts) in one response, ~100ms, ~5K tokens. Graph traversal finds what grep cannot: indirect callers, interface implementors, data flow paths. | | Editing | Agent modifies files without knowing the full dependency tree. Typical cycle: edit → build fails → read error → fix → new error → fix → ... This "fix loop" takes 10-20 iterations, up to 1 hour and 2M+ tokens for a cross-cutting change. | Agent calls analyze_code_impact before editing to see what will break. modify_code applies changes at entity level with auto-validation (lint before/after). Impact analysis + tracing catch breakage before compilation. Large refactors compile correctly on the first try in most cases. | | Memory | Agent forgets prior context and recreates functionality that already exists. Or spends hours debugging a function it accidentally disabled. Token waste grows with session length. | Graph provides complete structural context on every call. AutoDoc maintains up-to-date documentation automatically. Agent always sees the current state — no "amnesia" problems. | | Git | Branch switches and external file changes invalidate the agent's mental model. Stale data causes silent errors. Agent must be explicitly told to re-analyze. | GitWatcher detects file changes and branch switches in real-time. Incremental re-indexing of graph and embeddings happens automatically. Every query returns current data — zero manual intervention. |

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)

| Provider | Speed | Recommendation | | --------------- | ------------- | ------------------------------------------------------------------------ | | vLLM | 1352 emb/s | ⭐ NVIDIA GPU (recommended) | | TEI | 1169 emb/s | ⭐ NVIDIA GPU (Blackwell: 120-latest image) | | MLX | ~500 emb/s | ⭐ macOS Apple Silicon (Metal GPU) | | llama.cpp | 441 emb/s | AMD GPU (Vulkan), universal | | OVMS Native | 260-326 emb/s | ⭐ CPU / Intel GPU. Can help if main VRAM is occupied by local LLM. |

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):
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)
Main window → Speed Shift - EPP → 0 (max performance, reduces CPU throttle)
BD PROCHOT Offset → 0 (disables CPU thermal trigger for GPU)
Limit Reasons → check what's blocking (if "MS Platform" — ignore)
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)

| Provider | Models | Recommendation | | ----------------------- | --------------------------------------- | -------------------------------- | | Docker Model Runner | Qwen 2.5, DeepSeek R1, Phi-4, Llama 3.2 | ⭐ If Docker Desktop is installed | | Ollama | qwen2.5-coder, deepseek-coder, phi4 | Universal option | | Skip | — | Configure later |

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:

In all folders with source code (from supported languages), AUTODOC.md files will be created with a template listing files in the directory.
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.

Search and Navigation

| Tool | Description | | ------------------------------------------------------------------------------ | ---------------------------------------------------------------- | | semantic_search | Semantic search by meaning with filters (complexity, flow, docs) | | pattern_search | Advanced search: regex, semantic, hybrid | | query | NLP queries in natural language about code | | find_similar_code | Find functions with similar logic | | cross_language_search | Unified search across all project languages | | find_related_concepts | Find related concepts |

Code Analysis

| Tool | Description | | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | analyze_code_impact | Impact analysis — what will break on modification | | find_duplicates | Semantic code clone detection | | jscpd_detect_clones | jscpd-based clone detector | | suggest_refactoring | AI-powered code improvement suggestions | | analyze_hotspots | Complex areas with high cyclomatic complexity | | analyze_state_chaos | Analysis of tangled data dependencies | | analyze_swagger_impact | Swagger/OpenAPI spec change impact analysis | | analyze_api_impact | Unified API contract impact analysis (Swagger + Protobuf + GraphQL) | | get_database_schema | Database schema from SQL/Prisma/ORM/Redis with migration analysis and drift detection | | detect_technology_stack | Project technology stack detection | | detect_patterns | Detect anti-patterns, best-patterns, code smells, and optimization opportunities with semantic validation. Includes JIT deoptimization detectors for JS/TS (hidden classes, holey arrays, megamorphic dispatch) | | check_entity_patterns | Check specific entity for pattern matches with confidence scores | | graph_metrics | PageRank, Louvain community detection, centrality analysis, and bus factor for architecture understanding | | taint_analysis | Interprocedural taint analysis: trace untrusted data from sources to sinks, detect SQL injection, XSS, command injection, missing auth |

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.

| Tool | Description | | ----------------------------------------------------------------------------- | ---------------------------------- | | trace_flow | How code flows from point A to B | | trace_backwards | Why a function is not being called | | trace_data_flow | How data affects state | | analyze_state_impact | What changes with different values | | find_decision_points | Branching points in code |

Architecture Diagrams

| Tool | Description | | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | | get_architecture_diagram | Generate architecture diagrams in Mermaid, Graphviz DOT, or D2 from code graph |

Code Modification

| Tool | Description | | -------------------------------------------------------------------------- | -------------------------------------------- | | modify_code | Structural AST-level editing with validation | | create_file | Create new file | | copy_file | Copy file with graph updates | | rename_file | Rename file with import updates | | split_file | Split file into parts | | synthesize_files | Merge files | | rename_symbol | Project-wide symbol renaming | | add_member | Add methods/properties to classes |

Code Validation

| Tool | Description | | ---------------------------------------------------------------------------- | ----------------------------------------------- | | validate_file | File validation via oxlint/Pylint/golint/clippy | | validate_directory | Batch directory validation |

Documentation (AutoDoc)

| Tool | Description | | ----------------------------------------------------------------------------------- | ------------------------------------- | | autodoc_init | Initialize AutoDoc system | | autodoc_generate | Generate documentation for entities | | autodoc_save | Save documentation to .autodoc | | autodoc_get | Get entity documentation | | autodoc_search | Semantic search through documentation | | autodoc_validate | Check documentation freshness | | autodoc_status | Documentation coverage statistics | | autodoc_sync | Synchronize with code changes | | autodoc_changelog | Documentation change history | | autodoc_install_hooks | Install Git hooks for auto-updates | | autodoc_detect_language | Detect language for generation |

Git Integration

| Tool | Description | | ------------------------------------------------------------------- | ------------------------------------ | | list_branches | List indexed branches | | switch_branch | Switch branches with auto-reindexing | | get_branch_status | Current branch status | | get_changed_files | Compare files between branches | | cleanup_branches | Clean up old branches (LRU) |

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.

| Tool | Description | | ------------------------------------------------------------------------------ | ---------------------------------------- | | spawn_agent_worktree | Create a git worktree for a new agent | | list_worktree_agents | List active worktree sessions | | cleanup_worktree | Remove a worktree | | get_worktree_info | Detailed worktree/submodule/subtree info |

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

| CLI Argument | Required | Description | | ------------------ | ----------- | ----------------------------------------------- | | --pipe | Yes | Use Named Pipe IPC (connects to running server) | | --directory PATH | Yes | Path to the agent's worktree | | --branch NAME | Recommended | Branch name (skips git detection on server) | | --agent-id ID | Recommended | Unique agent identifier for coordination |

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."

| Tool | Description | | ------------------------------------------------------------------------- | --------------------------------------------------- | | list_commits | List graph commits (version snapshots) | | get_entity_history | Entity change history across commits | | diff_commits | Compare two graph versions (added/modified/deleted) | | checkout_commit | Time travel — view graph at specific commit |

Semantic Merge

| Tool | Description | | --------------------------------------------------------------------------------- | ---------------------------------------------- | | semantic_merge | AI-powered 3-way merge with code understanding | | analyze_merge_conflicts | Analyze conflicts with explanations | | get_merge_suggestions | AI suggestions for conflict resolution | | get_semantic_merge_info | Information about semantic differences |

Snapshots and Safety

| Tool | Description | | ------------------------------------------------------------------------- | ---------------------------- | | create_snapshot | Save restore point | | undo | Instant rollback to snapshot | | list_snapshots | List available snapshots | | cleanup_snapshots | Clean up old snapshots |

Code Graph and Indexing

| Tool | Description | | ------------------------------------------------------------------------------------- | ------------------------------------- | | index | Index codebase | | clean_index | Full reindexing | | get_members | List entities in file | | list_entity_relationships | Entity relationships and dependencies | | get_graph | Get graph (JSON/GraphML/Mermaid) | | get_graph_stats | Graph statistics | | get_graph_health | Graph health diagnostics | | reset_graph | Full graph cleanup |

Metrics and Monitoring

| Tool | Description | | ------------------------------------------------------------------------- | ---------------------------------------------------------------- | | get_metrics | System metrics and statistics | | get_version | Server and runtime version | | get_agent_metrics | Multi-agent system telemetry | | get_bus_stats | Knowledge bus statistics | | clear_bus_topic | Clear cached topic entries | | get_watcher_status | Background watcher status | | get_help | Documentation and guides (quick-start, workflows, tracing, etc.) | | get_tools_for_task | Tool recommendations for a specific task |

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

| Language | Parser | -------------- | TypeScript | JavaScript | C# | Python | Kotlin | Java | Swift | Zig | Go | Rust | C/C++ | Bash | PowerShell | JSON/YAML | Protobuf | GraphQL | SQL | Prisma | Entities | Relationships | Metrics | Types | | --------------------- | -------- | ------------- | ------- | ----- | | TS Compiler + OXC | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | | TS Compiler + OXC | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | | Roslyn Compiler | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | | Regex + Pyright | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | | ANTLR4 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | | ANTLR4 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | | Regex (1342 LOC) | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐ | | Regex (1154 LOC) | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐ | | go/parser (native) | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐ | | Regex + ANTLR | ⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ | | Regex + clang | ⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ | | shfmt + tree-sitter | ⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐ | — | | tree-sitter | ⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐ | — | | native + OpenAPI | ⭐⭐⭐ | ⭐⭐⭐ | — | — | | Text parser | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | — | ⭐⭐⭐ | | Text parser | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | — | ⭐⭐⭐ | | Text + dialect detect | ⭐⭐⭐⭐ | ⭐⭐⭐ | — | ⭐⭐⭐ | | Text parser | ⭐⭐⭐ | ⭐⭐⭐ | — | ⭐⭐⭐ |

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

| Framework | Additional Capabilities | | ----------- | --------------------------------------------------------------------------------------------------- | | Angular | Components, directives, pipes, services, modules, DI hierarchy, template bindings | | NgRx | Actions, reducers, effects, selectors, feature states, action creators | | React | JSX/TSX, functional/class components, hooks (useState, useEffect, useMemo, useCallback, useContext) |

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:

| Section | Parameter | Default | Description | | --------------- | -------------------------- | --------- | ------------------------------------------ | | logging | level | info | Log level: debug, info, warn, error | | | maxFiles | 5 | Number of log files for rotation | | database | mode | WAL | SQLite journal mode: WAL, DELETE, TRUNCATE | | | cacheSize | 10000 | SQLite cache size | | indexing | autoSwitchOnBranchChange | true | Auto-switch DB on branch change | | | maxBranchesPerRepo | 10 | Max branches per repository | | | incrementalThreshold | 20 | File threshold for full reindexing | | git | enabled | true | Git integration | | | autoReindex | true | Auto-index on branch change | | | debounceMs | 60000 | Delay before indexing changes | | parser | maxFileSize | 1048576 | Max file size (1MB) | | | timeout | 60000 | Parsing timeout (60 sec) | | performance | maxWorkerThreads | 4 | Parallel parsing workers |

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 [email protected]