codedb

Большой репозиторий. Маленькая карта. Найди важный код.

Интеллектуальный анализ кода для твоего агента программирования. Написан на Zig. Подключается через MCP.

Установка · Быстрый старт · Инструменты · Тесты производительности · Данные и приватность · Познакомьтесь с семьёй ↗

Твой агент имеет задачу. Где-то в твоём репозитории находится нужное определение, вызывающий код, который его объясняет, и тест, который держит его в чести. codedb рисует карту: фокусированный контекст исходного кода, символы, вызывающие стороны, структуры файлов и зависимости. Твой клиент для программирования использует свои нативные инструменты для внесения изменений.

Движок контекста, а не редактор. У codedb нет возможности редактирования. Используй его с Graff, Claude Code, Codex, Gemini CLI, Cursor, Windsurf, Devin или другим MCP-клиентом.

🧭 Дай своему агенту компас

Структурный поиск выполняется локально. По умолчанию гибридный поиск также использует хостинговые эмбеддинги; выбери semantic=local для полностью локального поиска. Подробнее см. в разделе Данные и приватность — что отправляется и хранится в каждом режиме.

⚡ Установка

macOS и Linux

curl -fsSL https://codedb.codegraff.com/install.sh | bash

Скачивает бинарник для твоей платформы и автоматически регистрирует codedb как MCP-сервер в Claude Code, Codex, Gemini CLI, Cursor, Windsurf и Devin — каждый записывается напрямую и аддитивно в конфиг соответствующего инструмента (только если инструмент присутствует). Установщик выводит точную команду codedb mcp, которую он зарегистрировал, а также указатели по настройке хуков для Codex и Claude Code.

В Windows запускай эту команду внутри WSL только если хочешь Linux-бинарник внутри WSL. Для нативного Windows-бинарника используй PowerShell ниже.

Windows

Запусти в PowerShell:

irm https://raw.githubusercontent.com/justrach/codedb/v0.2.5841/install/install.ps1 | iex

Запусти ту же команду снова, чтобы обновить codedb.

npm/npx на macOS и Linux

npx -y codedeebee mcp

Или установи глобально:

npm install -g codedeebee
codedb mcp

npm-пакет называется codedeebee (имя codedb занято на npm); он поставляется с тонким лаунчером, который при postinstall скачивает соответствующий нативный бинарник из GitHub Releases и проверяет контрольную сумму SHA256. Установленный CLI по-прежнему называется codedb.

Лаунчер уже умеет забирать codedb-windows-x86_64.exe, но текущий опубликованный codedeebee вышел до появления этого ассета, поэтому npx -y codedeebee mcp пока не работает на Windows — станет доступно со следующим релизом. До этого используйте PowerShell-установщик выше.

Удобно для MCP-клиентов (Claude Code, Cursor, opencode, Claude Desktop), которые уже используют npx:

{
  "codedb": {
    "type": "local",
    "command": ["npx", "-y", "codedeebee"],
    "args": ["mcp"],
    "enabled": true
  }
}

Обновление или восстановление старой установки

На macOS или Linux, если codedb update падает на старом релизе, запустите установщик повторно:

curl -fsSL https://codedb.codegraff.com/install.sh | bash

Это заменит бинарник codedb на последний GitHub Release и сохранит ваши существующие MCP-регистрации, конфиг, кэши и снэпшоты. Используйте этот путь для любых релизов, чей встроенный апдейтер не может получить контрольные суммы релизов.

Самообновление работает на нативном Windows с 0.2.5833 (codedb update). На старых сборках запустите PowerShell-установщик выше, чтобы обновить или восстановить бинарник.

🌱 Статус проекта

Alpha: API и форматы снэпшотов могут меняться. Ядро говорит JSON-RPC 2.0 через stdio, с опциональным локальным HTTP-сервером.

• Парсеры: Zig, C/C++, Python, TypeScript/JavaScript, Rust, Go, PHP, Ruby, HCL, R, Dart/Flutter и OCaml; для других языков есть лёгкие контуры.
• Навигация: контекст задачи, определения символов, вызовы, графы зависимостей, триграммный поиск и переносимые снэпшоты.
• Живые обновления: ограниченные системные ватчеры с периодической верификацией контента при переполнении. Каждый MCP-процесс владеет своим ватчером; несколько клиентов могут умножать фоновую работу.
• Распространение: бинарники для macOS, Linux и Windows; скачивание с проверкой SHA256. Релизы macOS подписаны и нотаризованы.

Документация

