tokensave

Семантическая кодовая аналитика для AI-агентов программирования

Меньше токенов • Меньше вызовов инструментов • 100% локально

Почему tokensave?

AI-агенты программирования тратят токены впустую, исследуя кодовые базы. Каждый grep, glob и чтение файла стоят денег. На сложных задачах агенты порождают множество под-агентов Explore, которые сканируют сотни файлов только для построения контекста.

tokensave предоставляет агентам предварительно проиндексированный семантический граф знаний. Вместо сканирования файлов агент запрашивает граф и получает мгновенные, структурированные ответы — нужные символы, их взаимосвязи и исходный код, за один вызов.

Как это работает

┌──────────────────────────────────────────────────────────────┐
│  AI Coding Agent (Claude Code, Codex, Gemini, Cursor, ...)   │
│                                                              │
│  "Implement user authentication"                             │
│        │                                                     │
│        ▼                                                     │
│  ┌─────────────────┐       ┌─────────────────┐               │
│  │  Sub-agent      │ ───── │  Sub-agent      │               │
│  └────────┬────────┘       └─────────┬───────┘               │
└───────────┼──────────────────────────┼───────────────────────┘
            │                          │
            ▼                          ▼
┌──────────────────────────────────────────────────────────────┐
│  tokensave MCP Server                                        │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐           │
│  │   Search    │  │   Callers   │  │   Context   │           │
│  │   "auth"    │  │  "login()"  │  │   for task  │           │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘           │
│         └────────────────┼────────────────┘                  │
│                          ▼                                   │
│              ┌───────────────────────┐                       │
│              │   libSQL Graph DB     │                       │
│              │   • Instant lookups   │                       │
│              │   • FTS5 search       │                       │
│              └───────────────────────┘                       │
└──────────────────────────────────────────────────────────────┘

Без tokensave: Агенты используют grep, glob и Read для сканирования файлов — много вызовов API, высокий расход токенов.

С tokensave: Агенты запрашивают граф через инструменты MCP — мгновенные результаты, локальная обработка, меньше токенов.

Ключевые возможности

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

1. Установка

Homebrew (macOS):

brew install aovestdipaperino/tap/tokensave

Scoop (Windows):

scoop bucket add tokensave https://github.com/aovestdipaperino/scoop-bucket
scoop install tokensave

Cargo (любая платформа):

cargo install tokensave                          # full (50+ languages, default)
cargo install tokensave --features medium        # medium tier
cargo install tokensave --no-default-features    # lite (smallest binary)

Готовые бинарные файлы (Linux, Windows, macOS):

Скачайте из последнего релиза и поместите бинарный файл в ваш PATH.

2. Настройка вашего агента

tokensave install                         # auto-detects installed agents
tokensave install --agent antigravity     # Google Antigravity (formerly Windsurf)
tokensave install --agent auggie          # AugmentCode
tokensave install --agent claude          # Claude Code
tokensave install --agent cline           # Cline
tokensave install --agent codex           # OpenAI Codex CLI
tokensave install --agent copilot         # GitHub Copilot
tokensave install --agent cursor          # Cursor
tokensave install --agent droid           # Factory Droid
tokensave install --agent gemini          # Gemini CLI
tokensave install --agent kilo            # Kilo CLI
tokensave install --agent kiro            # AWS Kiro
tokensave install --agent kimi            # Moonshot Kimi CLI
tokensave install --agent opencode        # OpenCode
tokensave install --agent pi              # Pi (pi.dev)
tokensave install --agent qwen            # Qwen Code
tokensave install --agent roo-code        # Roo Code
tokensave install --agent vibe            # Mistral Vibe
tokensave install --agent zed             # Zed
tokensave install --agent grok            # Grok Build (xAI)
tokensave install --git-hook yes           # auto-install the global post-commit and post-checkout hooks (no prompt)
tokensave install --git-hook no            # skip the post-commit and post-checkout hooks (no prompt)

Каждый агент регистрирует свой MCP-сервер в нативном формате конфигурации. Claude Code дополнительно получает хук PreToolUse (блокирует расточительных агентов Explore), хук UserPromptSubmit, хук Stop, правила подсказок в CLAUDE.md и автоматически разрешенные права инструментов. Kiro получает глобальную конфигурацию MCP, tokensave.md управление загружается как ресурс, и управляемый tokensave агент по умолчанию с разрешительным одобрением встроенных инструментов и инструментов tokensave, хуками ограничения делегирования и синхронизацией после записи; агенты Kiro, управляемые пользователем, сохраняются.

Все изменения идемпотентны — их безопасно запускать повторно после обновления. После настройки агента вам будет предложено установить глобальные git-хуки post-commit и post-checkout.

Локальная установка в проект

По умолчанию tokensave install регистрирует MCP-сервер в вашей глобальной конфигурации агента (например, ~/.claude.json). Чтобы зарегистрировать tokensave только для текущего проекта, добавьте --local:

tokensave install --local --agent claude

