Как перестать скармливать лишние токены ИИ-агентам при поиске по коду
Знакомая ситуация: вы просите Claude или Cursor найти, где в проекте обрабатываются сессии пользователей, а он в ответ вываливает простыню из десятка файлов, половина из которых вообще не при делах. Или, что еще хуже, агент начинает «галлюцинировать», потому что не смог быстро найти нужный контекст в огромном репозитории. В итоге — потраченное время и раздутые счета за токены.
Недавно я наткнулся на проект cocoindex-code. Это легковесный движок для семантического поиска по коду, который работает локально и, по заверениям авторов, экономит до 70% токенов за счет умной подготовки контекста.
Что это такое и зачем оно в вашем терминале
Если коротко, cocoindex-code — это CLI-инструмент, который индексирует ваш проект, используя абстрактные синтаксические деревья (AST). Вместо того чтобы просто искать по ключевым словам, как старый добрый grep, он понимает структуру кода и его смысл.
Проект построен на базе CocoIndex — высокопроизводительного движка на Rust. Это важно, потому что индексация происходит быстро, а поиск не заставляет кулеры ноутбука взлетать. Инструмент ориентирован на работу с современными AI-агентами (Claude Code, Cursor, Codex), но его можно использовать и просто как продвинутый поиск в терминале.
Чем он отличается от обычного поиска
Главная фишка здесь — сочетание AST и векторных эмбеддингов. Когда вы вводите запрос вроде «логика аутентификации», инструмент не просто ищет слово «auth», а находит куски кода, которые семантически близки к этой теме.
Вот несколько моментов, которые зацепили меня:
- Экономия токенов. Инструмент разбивает код на осмысленные чанки, опираясь на структуру языка. Агенту отправляется только самый релевантный кусок, а не весь файл целиком.
- Нулевая конфигурация. После установки достаточно запустить одну команду, и всё заработает. Не нужно поднимать тяжелые базы данных типа PostgreSQL с расширением pgvector.
- Локальность. Если вы параноик (в хорошем смысле) или просто не хотите платить за API эмбеддингов, можно использовать локальные модели через
sentence-transformers. - Поддержка MCP. Проект работает как сервер Model Context Protocol. Это значит, что его можно подключить к любому приложению, поддерживающему этот стандарт, и ваш ИИ-ассистент получит «суперсилу» поиска по коду.
Как это работает на практике
Установка максимально простая. Если у вас есть uv (а если нет, очень рекомендую попробовать), ставится одной командой:
uv tool install --upgrade 'cocoindex-code[full]'
Версия [full] подтягивает зависимости для локальных эмбеддингов. Если планируете использовать облачные API (OpenAI, Voyage, Gemini), можно ставить облегченную версию без [full].
После установки в корне проекта запускаем:
ccc init
ccc index
Всё, теперь можно искать:
ccc search "как работает валидация форм"
Интересно, что ccc index умеет инкрементальное обновление. Если вы изменили пару файлов, он не будет перелопачивать весь проект, а обновит только то, что нужно. Это заслуга Rust-движка под капотом.
Интеграция с ИИ-агентами
Самый сок начинается при использовании с Claude Code или другими агентами. Вы можете добавить ccc как навык (Skill):
npx skills add cocoindex-io/cocoindex-code
Теперь агент сам будет решать, когда ему нужно воспользоваться семантическим поиском. Например, если вы спросите его: «Найди, где в этом легаси-коде запрятана логика списания бонусов», он не будет гадать, а сделает точный запрос через cocoindex-code.
Немного о внутренностях
Проект поддерживает внушительный список языков: от Python и TypeScript до Rust, Go и даже SQL с Solidity. Для каждого языка используется свой парсер, чтобы правильно разбивать код на чанки.
В конфиге ~/.cocoindex_code/global_settings.yml можно гибко настроить модель эмбеддингов. По умолчанию предлагается Snowflake/snowflake-arctic-embed-xs — она маленькая, быстрая и вполне справляется с кодом. Но если хочется чего-то помощнее, можно подключить nomic-ai/CodeRankEmbed или облачные модели через LiteLLM.
Кстати, если у вас действительно огромный проект на десятки тысяч файлов, может возникнуть ошибка MDB_MAP_FULL. Это ограничение базы LMDB. Лечится простым увеличением лимита в конфиге:
envs:
COCOINDEX_LMDB_MAP_SIZE: "34359738368" # 32 GiB
Стоит ли пробовать
Инструмент определенно пригодится тем, кто:
- Работает с большими или незнакомыми кодовыми базами.
- Активно использует AI-ассистентов и хочет снизить расходы на токены.
- Ищет быстрый способ навигации по проекту без настройки сложных IDE-плагинов.
Конечно, для маленького проекта на три файла это избыточно. Но как только количество модулей переваливает за десяток, возможность спросить терминал «где тут обработка ошибок в API» и получить точный ответ — дорогого стоит.
Проект активно развивается, и хотя документация местами лаконична, CLI-команда ccc doctor отлично помогает разобраться, если что-то пошло не так. Если вы цените скорость и локальность инструментов, cocoindex-code — отличный кандидат в ваш toolbox.
