# Octocode: инструмент продуктивности для разработчиков, который заменил нам grep

> Семантический поисковый движок по коду, MCP-инструмент и AI-инструмент для продуктивности разработчиков в одном Rust-бинарнике. Как мы его построили и почему используем каждый день.

Вы только что присоединились к проекту с 400 000 строк кода в 12 000 файлов. Кто-то просит вас починить поток аутентификации. Вы делаете `grep -r "auth"` и получаете 847 результатов. Половина — комментарии. Треть — тестовые файлы. Ни один не говорит вам, _как на самом деле работает аутентификация_.

Это была проблема, в которую мы постоянно упирались. И именно поэтому мы построили Octocode.

Octocode — это инструмент продуктивности для разработчиков, написанный на Rust: семантический поиск по коду, MCP-сервер и AI-инструментарий в одном бинарнике. Вы спрашиваете его «как работает аутентификация пользователей?» простым английским, и он возвращает 3-5 файлов, которые действительно имеют значение, с контекстом о том, как они связаны. Работает локально, функционирует как MCP-инструмент для Claude и Cursor, и превращает вашу кодовую базу в граф знаний с возможностью запросов.

Мы используем его каждый день. Это инструмент, благодаря которому [Octomind](https://octomind.run) — наш рантайм AI-агентов — создаётся и выпускается на скорости командой из двух человек. Это наше секретное оружие. И он с открытым исходным кодом.

Мы только что выпустили v0.13.0 с поиском по коммитам, AI-дифами, автоматическими релизами, объяснением кода и векторной компрессией RaBitQ. Вот полная картина.

## Боль, с которой всё началось

Мы создаём много программного обеспечения. Множество репозиториев, множество языков, проекты, которые тянутся годами. Проблема была не в написании кода, а в его поиске. Понять, что уже существует, прежде чем писать что-то новое.

`grep` быстрый, но тупой. Он находит строки, а не смысл. Поиск GitHub медленный и ограничен публичными репозиториями. ChatGPT теряет контекст после 128К токенов. Каждый раз, когда мы заходили в старый проект, мы тратили часы на повторное чтение файлов, которые читали полгода назад.

Вопрос был прост: что, если поиск по коду работал бы так, как работает ваш мозг? Вы не думаете «найди мне строку `authenticate`» — вы думаете «как работает логин?». Инструмент должен понимать эту разницу.

Так что мы построили такой.

![grep vs поиск octocode](/blog/octocode-semantic-code-search/grep-vs-semantic.svg)

## Что делает Octocode

В своей основе Octocode делает четыре вещи:

**1. Семантический поиск** — Задавайте вопросы на естественном английском. Он преобразует ваш запрос в векторный эмбеддинг, сравнивает его с эмбеддингами каждого фрагмента кода в вашем проекте и возвращает наиболее семантически релевантные результаты. Не совпадения ключевых слов — совпадения смысла.

**2. Анализ структуры кода** — Извлечение сигнатур функций, определений классов и интерфейсов модулей из любого файла или glob-шаблона. Понять, что делает файл, не читая каждую строку.

**3. Графы знаний (GraphRAG)** — Картирование связей между файлами: кто что импортирует, какие модули являются соседними, как данные текут через систему. Спросите «как файл A связан с файлом B?» и получите реальный ответ.

**4. AI-инструменты для разработчиков** — Семантические дифы, автоматизированный код-ревью, умные commit-сообщения, объяснение кодовой базы и многоязычное управление релизами. Не отдельные инструменты, прикрученные сбоку — они построены на том же движке индексации и поиска.

Всё это выставлено как MCP-сервер — это означает, что Claude, Cursor, Windsurf или любой совместимый с MCP AI-ассистент может использовать его напрямую. Ваш AI перестаёт гадать о вашей кодовой базе и начинает её знать.

## Как мы реально его используем

Прежде чем углубляться в функции — это не инструмент, который мы построили и забыли. Мы используем Octocode ежедневно для создания [Octomind](https://octomind.run), нашей рантайма AI-агентов.

Вот как выглядит наш типичный день:

- Утро: `octocode diff --staged` для просмотра того, что Ava (наша AI-коллаборатор) выпустила за ночь. Не 200 строк дифа — краткая сводка типа «Добавлена логика повторных попыток в транспортный слой MCP, отрефакторена обработка ошибок в 3 файлах».
- Перед PR: `octocode review --staged --focus security` ловит вещи, которые мы бы пропустили. Случайно удалённые рейт-лимитеры. Векторы SQL-инъекций. Небезопасные unwrap в Rust.
- Время коммита: `octocode commit` генерирует сообщения из реального дифа. Никаких больше коммитов «fix stuff».
- Релизы: `octocode release` читает каждый коммит с последнего тега, решает по бампу версии, генерирует чейнджлог и обновляет файлы версий в Cargo.toml, package.json или что бы ваш проект ни использовал.
- Весь день: Claude Code использует Octocode как свой MCP-сервер. Когда мы спрашиваем «как работает пайплайн эмбеддингов?», Claude ищет в реальном коде, читает его и отвечает. Никаких галлюцинаций.

Это рабочий процесс, который позволяет двум людям и одному AI выпускать продукт как намного более крупная команда.

## CLI: AI-инструменты для продуктивности разработчиков

Octocode начался как MCP-инструмент. Но чем больше мы его использовали, тем больше понимали: этой штуке нужно работать и автономно. Не всё происходит внутри AI-чата.

### `octocode search` — семантический поиск из вашего терминала

```bash
# Одиночный запрос
octocode search "how is user authentication implemented"

# Мульти-запрос для тщательных результатов
octocode search "auth middleware" "JWT token validation" "session management"

# Поиск по конкретным типам контента
octocode search "database migration" --mode code
octocode search "why did we change the API" --mode commits

# Контроль детализации вывода
octocode search "auth" --detail-level full
```

Мульти-запрос — это убойная функция здесь. Вместо одного поиска в надежде поймать всё, вы запускаете 3-4 связанных запроса и получаете результаты, охватывающие полную картину. Движок дедуплицирует и переранжирует по всем запросам.

Уровни детализации позволяют вам контролировать, сколько кода возвращается: `signatures` для быстрого сканирования, `partial` (по умолчанию) для умного усечения или `full` для всего.

### `octocode view` — сигнатуры без шума

```bash
# Просмотреть все сигнатуры функций Rust
octocode view "src/**/*.rs"

# Проверить интерфейс конкретного модуля
octocode view "src/api/*.ts" --md

# Несколько языков сразу
octocode view "**/*.{rs,ts,py}"
```

Это одна из тех функций, которая звучит просто, но экономит реальное время. Вы ревьюите PR, который касается 8 файлов. Вместо открытия каждого и прокрутки, вы запускаете `octocode view` с глобом и получаете каждую сигнатуру функции, определение структуры и экспорт типа в одном выводе. Markdown-режим (`--md`) делает его удобным для вставки.

Мы активно используем это и в MCP-сервере — когда Claude нужно понять интерфейс модуля перед его редактированием, `view_signatures` даёт ему структуру без сброса 2000 строк реализации.

### `octocode diff` — сводка, а не патч

Это новое в v0.13. И это изменило то, как мы ревьюим код, сгенерированный AI.

```bash
# Что изменилось в моей области staging?
octocode diff --staged

# Что произошло между ветками?
octocode diff main..feature-branch

# Фокус на конкретных аспектах
octocode diff --staged --focus security
octocode diff --staged --focus performance
```

Вот почему это важно сейчас как никогда. AI-инструменты для кодинга генерируют большие дифы. Одна сессия Claude может затронуть 15 файлов на 400 строк. Чтение этого сырого дифа занимает 20 минут. `octocode diff` читает его за секунды и даёт вам сводку: что изменилось, почему это важно, на что обратить внимание.

Флаг `--focus` острый. Передайте `security`, и он отметит удалённые валидации, открытые эндпоинты, захардкоженные секреты. Передайте `performance`, и он подсветит новые аллокации, блокирующие вызовы, отсутствующие индексы. Мы запускаем оба перед каждым мерджем.

### `octocode explain` — понять что угодно

```bash
# Объяснить конкретный файл
octocode explain src/auth/middleware.rs

# Объяснить концепцию по всей кодовой базе
octocode explain "how does the embedding pipeline work"
```

Наведите его на файл и получите структурированный разбор: что он делает, от чего зависит, что зависит от него. Наведите на концепцию, и он ищет семантически, затем синтезирует результаты в объяснение. Отлично для онбординга в незнакомые части кодовой базы.

### `octocode review` — ловит то, что люди упускают

```bash
octocode review --staged
octocode review --focus security --severity high
```

Не замена человеческому ревью. Но он стабильно ловит вещи, которые мы бы пропустили: неиспользуемые импорты, непоследовательная обработка ошибок, потенциальные гонки данных, проблемы безопасности. Мы теперь запускаем его перед каждым PR. Фильтр серьёзности не даёт ему быть шумным.

### `octocode commit` — commit-сообщения, которые что-то значат

```bash
git add .
octocode commit
octocode commit --yes  # пропустить подтверждение
```

Анализирует staged-изменения, генерирует commit-сообщение, которое реально описывает то, что произошло. Не «update files», а что-то вроде «refactor: extract embedding batch processing into standalone pipeline with retry logic». Мелочь, но она набирается, когда вы делаете 20 коммитов в день.

### `octocode release` — автоматизированные многоязычные релизы

```bash
octocode release
octocode release --dry-run
octocode release --force-version "2.0.0"
```

Этот скрытый чемпион. Он читает каждый коммит с последнего git-тега, использует LLM для определения правильного бампа версии (patch, minor или major), генерирует структурированный чейнджлог и обновляет файлы версий.

Многоязычная часть имеет значение: он обрабатывает Cargo.toml (Rust), package.json (Node), composer.json (PHP), pyproject.toml (Python) и go.mod (Go). Если ваш проект использует несколько языков, он обновляет их все.

Мы используем это для каждого релиза самого Octocode. [Чейнджлог v0.13](https://github.com/Muvon/octocode/blob/master/CHANGELOG.md) — с его категоризированными функциями, улучшениями и исправлениями багов — был сгенерирован `octocode release`.

### `octocode stats` — быстрая проверка пульса

```bash
octocode stats
octocode stats --format json
```

Количество файлов по языкам, количество строк, статус индексации. Полезно для CI-дашбордов или просто чтобы ответить «насколько большой этот проект?»

## Как работает индексация

![Пайплайн индексации Octocode](/blog/octocode-semantic-code-search/pipeline.svg)

Когда вы запускаете `octocode index`, вот что происходит под капотом:

1. **Обнаружение файлов** — обходит репозиторий, уважает `.gitignore` и `.noindex`, обрабатывает симлинки
2. **AST-парсинг** — Tree-sitter парсит каждый файл в абстрактное синтаксическое дерево. Так Octocode понимает структуру кода — функции, классы, импорты, экспорты — а не просто текст
3. **Чанкинг** — код разбивается на семантические чанки (настраиваемо, по умолчанию 2000 байт с перекрытием)
4. **Эмбеддинг** — каждый чанк преобразуется в векторный эмбеддинг через выбранного вами провайдера
5. **Хранение** — векторы идут в LanceDB с опциональной квантизацией RaBitQ (~32x компрессия)
6. **GraphRAG** — связи между файлами извлекаются и хранятся как граф знаний

Весь пайплайн инкрементален. Измените один файл, и только этот файл переиндексируется. Переключите ветки, и Octocode отслеживает, что нужно обновить. Это новая дельта-индексация с учётом веток в v0.13.

### Провайдеры эмбеддингов

Вы выбираете свой:

**Облако** (требуется API-ключ):

- **Voyage AI** — лучшее качество для кода, 200М бесплатных токенов/месяц (наш дефолт)
- **Jina AI** — сильные эмбеддинги кода
- **Google AI** — gemini-embedding-001
- **OpenAI** — text-embedding-3-small/large
- **Together AI** — распределённый

**Локально** (без API, без сети):

- **FastEmbed** — самый быстрый, 384-мерный (macOS)
- **HuggingFace** — CodeBERT, sentence-transformers (macOS)

Одна деталь, которая имеет значение: Octocode использует **асимметричный поиск**. Эмбеддинги кода и эмбеддинги запросов генерируются по-разному, потому что «как работает аутентификация?» и `fn authenticate(token: &str)` семантически связаны, но структурно различны. Это значимое улучшение точности по сравнению с инструментами, которые эмбеддят всё одинаково.

### Квантизация RaBitQ (новое в v0.13)

Векторы большие. Эмбеддинг float32 на 1024 измерения — это 4КБ на чанк. Умножьте на тысячи чанков, и хранилище набирается.

RaBitQ сжимает векторы примерно в 32 раза с минимальной потерей качества. Для большинства кодовых баз вы не заметите разницы в качестве поиска. Но ваш индекс уменьшается со 100МБ до 3МБ. Это важно, когда вы индексируете монорепозиторий.

```bash
octocode config --quantization true
octocode index --force  # переиндексировать с компрессией
```

### Контекстный поиск: улучшение на 49%

Это основано на [исследовании Anthropic по контекстному поиску](https://www.anthropic.com/news/contextual-retrieval) — техника, которая снижает неудачи поиска на 49%, а в сочетании с переранжированием — на 67%. Мы реализовали оба в Octocode.

Проблема с сырыми эмбеддингами кода: функция с именем `process()` ничего не значит в векторном пространстве. Она обрабатывает платежи? Парсит HTML? Сжимает изображения? Модель эмбеддингов не может сказать только по имени функции.

Octocode решает это на двух уровнях.

**Уровень 1: Структурный контекст (всегда включён).** Каждый чанк получает префикс из пути файла, языка и имён символов перед эмбеддингом. Так модель эмбеддингов видит `# File: src/api/auth.rs / # Language: Rust / # Defines: validate_token, refresh_session` перед собственно кодом. Уже одно это — большое улучшение: эмбеддинг теперь знает, _где_ живёт код и _что_ он определяет.

**Уровень 2: Описания, сгенерированные LLM (опционально).** Когда включено, LLM читает каждый чанк и пишет описание в 1-2 предложения того, что он делает. Промпт специфичен: «напиши, что делает этот код в терминах, которые разработчик стал бы искать». Так `process()` становится «валидирует входящие webhook-payload'ы от Stripe и диспетчеризует их к правильному обработчику платежей».

Это описание добавляется к чанку перед эмбеддингом. Модель эмбеддингов теперь имеет и код, И мост на естественном языке к нему. Этот мост — именно то, что закрывает разрыв между тем, как разработчики ищут («как работают вебхуки?») и тем, как написан код (`fn process(payload: &[u8])`).

```bash
octocode config --contextual-descriptions true
octocode config --contextual-model "openrouter:openai/gpt-4o-mini"
octocode index --force
```

Стоит несколько центов на тысячу чанков с gpt-4o-mini. За скачок в качестве поиска — это не задача.

### Переранжирование: точность после полноты

Векторный поиск хорош в полноте — находит правильные документы в стоге сена. Но точно ранжировать эти результаты? Тут становится размыто. Два результата с похожестью 0.82 и 0.79 могут быть в неправильном порядке.

Octocode использует двухэтапный поисковый пайплайн. Сначала векторный поиск вытаскивает топ-кандидатов (широкая сеть, высокая полнота). Затем cross-encoder переранжировщик переоценивает каждый результат, глядя на полную пару запрос-документ вместе. Не отдельные эмбеддинги — реальная связь между вашим вопросом и каждым чанком кода.

[Исследования показывают](https://app.ailog.fr/en/blog/news/reranking-cross-encoders-study), что переранжирование cross-encoder улучшает точность RAG до 40%. В наших тестах оно стабильно толкает самый релевантный результат на позицию #1 вместо позиции #3 или #4. Разница между «полезно» и «именно то, что вам было нужно».

Переранжировщик работает через [octolib](https://github.com/Muvon/octolib) и поддерживает несколько провайдеров. Он добавляет несколько миллисекунд к латентности поиска. Невидимо для людей. Невидимо для MCP-клиентов.

```bash
# Переранжирование включено по умолчанию, когда настроен провайдер
octocode config --show  # проверить настройки переранжировщика
```

В сочетании с контекстными описаниями это даёт Octocode поисковый пайплайн, ближе к state-of-the-art RAG-системам, чем к традиционным инструментам поиска кода.

## GraphRAG: граф знаний

Это функция, отделяющая Octocode от «семантического grep».

Когда вы включаете GraphRAG, Octocode строит граф, где каждый файл — это узел, а каждая связь — это ребро. Связи включают:

- **imports** — файл A импортирует из файла B
- **sibling_module** — файлы в одной директории
- **parent/child_module** — иерархия директорий

Каждый узел хранит: путь файла, описание, сгенерированное AI, извлечённые символы, списки импортов/экспортов и векторные эмбеддинги.

Что вы можете с этим делать?

```bash
# Найти все файлы, связанные с аутентификацией
octocode graphrag search --query "authentication system"

# Проследить, как связаны два файла
octocode graphrag find-path --source-id src/api/auth.rs --target-id src/db/users.rs

# Получить полную детализацию роли файла
octocode graphrag get-node --node-id src/api/auth.rs

# Увидеть все зависимости для файла
octocode graphrag get-relationships --node-id src/api/auth.rs

# Высокоуровневый обзор кодовой базы
octocode graphrag overview
```

Команда `find-path` недооценена. «Как модуль аутентификации связан с базой данных?» В большом проекте этот путь может проходить через 4-5 промежуточных модулей, о существовании которых вы не знали. GraphRAG его находит.

Разрешение импортов работает и между языками — Rust `use`, Python `import`, TypeScript `import/require`, Go `package`, PHP `use` — всё сопоставлено с реальными путями файлов.

## MCP-инструменты: давая AI глаза в ваш код

Здесь Octocode меняет то, как вы работаете с AI-ассистентами.

Claude, Cursor и Windsurf — все поддерживают MCP. Когда вы подключаете Octocode как MCP-сервер, ваш AI-ассистент получает три инструмента:

| Инструмент        | Что он делает                                                |
| ----------------- | ------------------------------------------------------------ |
| `semantic_search` | Поиск кода, документации, текста или коммитов по смыслу      |
| `view_signatures` | Извлечение структуры из файлов, соответствующих glob-шаблону |
| `graphrag`        | Запрос графа знаний для связей и зависимостей                |

### Настройка

Добавьте в ваш конфиг Claude Desktop или Cursor:

```json
{
	"mcpServers": {
		"octocode": {
			"command": "octocode",
			"args": ["mcp", "--path", "/your/project"]
		}
	}
}
```

Вот и всё. Теперь, когда вы спрашиваете Claude «как работает поток оплаты?» — он не галлюцинирует. Он вызывает `semantic_search`, читает реальный код и даёт вам ответ, основанный на вашей кодовой базе.

### С интеграцией LSP

```bash
octocode mcp --with-lsp "rust-analyzer"
```

Это добавляет ещё 6 инструментов: `goto_definition`, `hover`, `find_references`, `completion`, `document_symbols`, `workspace_symbols`. Ваш AI теперь может двигаться через код так, как это делает ваша IDE — но программно.

### Multi-repo прокси

Работаете с несколькими репозиториями? MCP-прокси автоматически обнаруживает git-репозитории в директории и обслуживает их через единую HTTP-точку:

```bash
octocode mcp-proxy --bind 127.0.0.1:8080 --path /workspace
```

## Производительность

Цифры важнее утверждений. Вот что мы видим на реальных проектах:

| Метрика             | Малый (<1К файлов) | Средний (1-10К) | Большой (10К+) |
| ------------------- | ------------------ | --------------- | -------------- |
| Скорость индексации | 500+ файлов/сек    | 200-400/сек     | 100-200/сек    |
| Латентность поиска  | <50мс              | <100мс          | <200мс         |
| Память              | 50-100МБ           | 100-500МБ       | 500МБ-2ГБ      |
| Хранение (с RaBitQ) | ~300КБ             | ~3МБ            | ~30МБ          |

Латентность поиска — это то, что важно для MCP. Когда Claude вызывает `semantic_search`, вы не хотите ждать 5 секунд. Менее 100мс означает, что AI ощущается мгновенным.

Индексация одноразовая (плюс инкрементные обновления). Даже проект на 10К файлов индексируется менее чем за минуту.

## 14 языков, один инструмент

Octocode использует Tree-sitter для парсинга, что означает реальный AST-анализ — а не regex-хаки. В настоящее время поддерживается:

Rust, Python, TypeScript, JavaScript, Go, PHP, C++, Ruby, Java, Bash, CSS/SCSS, Lua, Svelte, JSON, Markdown.

Каждый язык получает правильное разрешение импортов, извлечение символов и картирование связей. Парсер Go понимает импорты пакетов. Парсер Rust знает про `use` и `mod`. Парсер TypeScript обрабатывает `import` и `require`. Это не «один размер для всех» — каждый парсер языка настроен.

## Что изменилось в v0.13

Это наш самый большой релиз. 35 коммитов. Вот что нового:

- **Поиск по коммитам** — поиск по git-истории по смыслу, с ленивой загрузкой индексации
- **AI CLI команды** — `diff`, `explain`, `stats`, `review`, `commit`, `release`
- **Контекстное обогащение чанков** — техника Contextual Retrieval от Anthropic
- **Квантизация RaBitQ** — ~32x векторная компрессия
- **Провайдеры эмбеддингов OctoHub и Together AI**
- **Дельта-индексация с учётом веток** — более умные инкрементальные обновления
- **Миграция на SDK rmcp** — официальная Rust-реализация MCP для стабильности
- **Улучшенный GraphRAG** — лучшее разрешение узлов и поиск путей
- **7 исправлений багов** — корневые коммиты git, типы эмбеддингов, переранжирование, подсчёт связей

Мы используем Octocode для создания Octocode, поэтому каждая шероховатость ловится быстро.

## Начало работы

### macOS (Homebrew)

```bash
brew install muvon/tap/octocode
```

### Универсальный установочный скрипт

```bash
curl -fsSL https://raw.githubusercontent.com/Muvon/octocode/master/install.sh | sh
```

Работает на macOS (Intel + Apple Silicon), Linux (x86_64 + ARM64) и Windows.

### Из исходников

```bash
cargo install octocode
```

### Первый запуск

Настройте провайдер эмбеддингов (Voyage AI даёт 200М бесплатных токенов/месяц):

```bash
export VOYAGE_API_KEY="your-key"
```

Индексируйте и ищите:

```bash
cd your-project
octocode index
octocode search "how does authentication work"
```

Включите GraphRAG:

```bash
octocode config --graphrag-enabled true
octocode index --force
```

Подключите его к вашему AI-ассистенту как MCP-сервер — см. [руководство по интеграции MCP](https://github.com/Muvon/octocode#mcp-integration) для конфигов Claude, Cursor и Windsurf.

## Настоящая суть

Мы создали Octocode, потому что grep не понимает код. Не потому, что с grep что-то не так — он делает именно то, что говорит. Но «найди строку `auth`» и «покажи мне, как работает аутентификация» — это фундаментально разные вопросы.

Переход от поиска по ключевым словам к семантическому поиску — это не функция. Это смена категории. И с MCP это уже не только для людей — это то, как AI-ассистенты понимают ваш код.

Мы используем его для создания всего в Muvon. Это инструмент, который делает возможной команду из двух человек. И он бесплатный, с открытым исходным кодом, Apache 2.0.

260+ звёзд на GitHub. 14 языков. Один Rust-бинарник. [Попробуйте его](https://github.com/Muvon/octocode).