Это записывает конфигурацию в рамках проекта, которую можно закоммитить и использовать совместно с командой. Для Claude это ./.mcp.json, ./.claude/settings.json и ./CLAUDE.md. Поддерживаемые агенты: claude, cursor, droid, gemini, zed, opencode, roo-code, kiro, auggie (каждый записывает свой файл проекта, например, .cursor/mcp.json, .factory/mcp.json, .gemini/settings.json, .zed/settings.json, opencode.json, .roo/mcp.json, .kiro/settings/mcp.json, .augment/settings.json). Другие агенты не имеют конфигурации в рамках проекта и сообщают об ошибке с --local.

Удалите локальную установку проекта с помощью tokensave uninstall --local.

3. Индексация вашего проекта

cd /path/to/your/project
tokensave init

Это создает директорию .tokensave/ с базой данных графа знаний. Инициализация и синхронизация — это отдельные команды: init — это разовое действие для каждого проекта, в то время как sync обновляет только те проекты, которые уже были инициализированы. Это предотвращает скрытое создание баз данных глобальными git-хуками в репозиториях, которые вы не собирались индексировать. После init используйте tokensave sync для инкрементального обновления — переиндексируются только измененные файлы.

{
  "mcpServers": {
    "tokensave": {
      "command": "/path/to/tokensave",
      "args": ["serve"]
    }
  }
}

Устойчивая к сбоям синхронизация

Грамматики Tree-sitter — это скомпилированный код C/C++. Иногда они вызывают внутреннее утверждение или иным образом завершают процесс способами, которые обработка паники Rust не может перехватить. Начиная с версии 4.3.0, каждый файл разбирается внутри кратковременного рабочего подпроцесса: если грамматика вызывает segfault, вызывает abort() или переполняет стек, умирает только рабочий процесс. Пул перезапускает его, проблемный файл регистрируется и пропускается, а sync продолжает работу.

Рабочий процесс — это скрытая подкоманда extract-worker, аутентифицированная перед родителем с помощью 256-битного токена за каждый запуск, требуемого как в переменной окружения TOKENSAVE_WORKER_TOKEN, так и в качестве первых 32 байт, полученных через stdin. Прямой вызов пользователями невозможен. По умолчанию используется available_parallelism() рабочих процессов; откажитесь с помощью TOKENSAVE_DISABLE_SUBPROCESS=1.

Примитивы редактирования (tokensave_str_replace, tokensave_insert_at и т.д.) по-прежнему выполняются в процессе: они нацелены на один файл за раз, где накладные расходы на подпроцесс были бы доминирующими, и сбой экстрактора там сразу виден агенту.

Многоветочное индексирование (опционально)

tokensave может опционально поддерживать отдельный граф кода для каждой git-ветки. При включении переключение веток никогда не дает устаревших результатов и никогда не переиндексирует файлы, которые вы уже проанализировали в другой ветке. Многоветочное отслеживание включается по желанию — без него tokensave использует единую базу данных для всех веток.

Как это работает

Когда вы отслеживаете ветку, tokensave копирует ближайшую родительскую БД и синхронизирует только отличающиеся файлы. Это означает, что отслеживание функциональной ветки от main происходит почти мгновенно — анализируются только измененные вами файлы.

Команды CLI

tokensave branch add              # track the current branch
tokensave branch list             # see tracked branches and DB sizes
tokensave branch remove <name>    # stop tracking a branch
tokensave branch removeall        # remove all tracked branches except default
tokensave branch gc               # clean up branches deleted from git

Инструменты MCP для работы между ветками

Три инструмента MCP позволяют выполнять запросы между ветками без переключения рабочей копии:

• tokensave_branch_search — поиск символов в графе другой ветки
• tokensave_branch_diff — сравнение графов кода между двумя ветками: добавленные, удаленные и измененные символы (отличается сигнатура). Поддерживает фильтры по файлам и типам.
• tokensave_branch_list — список отслеживаемых веток с размерами БД, родительской веткой и временем синхронизации

Резервный переход по веткам

Когда MCP-сервер не может найти базу данных для текущей ветки, он обслуживает из БД ближайшей родительской ветки и включает предупреждение в каждый ответ инструмента, предлагая запустить tokensave branch add.

Автоматическое отслеживание веток (v7.3.0)

После начальной загрузки многоветочного режима (первое ручное tokensave branch add создало метаданные ветки), новые ветки могут отслеживаться автоматически, вместо перехода к родительской БД. Это покрывают два независимых механизма; проекты в режиме единой БД никогда не затрагиваются, и ни один механизм никогда не трогает базу данных ветки по умолчанию.

Git-хук (при переключении ветки). Хук post-checkout, который устанавливает tokensave install, распознает переключение ветки (в отличие от переключения файла) и запускает tokensave branch add в фоновом режиме. Эта команда ничего не делает, если ветка уже отслеживается или является веткой по умолчанию, поэтому обычное переключение между известными ветками ничего не стоит.