• Настройка MCP — конфигурации для каждого клиента (Claude Desktop, Cursor, VS Code, Claude Code, Codex CLI, Gemini CLI), разрешение корня, устранение неполадок
• База скиллов и контекстные файлы — agents.md / CLAUDE.md / GEMINI.md, .codedbrc, память разработчика
• Справочник CLI — каждая команда, каждый флаг
• Архитектура — внутренности движка, структура индекса
• Бенчмарки — микробенчмарки + результаты agentic-eval против codegraph, FTS5, lean-ctx
• Raspberry Pi 4 — полноценная настройка ARM64, сборка под Cortex-A72 и бенчмарк на устройстве
• Руководство по миграции на Zig 0.17.0-dev — повторяемый workflow через zigup и рецепты изменений API

Или установите вручную из GitHub Releases. Всегда сверяйте бинарник с прилагаемым checksums.sha256 перед запуском.

⚡ Быстрый старт

Как MCP-сервер (рекомендуется)

Шелл-установщик для macOS/Linux регистрирует codedb автоматически. Для npm/npx-установок на macOS/Linux и ручных установок на Windows используйте MCP-конфигурацию выше или примеры для конкретных клиентов в docs/mcp.md. Затем откройте проект — инструменты codedb станут доступны вашему ИИ-агенту.

# Manual MCP start (auto-configured by install script)
codedb mcp /path/to/your/project

Для клиентов, которые открывают много неиспользуемых MCP-сессий (например, по одной на ворктри),

Попробуйте экспериментальный ленивый запуск MCP с CODEDB_LAZY_MCP=1. Индексация начинается при первом запросе кода; неленивый запуск остаётся значением по умолчанию.

Как HTTP-сервер

codedb serve /path/to/your/project
# listening on localhost:7719

CLI

codedb tree /path/to/project          # file tree with symbol counts
codedb outline src/main.zig           # symbols in a file
codedb find AgentRegistry             # find symbol definitions
codedb search "handleAuth"            # full-text search (trigram-accelerated)
codedb word Store                     # exact word lookup (inverted index, O(1))
codedb hot                            # recently modified files

🔧 MCP-инструменты

Инструменты через Model Context Protocol (JSON-RPC 2.0 через stdio). Агенты по умолчанию видят пять одноразовых инструментов (context, explain, callpath, list_dir, status). Задача codedb — давать агентам контекст — а не быть вашим редактором. У codedb нет инструмента редактирования; используйте нативные инструменты редактирования вашего клиента.

codedb_context принимает max_tokens как консервативный приблизительный бюджет ответа. Компактные доказательства допускаются постепенно; когда оставшиеся доказательства не помещаются, ответ сообщает об опущении один раз вместо переполнения запроса секциями с более низким приоритетом.

MCP-ответы — обычный текст по умолчанию, без ANSI-стилизации. Установите CODEDB_MCP_ANSI=1 в окружении MCP-сервера для включения ANSI-цветных блоков сводки и руководства для клиентов, рендерящих терминальные цвета.

Профиль инструментов: агенты по умолчанию используют mini — пять одноразовых инструментов (context, explain, callpath, list_dir, status). Инструменты-прыжки остаются вызываемыми; они не афишируются. CODEDB_TOOLS_PROFILE=core — старый набор из 10 навигационных инструментов; slim — лаконичные шесть прыжков; full афиширует всё. GUI-клиенты, излучающие богатые блоки, всё равно получают full, если не задана переменная окружения.

Публичные репозитории — DeepWiki (удалённый MCP)