Автоотслеживание при открытии (опционально). Когда запускается TokenSave::open — команда CLI или старт MCP-сервера — и активная ветка не отслеживается, tokensave может отследить ее на месте, скопировав БД ближайшего отслеживаемого предка и записав ее в метаданные ветки. Это управляется полем конфигурации auto_track (по умолчанию false) или переменной окружения TOKENSAVE_AUTO_TRACK, которая переопределяет конфигурацию для каждого запуска (любое значение включает, кроме 0, false, no, off или пустого). Копирование — это то же самое почти мгновенное копирование БД предка, которое выполняет ручное branch add; синхронизация в этот момент не запускается — хук post-commit поддерживает БД новой ветки в актуальном состоянии по мере коммитов, или запустите tokensave sync для немедленного обновления. Автоотслеживание работает строго по принципу "максимальных усилий": о любой ошибке сообщается как о предупреждении, и open() продолжает работу с обычным резервным переходом к предку, так что это никогда не может нарушить вызов инструмента.

Короче говоря: с установленным хуком, переключение на новую функциональную ветку прозрачно дает ей собственный граф для каждой ветки; с включенным auto_track, даже ветка, созданная вне переключения (например, в свежем worktree), подхватывается при первом открытии проекта tokensave на ней.

См. docs/BRANCHING-USER-GUIDE.md для полного руководства.

Межсессионная память

Три инструмента MCP сохраняют решения и контекст области кода между сессиями, хранясь в рамках проекта .tokensave/tokensave.db.

Используйте их, чтобы агенту не приходилось заново объяснять архитектурные решения от сессии к сессии.

Журнал экономии

Каждый вызов MCP записывает строку только для добавления в ~/.tokensave/global.db (таблица savings_ledger). Просмотр с помощью tokensave gain:

tokensave gain                    # current project, last 30 days
tokensave gain --all              # all projects
tokensave gain --history --range 7d
tokensave gain --json

Оценки в долларах используют существующий модуль ценообразования (цены на вход Sonnet, обновляются ежедневно через LiteLLM).

Воспроизводимый бенчмарк

tokensave bench запускает фиксированный набор запросов через tokensave_context и сообщает об экономии при извлечении по сравнению с базовым уровнем полного файла (зеркально отражает методологию CCE):

tokensave bench                                    # ships with 10 default queries
tokensave bench --queries my-queries.toml --json
tokensave bench --max-nodes 5

Измерено на этом репозитории (сам tokensave) с использованием поставляемого общего набора запросов:

Совокупно: 88% средняя экономия при извлечении (142.8k → 5.5k токенов по 10 запросам).

Набор запросов по умолчанию нацелен на шаблоны, присутствующие в большинстве кодовых баз приложений (CLI, демоны, сервисы). Запустите его на своем проекте с помощью tokensave bench, чтобы увидеть свои цифры, или напишите адаптированный файл запросов (--queries my.toml) для более точного отзыва.

Критериальный бенч на больших реальных репозиториях

benches/large_repos.rs — это criterion микро-бенчмарк, который тестирует инструменты MCP сквозным образом на четырех крупных open-source кодовых базах, зафиксированных на постоянных ссылках. Каждый инструмент управляется как минимум 5 запросами с аргументами (идентификаторы узлов, полные имена, глобы файлов, …), выбранными из индексированного графа один раз для каждого репозитория, так что временные показатели воспроизводимы между запусками.

Репозитории и зафиксированные ссылки (определены в benches/repos.rs):

Каждый репозиторий клонируется с малой глубиной (git init + git fetch --progress --depth 1 origin <ref> + checkout FETCH_HEAD) при первом использовании и кэшируется локально; последующие запуски используют существующую копию. Вывод Git транслируется в терминал, так что многогигабайтная загрузка показывает прогресс в реальном времени.

Охваченные инструменты (по 5 запросов каждый). Инструменты чтения — search, context, callers, callees, node, by_qualified_name, signature, impact, body, files, complexity, doc_coverage, largest, hotspots, god_class, module_api, derives, dead_code, rank, coupling, circular. Инструменты записи — str_replace, multi_str_replace, insert_at и (если ast-grep находится в PATH) ast_grep_rewrite.

Принудительная синхронизация при каждом запуске. Перед запуском любого бенчмарка обвязка выполняет эквивалент tokensave sync --force для каждого репозитория (index_all() независимо от свежести .tokensave/), так что временные показатели всегда отражают зафиксированный исходный код.

Бенчи записи и очистка. Инструменты записи изменяют файлы. Чтобы сохранить предусловие «совпадение должно быть уникальным», обвязка использует criterion iter_batched — небольшой рабочий файл в <repo>/.tokensave-bench-scratch/ перезаписывается известным содержимым перед каждой итерацией с замером времени, затем инструмент редактирования работает с ним. После завершения всех бенчмарков обвязка запускает git stash --include-untracked && git stash drop внутри каждого подготовленного репозитория, чтобы рабочее дерево вернулось к зафиксированной ссылке.

Конфигурация Criterion. Бенч переопределяет значения criterion по умолчанию на sample_size = 10 и measurement_time = 30s (против стандартных 100 / 5 с), что дает каждому замеру времени на запрос ~30 секунд измерения — достаточно, чтобы медленные инструменты, такие как tokensave_context на polkadot-sdk, выдавали стабильные цифры.

Запуск:

# Required: a writable cache directory for the cloned repos + their indexes.
# Expect several GB of disk and a long first run (shallow clone + full index of each repo).
export TOKENSAVE_BENCH_REPOS_DIR=~/tokensave-bench-cache

cargo bench --bench large_repos

Если TOKENSAVE_BENCH_REPOS_DIR не задана, бенч выводит уведомление и регистрирует ноль бенчмарков (так что cargo bench --all остается дешевым на машинах контрибьюторов).

Конфигурация (все опционально, через переменные окружения):

Фильтрация бенчмарков использует стандартный CLI criterion — например, только инструмент search на scipy:

cargo bench --bench large_repos -- 'scipy/tokensave_search'

Отчеты (HTML + сырые выборки) сохраняются в target/criterion/.

Чтобы изменить зафиксированные ссылки (например, на более новый релиз или конкретный SHA), отредактируйте REPOS в benches/repos.rs и удалите соответствующий маркер $TOKENSAVE_BENCH_REPOS_DIR/<repo>/.bench-ref, чтобы следующий запуск перезагрузил данные. Если вы пропустите очистку после запуска (например, нажмете Ctrl-C в середине бенча), запуск git stash --include-untracked && git stash drop внутри каждой директории репозитория восстановит его вручную.

Зонд тестовой матрицы MCP (scripts/mcp_probe)

scripts/mcp_probe/ — это обвязка на Python, которая управляет tokensave serve через stdio для настраиваемого набора реальных репозиториев и тестирует каждый инструмент MCP только для чтения с 5 вариантами запросов на каждый язык, создавая таблицу статусов для каждого инструмента / репозитория. Одна и та же обвязка служит двум целям:

• Регрессионное сканирование. Новая языковая поддержка, новый инструмент или рефакторинг — перезапустите матрицу, и любая ячейка, которая выдает новую ошибку, тайм-аут или возвращает пустые результаты, выделяется как 🚩.
• Зонд производительности. Временные показатели каждого вызова записываются в TSV; тот же фиксированный корпус репозиториев служит для грубого сравнения между версиями. Текущая ошибка цикла tokensave_inheritance_depth была обнаружена этой обвязкой, когда один инструмент на polkadot-sdk превысил тайм-аут >60 с.

Структура — probe.py является драйвером (JSON-RPC с сопоставлением по id, чтобы медленный инструмент не мог отравить последующие вызовы), isolated.py повторно запускает один инструмент с новым сервером для каждого вызова (избегает очередей сервера), build_matrix.py читает TSV и выдает markdown, модули tools/<lang>.py предоставляют наборы запросов для каждого языка (Rust поставляется; добавьте Python/Go/…, добавив новый модуль), repos.toml перечисляет целевые репозитории (переопределите через $TOKENSAVE_PROBE_REPOS).

Быстрый запуск:

cargo build --release --bin tokensave
python3 scripts/mcp_probe/probe.py
python3 scripts/mcp_probe/build_matrix.py > matrix.md

Выходные ячейки: ✓ 5/5 (чисто), 🐛 e/N (ошибки), ⏱ N/N (тайм-ауты), ∅ E/N (пусто), 🐢 ok/slow (вызовы >10 с). Любая ячейка с ошибкой или тайм-аутом получает 🚩 в крайнем правом столбце. Детали каждого вызова с первыми 100 символами каждой ошибки попадают в журнал TSV для последующего анализа.

Отличие от критериального бенча выше: criterion измеряет задержку на итерацию для сфокусированного набора инструментов на зафиксированных ссылках и создает статистические отчеты в target/criterion/; mcp_probe тестирует каждый инструмент с более широким набором запросов на любых репозиториях, на которые вы укажете, оптимизируя широту охвата, а не точность измерений.

Более 80 инструментов MCP

Сервер предоставляет более 80 инструментов (на один меньше, если опциональный бинарный файл ast-grep отсутствует в PATH); таблицы ниже группируют наиболее часто используемые по категориям. Большинство из них только для чтения, их безопасно вызывать параллельно, и они аннотированы с помощью readOnlyHint. Примитивы редактирования ограничены отдельными файлами и переиндексируются на месте; инструменты базового уровня сессии и записи в память также изменяют локальное состояние .tokensave и аннотированы как не только для чтения. Три основных инструмента (tokensave_context, tokensave_search, tokensave_status) помечены anthropic/alwaysLoad, поэтому они обходят цикл поиска инструментов клиента.

Обнаружение

Граф вызовов и влияние

Качество кода

Аналитика здоровья кода

Пять инструментов выявляют сигналы структурного качества из существующего графа. Составная оценка использует среднее геометрическое по независимым измерениям, так что ни одно из них нельзя обмануть.

Сессии