codedb индексирует ваш проверенный код. Для вопросов о публичных репозиториях GitHub установщик регистрирует DeepWiki (https://mcp.deepwiki.com/mcp — бесплатно, без авторизации) как отдельный удалённый MCP-сервер в каждом обнаруженном клиенте, с инструментами read_wiki_structure, read_wiki_contents и ask_question. Отказаться можно при установке через CODEDB_INSTALL_DEEPWIKI=0. (Старый инструмент codedb_remote, работавший на api.wiki.codes, был удалён; DeepWiki заменяет его роль.)

Команды CLI

Опции: --no-telemetry (или переменная окружения CODEDB_NO_TELEMETRY)

Отказ от хука Claude Code: установщик регистрирует PreToolUse-хук, который подталкивает агентов от grep/cat к codedb внутри индексируемых репозиториев. CODEDB_NO_HOOKS=1 пропускает его только для этого запуска (это значение никогда не сохраняется из окружения, поэтому временный export не может быть повышен до постоянного отказа фоновым автообновлятором). Чтобы сделать это постоянным, запустите установщик с CODEDB_PERSIST_NO_HOOKS=1 или выполните touch ~/.codedb/no-hooks; rm ~/.codedb/no-hooks снова включит хук. Удаление записи хука из ~/.claude/settings.json также работает навсегда — установщик запоминает свои регистрации и считает отсутствующую запись намеренным удалением (он сам создаст ~/.codedb/no-hooks, поэтому удалите этот файл, чтобы отменить).

Пример: агент исследует кодовую базу

# 1. Get the file tree
curl localhost:7719/tree
# → src/main.zig      (zig, 55L, 4 symbols)
#   src/store.zig     (zig, 156L, 12 symbols)
#   src/agent.zig     (zig, 135L, 8 symbols)

# 2. Drill into a file
curl "localhost:7719/outline?path=src/store.zig"
# → L20: struct_def Store
#   L30: function init
#   L55: function recordSnapshot

# 3. Find a symbol across the codebase
curl "localhost:7719/symbol?name=AgentRegistry"
# → {"path":"src/agent.zig","line":30,"kind":"struct_def"}

# 4. Full-text search
curl "localhost:7719/search?q=handleAuth&max=10"

# 5. Check what changed
curl "localhost:7719/changes?since=42"

📊 Бенчмарки

Замеры на Apple M4 Pro, 48 ГБ ОЗУ. MCP = предварительно проиндексированные «тёплые» запросы (среднее по 20 итерациям). CLI/внешние инструменты включают запуск процесса (среднее по 3 итерациям). Истинность проверена против эталонной реализации на Python.

Латентность — codedb MCP vs codedb CLI vs ast-grep vs ripgrep vs grep

Репозиторий codedb (20 файлов, 12,6 тыс. строк):

Репозиторий merjs (100 файлов, 17,3 тыс. строк):

rtk-ai/rtk repo (329 файлов) — codedb vs rtk vs ripgrep vs grep:

Эффективность токенов

codedb возвращает структурированные, релевантные результаты — не сырой дамп строк. Для ИИ-агентов это означает драматически меньше токенов на запрос:

Скорость индексации

codedb v0.2.57 использует параллельное сканирование с локальными воркерами и детерминированное слияние — каждый воркер строит свой частичный индекс, затем результаты объединяются в главном потоке:

Индексы строятся при запуске, а вотчер поддерживает их в актуальном состоянии. Историческое время индексации одного файла выше исключает объединение событий, задержку опроса и постановку в очередь. Индексированные запросы переиспользуют индекс; живой листинг и резервное чтение могут обращаться к файловой системе. Для репозиториев >1000 файлов содержимое файлов освобождается после индексации для экономии ~300-500 МБ.

Исторические фоновые замеры (openclaw, 6 315 файлов, Apple M4 Pro)

Вотчер проверяет mtime .git/HEAD перед форком git rev-parse HEAD. Эти исторические замеры не ограничивают CPU вотчера при активности файловой системы; см. воспроизведение issue #748.

Почему codedb быстрый

• MCP-сервер индексирует один раз при запуске → все запросы попадают в in-memory структуры данных (O(1) хеш-лукапы)
• CLI платит ~55 мс за запуск процесса + полное сканирование ФС при каждом вызове
• ast-grep перепарсивает все файлы через tree-sitter при каждом вызове (~3 мс)
• ripgrep/grep брутфорсно сканируют каждый файл при каждом вызове (~5-7 мс)
• Преимущество MCP: индексируй один раз, запрашивай тысячи раз с подмиллисекундной латентностью

Матрица функций

Карта для следующего шага: структурные парсеры, поисковые индексы и граф зависимостей в одном Zig-бинарнике.

🏗️ Архитектура

┌─────────────┐     ┌─────────────┐
│  HTTP :7719 │     │  MCP stdio  │
│  server.zig │     │  mcp.zig    │
└──────┬──────┘     └──────┬──────┘
       │                   │
       └───────┬───────────┘
               │
    ┌──────────▼──────────┐
    │     Explorer        │
    │   explore.zig       │
    │  ┌───────────────┐  │
    │  │ WordIndex      │  │
    │  │ TrigramIndex   │  │
    │  │ Outlines       │  │
    │  │ Contents       │  │
    │  │ DepGraph       │  │
    │  └───────────────┘  │
    └──────────┬──────────┘
               │
    ┌──────────▼──────────┐
    │      Store          │──── data.log
    │    store.zig        │
    └──────────┬──────────┘
               │
    ┌──────────▼──────────┐
    │     Watcher         │ ← OS events + overflow polling
    │   watcher.zig       │
    │  (FilteredWalker)   │
    └─────────────────────┘

Никакого SQLite. Никаких зависимостей. Специализированная модель данных:

• Explorer — движок структурного индекса. Парсит Zig, Python, TypeScript/JavaScript, Rust, Go, PHP, Ruby, HCL, R и Dart. Поддерживает контуры, триграмматический индекс, инвертированный словесный индекс, кэш содержимого и граф зависимостей за одним мьютексом.

• Store — append-only журнал версий. Каждое записанное изменение файла (снимок, модификация, удаление) получает монотонно увеличивающийся порядковый номер. История версий ограничена 100 на файл.
• Watcher — ограниченные OS-наблюдатели, объединение событий за 100мс и проверка содержимого для переполнения примерно каждые 2с. FilteredWalker отсекает .git, node_modules, zig-cache, __pycache__ и т.д. перед погружением.
• Agents — полноценные структуры с курсорами, хартбитами и эксклюзивными файловыми блокировками. Устаревшие агенты собираются через 30с.

Модель потоков

Все потоки используют общий shutdown: atomic.Value(bool) для graceful-завершения.

🔒 Данные и приватность

codedb собирает анонимную телеметрию использования для улучшения инструмента. Телеметрия включена по умолчанию — пишется в ~/.codedb/telemetry.ndjson и периодически синхронизируется с эндпоинтом аналитики codedb. Исходный код, содержимое файлов, пути файлов или поисковые запросы НЕ собираются — только агрегированные счётчики вызовов инструментов, задержки и статистику запуска.

codedb_context по умолчанию использует гибридный поиск по Парето-фронтиеру. Локальный BM25, триграммы, символы и графовый поиск всегда выполняются первыми. Передайте semantic=local для полностью локального вызова, который не отправляет запрос или исходный текст в сервис эмбеддингов. В режиме гибрида по умолчанию:

• локальный BM25/символьный поиск всё равно выполняется первым и остаётся безопасной fallback-результирующей базой;
• при наличии свежего локального OpenPuffer sidecar codedb отправляет задачу плюс фиксированную публичную калибровочную строку в одном запросе эмбеддинга, проверяет, что провайдер всё ещё представляет то же векторное пространство, и ищет сохранённые чанки кода локально через проверенный mmap-backed граф;
• без sidecar codedb отправляет задачу плюс не более 24 локально выбранных относительных путей и ограниченных сниппетов, лимитированных 2 KiB на элемент путь+сниппет / 8 KiB общий объём кандидат-текста, в одной партии exact-rerank;
• хостинговый сервис эмбеддингов codedb выполняет временный inference и не сохраняет тела запросов, пути кандидатов, исходные сниппеты или векторы;
• серверный архив репозитория или серверный репозиторий/векторный индекс НЕ создаются;
• сбой провайдера/сети сохраняет локальный результат и никогда не вызывает CPU-эмбеддинг fallback.

Явно соберите новый локальный ANN:

codedb /path/to/repo semantic-index

CodeDB 0.2.5851 стадировал управляемую миграцию эмбеддингов без ломки старых клиентов. Версии до 0.2.5850 продолжают запрашивать Qwen/Qwen3-Embedding-0.6B; 0.2.5851 и позже запрашивают jinaai/jina-embeddings-v2-base-code. Сервис держит оба роута активными. Существующий Qwen ANN sidecar отклоняется проверкой модели/векторного пространства нового клиента. Начиная с 0.2.5852, первый гибридный MCP-запрос всё равно возвращается через ограниченный exact Jina reranker, затем планирует один фоновый ребилд именно этого legacy hosted-Qwen sidecar. Старое поколение OpenPuffer остаётся нетронутым до тех пор, пока Jina-замена не пройдёт валидацию исходников, Git, метаданных и векторного пространства и не закоммитится атомарно. Кастомные эндпоинты/переопределения моделей и новые репозитории никогда не авто-строятся; установите CODEDB_NO_AUTO_SEMANTIC_MIGRATION=1 чтобы отключить даже эту legacy-миграцию. CodeDB никогда не смешивает векторы от двух моделей.

Оно разбивает уже индексируемые файлы на ограниченные 832-байтовые чанки исходников, использует по умолчанию четыре параллельных запроса по 25 элементов (явно настраиваемых от одного до восьми), и пишет небольшую маппинг-таблицу semantic-chunks-v3.meta плюс generation-named .hmls mmap-слой только в локальную per-project директорию данных codedb. Директория и файлы используют приватные права (0700/0600 на POSIX). При lookup codedb проверяет идентичность модели/векторного пространства, Git/содержимое на свежесть и ограниченные метаданные перед открытием слоя. Куча метаданных ограничена 64 MiB, чтения валидации графа — 128 MiB; векторные слои остаются demand-paged вместо копирования в процесс запроса. Оно никогда не сканирует и не загружает .env, .env.*, .envrc, креды, приватные ключи или другие пути из denylist чувствительных файлов. Обычная лексикальная индексация не строит этот sidecar.

Дефолтный управляемый семантический lane бесплатен для вызовов и не требует API-токена или ручной настройки. При первом использовании CodeDB создаёт локальный Ed25519 installation key,

зарегистрирует свой публичный ключ и получит кратковременный сертификат, подписанный сервером. Каждый запрос подтверждает владение ключом установки; продление происходит автоматически. Приватный сид хранится в глобальном файле ~/.codedb/credentials.json, записываемом атомарно с режимом 0600 в POSIX, и никогда не является частью запроса эмбеддингов. Публичный маршрут предоставляет только управляемую дорожку CodeDB и обеспечивает регистрацию, установку и совокупные сетевые лимиты. Общие API провайдеров остаются аутентифицированными.

format=json раскрывает эту границу в объекте retrieval, включая размерность векторов, ограниченные количество байт/документов, политику удержания и политику отказа. Если CODEDB_EMBEDDINGS_URL указывает на пользовательского провайдера, codedb помечает его удержание как custom_endpoint_unverified, потому что клиент не может доказать политику хранения другого оператора.

Не хранится: В явном режиме semantic=local исходный код никуда не отправляется. В режиме гибридного по умолчанию и в явном режиме построения индекса только ограниченные временные батчи выше покидают машину; управляемый сервис их не хранит и никогда не создаёт индекс репозитория. Опциональные ANN-векторы и граф остаются в локальном каталоге данных codedb. Ни содержимое файлов, ни пути к файлам, ни поисковые запросы не собираются в телеметрию. Чувствительные файлы автоматически исключаются из индексации и поэтому не могут стать гибридными кандидатами (.env, .env.*, .envrc, credentials.json, secrets.*, .pem, .key, SSH-ключи, AWS-конфиги). Конструктор гибридного запроса повторяет каноническую проверку безопасных путей непосредственно перед сериализацией, поэтому эти пути остаются заблокированными даже если устаревший или вручную собранный индекс в памяти содержит один из них. Структурированные отчёты об источнике сообщают только общее число sensitive_paths_blocked, никогда не раскрывая отклонённый путь.

Опциональные переопределения пользовательского провайдера (управляемая дорожка не требует никаких):

CODEDB_EMBEDDINGS_URL=https://provider.example/v1/embeddings
CODEDB_EMBEDDINGS_MODEL=your-deployment-id
CODEDB_EMBEDDINGS_DIMENSIONS=512
CODEDB_EMBEDDINGS_TOKEN='optional bearer token for a protected/custom endpoint'
CODEDB_EMBEDDINGS_TIMEOUT_MS=15000
CODEDB_SEMANTIC_INDEX_CONCURRENCY=4

Для отключения телеметрии: установите CODEDB_NO_TELEMETRY=1 или передайте --no-telemetry.

Для синхронизации локального NDJSON-файла в Postgres для анализа или дашбордов используйте scripts/sync-telemetry.py со схемой в docs/telemetry/postgres-schema.sql. Поток данных задокументирован в docs/telemetry.md.

codedb nuke                # uninstall binary, clear caches/snapshots, remove MCP registrations
rm -rf ~/.codedb/          # cache-only cleanup if you want to keep the binary installed
rm -f codedb.snapshot      # remove snapshot from current project only

🔨 Сборка из исходников

Требования: Zig 0.17.0-dev.813+2153f8143 (точный протестированный снимок разработки). См. руководство по миграции для воспроизводимой настройки zigup.

git clone https://github.com/justrach/codedb.git
cd codedb
zig build                              # debug build
zig build -Doptimize=ReleaseFast       # release build
zig build test                         # run tests
zig build bench                        # run benchmarks

Бинарник: zig-out/bin/codedb

Кросс-компиляция

zig build -Doptimize=ReleaseFast -Dtarget=x86_64-linux
zig build -Doptimize=ReleaseFast -Dtarget=aarch64-linux
zig build -Doptimize=ReleaseFast -Dtarget=x86_64-macos
zig build -Doptimize=ReleaseFast -Dtarget=x86_64-windows

Релизинг

./release.sh 0.2.0              # build, codesign, notarize, upload to GitHub Releases
./release.sh 0.2.0 --dry-run    # preview without executing

Лицензия

См. LICENSE для подробностей.