Сделайте снимок метрик здоровья в начале сессии кодирования с ИИ, затем сравните в конце, чтобы увидеть, что улучшилось или ухудшилось.| Инструмент | Назначение | |------|---------| | tokensave_session_start | Сохранить текущие метрики здоровья в виде JSON-слепка для последующего сравнения | | tokensave_session_end | Пересчитать и сравнить со слепком — дельты по каждому измерению, пройдено/не пройдено, автоматическая очистка |

Примитивы редактирования

Четыре инструмента записи, позволяющие агентам изменять файлы без рисков, связанных с регулярными выражениями или экранированием командной оболочки. Каждый работает с одним файлом, привязан к якорю и запускает переиндексацию на месте после записи, чтобы граф никогда не устаревал.

Git и рабочий процесс

Система типов

Портирование

Многоветвевая работа

Ресурсы MCP

Четыре ресурса предоставляются через resources/list и resources/read:

• tokensave://status -- статистика графа в формате JSON
• tokensave://files -- проиндексированное дерево файлов, сгруппированное по директориям
• tokensave://overview -- сводка проекта с распределением языков и видами символов
• tokensave://branches -- отслеживаемые ветки с размерами БД и информацией о родителях

Учёт токенов

tokensave измеряет количество сэкономленных токенов при каждом вызове инструмента MCP. Каждый ответ инструмента включает строку tokensave_metrics: before=N after=M, показывающую, сколько токенов необработанных файлов было сэкономлено этим конкретным вызовом.

Наблюдаемость затрат

tokensave cost                     # 7-day cost summary (default)
tokensave cost today               # today only
tokensave cost --by-model          # breakdown by Claude model
tokensave cost --by-task           # breakdown by task category (coding, debugging, exploration, ...)
tokensave cost --export json       # JSON export to stdout
tokensave cost --export csv        # CSV export to stdout

Анализирует стенограммы сессий Claude Code (~/.claude/projects/**/*.jsonl), классифицирует каждый API-оборот по одной из 13 категорий задач, вычисляет стоимость в долларах, используя цены моделей, и сохраняет результаты в ~/.tokensave/global.db для быстрых агрегированных запросов. Цены обновляются из LiteLLM каждые 24 часа и используют встроенную таблицу при отсутствии сети.

Заголовок tokensave status включает строку затрат, показывающую сегодняшние расходы, итог за 7 дней и коэффициент эффективности (сэкономлено токенов / всего токенов). TUI tokensave monitor показывает панель затрат в реальном времени рядом с лентой экономии. В конце каждой сессии Claude Code обработчик hook_stop выводит однострочный чек в терминал.

Категории классификации задач: Кодирование, Отладка, Разработка функций, Рефакторинг, Тестирование, Исследование, Планирование, Делегирование, Операции с Git, Сборка/Развёртывание, Мозговой штурм, Общение, Общее. Классификация детерминирована (сопоставление с образцом по именам инструментов и командам Bash), не требует вызовов LLM и адаптирована из AgentSeal/codeburn.

Живой монитор

tokensave monitor

Глобальный TUI, показывающий вызовы инструментов MCP из всех проектов в реальном времени через общий кольцевой буфер в памяти по адресу ~/.tokensave/monitor.mmap. Каждая запись показывает имя проекта, имя инструмента и дельту токенов. Панель затрат вверху показывает сегодняшние расходы, экономию, эффективность и основную модель (обновляется каждые 30 секунд).

Счётчики сессии и за всё время

tokensave current-counter          # show per-project session counter
tokensave reset-counter            # reset the session counter
tokensave status                   # shows project + global lifetime totals + cost

tokensave status отображает статистику индекса проекта, разбивку по языкам, строку затрат (сегодня / 7 дн. / эффективность), а также итоги за всё время по проекту и по всему миру:

Всемирный счётчик

Все пользователи tokensave вносят вклад в анонимный агрегированный счётчик. tokensave status показывает как ваш итог по проекту, так и всемирный итог. При отправке передаётся только одно число (например, 4823) без идентифицирующей информации. Отказаться можно с помощью tokensave disable-upload-counter.

Актуальность индекса

tokensave поддерживает граф в актуальном состоянии без фонового демона или наблюдателя за файлами на уровне ОС.

Проверка устаревания по требованию. Каждый вызов инструмента MCP проверяет, были ли изменены какие-либо проиндексированные файлы с момента последней синхронизации. Если обнаружены устаревшие файлы, они повторно извлекаются до возврата ответа инструмента. 30-секундная задержка предотвращает повторный обход дерева при каждом нажатии клавиши при последовательных вызовах.

Навёрстывающая синхронизация при подключении. При запуске MCP-сервер немедленно выполняет неблокирующую навёрстывающую синхронизацию, которая подхватывает любые изменения, сделанные, пока агент не был подключён — git pull, правка в IDE, шаг сборки — так что самый первый вызов инструмента в сессии видит актуальный индекс.

Мультиагентная работа и git worktrees. Когда несколько агентов работают над одним проектом одновременно, строгое предположение состоит в том, что каждый агент работает в своём собственном git worktree. Worktrees — это независимые файловые checkout'ы одного репозитория: у агента A и агента B есть своя копия каждого файла, поэтому они никогда не перезаписывают незавершённые правки друг друга. tokensave автоматически определяет, когда запрос приходит из worktree, вложенного в основную рабочую копию, и выдаёт результаты из графа правильной ветки. Изменения накапливаются независимо и в конечном итоге согласовываются через git merge или rebase — тот же процесс, который используется для любой другой параллельной разработки. Такая конструкция позволяет избежать сложностей и режимов отказа, связанных с межагентной блокировкой общего изменяемого каталога.

Рабочие процессы только с CLI. Если вы запускаете команды tokensave без подключённого агента (без MCP-сервера), проверка устаревания между командами не выполняется. Установите git-хуки для автоматического поддержания индекса в актуальном состоянии после каждого коммита или клонирования:

cp scripts/post-commit scripts/post-checkout .git/hooks/
chmod +x .git/hooks/post-commit .git/hooks/post-checkout

Обновление с версии 5.x

Автономная команда tokensave daemon и её автозапуск через launchd/systemd/Службу Windows были удалены в версии 6.0.0. Встроенный наблюдатель за файлами на уровне ОС, заменивший демона, сам был удалён в версии 6.1.0 (он вызывал неконтролируемый рост нагрузки на ЦП и память на больших монорепозиториях с глубокими деревьями node_modules или target). Описанная выше модель проверки устаревания по требованию является текущей архитектурой.

Если у вас всё ещё есть автозапуск демона от версии 5.x, удалите его:

• macOS: launchctl unload ~/Library/LaunchAgents/com.tokensave.daemon.plist && rm ~/Library/LaunchAgents/com.tokensave.daemon.plist
• Linux: systemctl --user disable --now tokensave-daemon && rm ~/.config/systemd/user/tokensave-daemon.service
• Windows: sc.exe delete tokensave-daemon (из терминала с повышенными правами)

Если вы не помните точное имя: launchctl list | grep tokensave / systemctl --user list-units | grep tokensave / sc.exe query state= all | findstr -i tokensave.

Самообновление

tokensave upgrade                  # upgrade to latest in current channel
tokensave channel                  # show current channel (stable/beta)
tokensave channel beta             # switch to beta channel
tokensave channel stable           # switch back to stable

tokensave upgrade загружает правильный бинарный файл для платформы из релизов GitHub и заменяет запущенный бинарный файл на месте. Поддерживает стабильный и бета-каналы независимо.

Версионирование и обновления

Номера версий tokensave выглядят как SemVer, но не следуют ему: изменяемый компонент кодирует необходимый объём обслуживания, которое tokensave выполняет автоматически при следующем запуске — вам никогда не нужно вручную выполнять переустановку или переиндексацию.

Глобальная переустановка. При первом запуске новой минорной или мажорной сборки tokensave незаметно повторно выполняет install для каждого зарегистрированного агента, чтобы конфигурация агента всегда указывала на текущий бинарный файл и предоставляла текущий набор инструментов. Патч-обновления пропускают этот шаг — маркер запущенной версии просто обновляется.

Принудительная переиндексация для каждого проекта (только для мажорных версий). Мажорное изменение означает, что индексы проектов должны быть перестроены. tokensave делает это лениво и для каждого проекта отдельно: при первом вызове инструмента MCP в проекте после мажорного обновления он запускает фоновую полную переиндексацию (эквивалент tokensave sync --force), которая никогда не блокирует ответ инструмента.

Резервный вариант Brew / cargo. Внешние обновления, заменяющие бинарный файл вне tokensave upgrade — brew upgrade tokensave или cargo install tokensave — обнаруживаются таким же образом: если запущенная версия новее, чем последняя версия, выполнившая установку, переустановка запускается при следующем запуске так же, как после самообновления.

См. TOKENSAVE-VERSIONING.md для объяснения, почему tokensave отходит от SemVer (кодирование обслуживания в версии — это то, что делает возможными обновления без участия пользователя), механики маркеров, независимой версии схемы базы данных и правил для мейнтейнеров по выпуску релизов.

Справка по CLI

tokensave init [path]              # Initialize a new project (full index)
tokensave sync [path]              # Incremental sync (must be initialized first)
tokensave sync --force [path]      # Force a full re-index
tokensave sync --doctor [path]     # Sync and list added/modified/removed files
tokensave status [path]            # Show statistics + cost summary
tokensave status [path] --json     # Show statistics (JSON output)
tokensave status --details         # Include node-kind breakdown
tokensave cost [range]             # Token cost summary (default: 7d)
tokensave cost --by-model          # Cost grouped by model
tokensave cost --by-task           # Cost grouped by task category
tokensave cost --export json|csv   # Export cost data
tokensave query <search> [path]    # Search symbols
tokensave files [--filter dir] [--pattern glob] [--json]   # List indexed files
tokensave affected <files...> [--stdin] [--depth N]        # Find affected test files
tokensave install [--agent NAME]   # Configure agent integration
tokensave reinstall                # Refresh settings for all installed agents
tokensave uninstall [--agent NAME] # Remove agent integration
tokensave serve                    # Start MCP server
tokensave monitor                  # Live TUI showing MCP calls across all projects
tokensave upgrade                  # Self-update to latest version
tokensave channel [stable|beta]    # Show or switch update channel
tokensave doctor [--agent NAME]    # Check installation health
tokensave branch add|list|remove|removeall|gc   # Multi-branch management
tokensave current-counter          # Show per-project token counter
tokensave reset-counter            # Reset per-project token counter
tokensave disable-upload-counter   # Opt out of worldwide counter uploads
tokensave enable-upload-counter    # Re-enable worldwide counter uploads

tokensave doctor

Запустить комплексную проверку работоспособности вашей установки tokensave:

tokensave doctor

Проверки: расположение бинарного файла, индекс проекта, глобальная БД, пользовательская конфигурация, интеграция агента (MCP-сервер, хуки, разрешения, правила подсказок) и сетевая связность. Если после обновления отсутствуют какие-либо разрешения инструментов, он предложит запустить tokensave install. Используйте --agent для проверки только конкретного агента.

Doctor также проверяет, что каждый установленный хук использует правильную подкоманду tokensave, и автоматически исправляет сломанные хуки.

Как это работает с Claude Code

После настройки Claude Code автоматически использует tokensave вместо чтения необработанных файлов, когда ему нужно понять вашу кодовую базу. Три уровня усиливают друг друга:

Результат: Claude получает то же понимание кода с гораздо меньшими затратами токенов. Типичный агент Explore читает 20-50 файлов; tokensave возвращает релевантные символы, связи и фрагменты кода из своего предварительно построенного индекса.

Сетевые вызовы и конфиденциальность

Основная функциональность tokensave (индексация, поиск, запросы к графу, MCP-сервер) на 100% локальна -- ваш код никогда не покидает ваш компьютер.

Загрузка мирового счётчика отправляет один HTTP POST с телом JSON, например {"amount": 4823}. Никаких куки, отслеживания, идентификатора пользователя. Cloudflare Worker регистрирует страну вашего IP-адреса (полученную из заголовков запроса) для агрегированной географической статистики — ваш фактический IP-адрес не сохраняется.

Обновление цен моделей загружает публичный JSON-файл с GitHub (raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json), чтобы поддерживать актуальность цен моделей Claude для tokensave cost. Данные не отправляются — это простой HTTPS GET. Ответ кэшируется на ~/.tokensave/pricing.json в течение 24 часов. Если загрузка не удалась, tokensave использует свою встроенную таблицу цен.

50+ языков

tokensave поддерживает более 50 языков программирования, организованных в три уровня, управляемых флагами функций Cargo. Каждый уровень включает все языки из нижележащего уровня. Заголовки Markdown извлекаются как узлы Module с иерархическими рёбрами Contains, так что структура документа участвует в графовых запросах наряду с исходным кодом.

Lite — --no-default-features

Всегда компилируется. Самый маленький бинарный файл для самых популярных языков, плюс Svelte и Astro (извлечение блоков скриптов через экстрактор TypeScript, без дополнительной зависимости от грамматики).

Medium (Lite + ещё 9) — --features medium

Full (Medium + всё остальное) — по умолчанию

Отдельные языки также можно выбирать выборочно, без полного уровня:

cargo install tokensave --no-default-features --features lang-nix,lang-bash

Все экстракторы имеют одинаковую глубину: функции, классы, методы, поля, импорты, графы вызовов, цепочки наследования, строки документации, метрики сложности, извлечение декораторов/аннотаций и отслеживание межфайловых зависимостей.

tokensave против CodeGraph

tokensave — это полностью переписанный на Rust аналог CodeGraph (Node.js/TypeScript). Оба строят семантические графы кода для агентов ИИ-кодинга, но значительно различаются по охвату и возможностям.

CodeGraph был пионером в этом подходе и остаётся надёжным выбором, если вы предпочитаете инструментарий npm и нуждаетесь только в интеграции с Claude Code. tokensave расширяет концепцию более глубоким анализом, большим количеством агентов, поддержкой нескольких веток и нативным бинарным файлом без зависимостей времени выполнения.

Для подробного сравнения с CodeGraph, Dual-Graph (GrapeRoot), code-review-graph и OpenWolf смотрите docs/COMPARABLE-TOOLS.md.

Почему tokensave лучше альтернатив

Несколько инструментов сокращают использование токенов для агентов ИИ-кодинга. Вот почему tokensave выделяется.

Единый нативный бинарный файл, нулевые зависимости

Каждая альтернатива требует среду выполнения: Python, Node.js или и то, и другое. tokensave поставляется как единый бинарный файл Rust размером ~25 МБ со всеми 50+ грамматиками tree-sitter. Больше ничего устанавливать не нужно.

Самая глубокая аналитика кода

tokensave работает на уровне символов: функции, структуры, поля, рёбра вызовов, иерархии типов, метрики сложности. Альтернативы, такие как Dual-Graph (GrapeRoot), работают на уровне файлов — они знают, какие файлы существуют, но не могут ответить на вопросы «кто вызывает эту функцию?» или «что сломается, если я изменю эту структуру?». 80+ специализированных инструментов MCP tokensave охватывают обход графа вызовов, анализ влияния, обнаружение мёртвого кода, сопоставление тестов, предпросмотр переименования, иерархии типов, обнаружение циклических зависимостей, ранжирование сложности, аналитику здоровья кода (Джини, DSM, глубина зависимостей, пробелы в тестах с учётом рисков), атомарные примитивы редактирования и многое другое. Ближайший конкурент (code-review-graph) имеет 22 инструмента; у других — 5-9.

Самая широкая поддержка агентов

Более десятка интеграций с агентами ИИ-кодинга с нативными форматами конфигурации для каждого агента. Ни один другой инструмент не охватывает столько агентов с такой глубокой интеграцией. Claude Code получает хуки, правила подсказок и автоматически разрешённые разрешения инструментов. Kiro получает глобальную конфигурацию MCP, tokensave.md управление загружается как ресурс, управляемого агента с разрешительным одобрением встроенных инструментов/tokensave, а также хуки для защитных ограждений делегирования и синхронизации после записи. Другие агенты получают регистрацию сервера MCP в их нативном формате конфигурации.

Многоветвевое индексирование

Единственный инструмент в этой области с опциональными графовыми базами данных на ветку и межветвевым diff и поиском. При включении переключение веток происходит мгновенно — повторное индексирование не требуется.

Отслеживание токенов на вызов

Единственный инструмент, который сообщает, сколько именно токенов сэкономил каждый отдельный вызов инструмента MCP, плюс живой TUI-монитор по всем проектам и счётчики за всё время.

Полностью открытый исходный код

Rust под лицензией MIT, полностью аудируемый. Основной движок Dual-Graph (graperoot на PyPI) является проприетарным — вы не можете увидеть, что он делает с вашим графом кода. OpenWolf под AGPL-3.0, что требует открытия исходного кода производных работ.

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

Бенчмарк полного индексирования на смешанной кодовой базе из 1,782 файлов Rust/Java/Scala (57K узлов, 103K рёбер):

Устранение неполадок

"tokensave не инициализирован"

Каталог .tokensave/ не существует в вашем проекте.

tokensave init

Сервер MCP не подключается

Агент ИИ не видит инструменты tokensave.

1. Убедитесь, что конфигурация агента включает сервер MCP tokensave (запустите tokensave doctor)
2. Полностью перезапустите агента
3. Проверьте, что tokensave находится в вашем PATH: which tokensave

Отсутствуют символы в поиске

• Запустите tokensave sync, чтобы обновить индекс
• Проверьте, поддерживается ли язык (см. таблицу выше)
• Убедитесь, что файл не исключён .gitignore

Индексирование медленное

Большие проекты требуют больше времени при первом полном индексировании.

• Последующие запуски используют инкрементальную синхронизацию и работают значительно быстрее
• Используйте tokensave sync (не --force) для повседневных обновлений
• Устаревание проверяется автоматически при каждом вызове инструмента MCP, пока агент подключен

Отключение tokensave для отдельных проектов

Если проект слишком большой и tokensave потребляет слишком много оперативной памяти, вы можете отключить его для конкретного проекта, установив DISABLE_TOKENSAVE=true в окружении MCP-сервера. Сервер корректно завершает работу без инициализации.

Claude Code — добавьте в .claude/settings.json вашего проекта:

{
  "mcpServers": {
    "tokensave": {
      "command": "tokensave",
      "args": ["serve"],
      "env": {
        "DISABLE_TOKENSAVE": "true"
      }
    }
  }
}

Другие агенты — установите переменную окружения в той конфигурации, которую ваш агент использует для запуска MCP-серверов.

Вы также можете установить её глобально через оболочку (DISABLE_TOKENSAVE=true claude), но это отключит tokensave для всех проектов в текущем сеансе.

Происхождение

Этот проект является портом на Rust оригинальной реализации CodeGraph на TypeScript от @colbymchenry. Порт сохраняет ту же архитектуру и интерфейс инструментов MCP, используя Rust для повышения производительности и нативные привязки tree-sitter.

Сборка

cargo build --release                          # full (50+ languages, default)
cargo build --release --features medium        # medium tier
cargo build --release --no-default-features    # lite (smallest binary)

cargo test                                     # run all tests (requires full)
cargo check --no-default-features              # verify lite compiles
cargo clippy --all

История звёзд

Спонсоры

Бесплатная подпись кода для Windows предоставлена SignPath.io, сертификат от SignPath Foundation

Лицензия

Лицензия MIT — подробности см. в LICENSE.

tokensave.dev