tokensave

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

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

Зачем нужен tokensave?

ИИ-агенты программирования тратят токены на исследование кодовых баз. Каждый 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-binstall (любая платформа):

# Fast install prebuilt binary without compiling:
cargo binstall tokensave

# Or compile from source:
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 omp             # Oh My Pi (OMP)
tokensave install --agent opencode        # OpenCode
tokensave install --agent pi              # Pi (pi.dev)
tokensave install --agent plank           # Plank (macOS only)
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)
tokensave githooks                         # show which global git hooks tokensave owns
tokensave githooks off                     # remove them, leaving any hook content you wrote

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

Глобальные установки OMP нацелены на профиль, сообщаемый голым omp config path, записывая <resolved-agent-dir>/mcp.json и <resolved-agent-dir>/rules/tokensave.md. Экспортируйте OMP_PROFILE или совместимый с OMP PI_PROFILE при установке в именованный профиль; резолвер OMP также учитывает PI_CONFIG_DIR и PI_CODING_AGENT_DIR. Tokensave доверяет нативному резолверу, а не дублирует логику профилей OMP. Tokensave устанавливает MCP и рекомендательные правила для OMP; он не устанавливает принудительное применение хуков OMP.

Все изменения идемпотентны — безопасно запускать снова после обновления. После настройки агента вам будет предложено установить глобальные git хуки post-commit и post-checkout. tokensave uninstall удаляет эти хуки вместе с интеграциями агентов; передайте --keep-git-hooks, чтобы оставить их, или управляйте ими отдельно с помощью tokensave githooks.

Установка в рамках проекта

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

tokensave install --local --agent claude
tokensave install --local --agent omp

Это записывает конфигурацию в рамках проекта, которую можно закоммитить и поделиться с командой. Для Claude это ./.mcp.json, ./.claude/settings.json и ./CLAUDE.md; OMP использует ./.omp/mcp.json и ./.omp/rules/tokensave.md без вызова OMP CLI. Поддерживаемые агенты: claude, cursor, droid, gemini, zed, opencode, roo-code, kiro, auggie, omp, plank (каждый пишет свой файл проекта, например, .cursor/mcp.json, .factory/mcp.json, .gemini/settings.json, .zed/settings.json, opencode.json, .roo/mcp.json, .kiro/settings/mcp.json, .augment/settings.json, .omp/mcp.json, .mcp.json для plank). У других агентов нет конфигурации в рамках проекта, и они сообщают об ошибке с --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 не может перехватить. Начиная с v4.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-инструмента позволяют выполнять кросс-веточные запросы без переключения вашего checkout:

• 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 в фоновом режиме. Эта команда ничего не делает, если ветка уже отслеживается или является веткой по умолчанию, поэтому обычное переключение между известными ветками ничего не стоит. Первоначальное извлечение свежего git clone и новой git worktree add также является переключением ветки, и оно может оказаться на ветке, не являющейся веткой по умолчанию (git clone -b feature, git worktree add -b feature); в этом случае хук запускает tokensave init сначала, а tokensave branch add после него, в таком порядке. Хук, написанный более ранней версией, сохраняет тело, с которым он был установлен — установщик никогда не перезаписывает существующий — поэтому на таких установках свежее рабочее дерево все еще требует auto_track ниже или ручного tokensave branch add.

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

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

Полное руководство см. в docs/BRANCHING-USER-GUIDE.md.

Память между сессиями

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

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

Реестр экономии

Каждый вызов MCP записывает append-only строку в ~/.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) для более точного поиска.

Бенчмарк Criterion на больших реальных репозиториях

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

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

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

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

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

Запуск:

# Required: a writable cache directory for the cloned repos + their indexes.

<p align="center">
  <a href="https://ai.enzolombardi.net/"><img src="https://img.shields.io/badge/built%20with-AI-D97757?style=flat-square&labelColor=101010&logo=anthropic&logoColor=white" alt="Built with AI — part of Enzo Lombardi's AI portfolio"></a>
</p>

# 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 test-matrix probe (scripts/mcp_probe)

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

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

Структура — probe.py — драйвер (id-matched JSON-RPC, чтобы медленный инструмент не отравлял последующие вызовы), 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 выше: criterion измеряет задержку на итерацию для фокусного набора инструментов на закрепленных рефах и создает статистические отчеты в target/criterion/; mcp_probe проверяет каждый инструмент с более широким набором запросов на любых репозиториях, на которые вы его нацеливаете, оптимизируя широту покрытия, а не точность измерения.

80+ MCP-инструментов

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

Запрос другого инициализированного проекта

Семантические инструменты чтения могут запрашивать явно выбранный локальный граф без перезапуска MCP-сервера:

{
  "query": "screenGate",
  "graph_root": "/absolute/path/to/typewhisper"
}

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

{
  "node_id": "graph:<fingerprint>:function:<raw-id>",
  "graph_root": "/absolute/path/to/typewhisper",
  "graph_branch": "feature/auth"
}

graph_root должен быть точным абсолютным корнем уже инициализированного проекта. graph_branch опционален и, если указан, должен называть отслеживаемую ветку. Выбранные открытия — read-only: они никогда не инициализируют, не синхронизируют, не мигрируют, не авто-отслеживают и не записывают данные графа/исходников. Они также не вносят вклад в учет экономии. Вызовы без селекторов ведут себя точно так же, как раньше. graph_root полезен только в том случае, если вы знаете, что другой проект существует, поэтому сервер сообщает вам об этом: инициализированные проекты, расположенные непосредственно рядом с обслуживаемым корнем, перечислены в MCP instructions, в tokensave_status и в пустых результатах tokensave_search / tokensave_context — в тот момент, когда сессия в противном случае заключила бы, что символ не существует, а не заглянула бы по соседству (#375). Предлагаются только непосредственные соседи, не более пяти, и ничего не открывается и не индексируется от их имени; запрос к одному из них по-прежнему требует явного graph_root.

Селекторы намеренно недоступны для инструментов, которые записывают данные, выполняют внешние команды или зависят от текущего checkout: примитивы редактирования, инструменты VCS и веток, диагностика и выполнение тестов, интроспекция зависимостей и среды выполнения, инструменты рабочего процесса и памяти сессии, инструмент постоянного кэша (tokensave_redundancy) и администрирование сервера. Эти инструменты отклоняют селектор вместо того, чтобы молча его игнорировать.

Обнаружение

Не-кодовые артефакты

tokensave_files охватывает больше, чем исходный код. Файлы, расширение которых указано в artifact_extensions (.feature, .json, .yaml, .yml, .sql, .toml, .proto, .graphql, .md по умолчанию), отслеживаются по пути, так что такие вопросы, как «где находятся файлы .feature для потока входа?», получают ответ в виде графа, а не заблокированный find (#323). Они никогда не парсятся и не вносят символов; kind: "artifact" и kind: "code" фильтруют между двумя категориями, а анализы, означающие «код», исключают их. Расширение, уже обрабатываемое языковым экстрактором, игнорируется в этом списке, поэтому его нельзя использовать для остановки парсинга языка.

Список также определяет, внутрь чего может заглядывать литеральный поиск (#442). Литеральный (literal: true) поиск по tokensave_search читает байты, а не символы, поэтому ему не нужен парсер — но он перебирает индексированные файлы, поэтому может достичь только файла, для которого в индексе есть строка. Отслеживаемый шаблон .html или таблица стилей .css не имеет ни экстрактора, ни записи артефакта по умолчанию, поэтому их совпадения отсутствуют; добавьте расширение сюда и запустите tokensave sync -f, и его строки будут искаться как любые другие, с отчетом через enclosing: null, поскольку нет контекста символа. Литеральный ответ, который не смог достичь каждого отслеживаемого файла, сообщает об этом в блоке unscanned с указанием количества и расширений, так что частичный ответ никогда не выдается за полный.

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

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

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

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

Сессии

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

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

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

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

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

Перенос

Мульти-ветка

MCP-ресурсы

Четыре ресурса доступны через resources/list и resources/read:

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

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

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

Отключение отчетности. Строка метрик вместе с предложением в MCP instructions просит агента сообщать вам об экономии — что означает, что модель тратит выходные токены на описание экономии, которую tokensave сделал на входных токенах. Выходные токены — более дорогой вид, поэтому если ваш агент упоминает tokensave почти на каждом шаге, это повествование может свести на нет выигрыш (#356). Установите report_savings в false в .tokensave/config.json, или переменную окружения TOKENSAVE_REPORT_SAVINGS, чтобы переопределить для конкретного запуска (любое значение включает ее, кроме 0, false, no, off или пустого). И строка метрик, и инструкция исчезают; tokensave install также перестает записывать правило отчетности в файлы подсказок агента. Измерение не затрагивается в любом случае — каждый вызов по-прежнему попадает в реестр экономии, поэтому tokensave gain, tokensave list, status и monitor продолжают сообщать точно так же, как раньше. По умолчанию остается true.

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

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 memory [--clean]

Отчёт об использовании памяти на уровне всей машины для каждого процесса tokensave (MCP-серверы, синхронизации, запуски индексации) через общую таблицу с отображением в память по адресу ~/.tokensave/memory.mmap. Каждый экземпляр самостоятельно снимает свои показатели RSS по мере возможности при запуске, при каждом вызове инструмента MCP, а также вокруг фаз синхронизации и разрешения зависимостей, поэтому отчёт показывает текущее и пиковое значение RSS с фазой, в которой был достигнут пик — данные, необходимые для атрибуции высокого потребления памяти (см. #253). Строки помечаются как alive, dead (процесс, убитый OOM-killer, оставляет свой пик/фазу как судебно-медицинскую запись) или orphan (всё ещё работает, но переподчинён процессу init). --clean очищает мёртвые слоты.

PEAK PHASE указывает на самый высокий сэмпл, поэтому его точность ограничена частотой сэмплирования. Инкрементальная синхронизация записывает по порядку: sync:extract, sync:resolve:load_nodes, sync:resolve:build_caches, sync:resolve:refs, sync:variants, sync:done. Полная индексация записывает index:extract, index:resolve:build_caches, index:resolve:refs, index:resolve:done, index:insert, index:done.

Каждый сэмпл записывается после работы, которую он называет. Раньше они записывались до неё, поэтому каждый сэмпл сообщал RSS предыдущего шага под ярлыком следующего шага — что приписывало 73 МиБ загрузке узлов, хотя на самом деле это относилось к загрузке неразрешённых ссылок, шагу, для которого вообще не было сэмпла, и направляло расследование памяти не в ту подсистему в течение месяцев (#409). Если вы добавляете фазу, снимайте сэмпл после работы, а не до неё, и добавляйте сэмпл для любого шага, достаточно большого, чтобы удержать пик.

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

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 проверяет, были ли изменены какие-либо индексированные файлы с момента последней синхронизации. Если найдены устаревшие файлы, они повторно извлекаются до возврата ответа инструмента. Тридцатисекундная задержка предотвращает повторный обход дерева при каждом нажатии клавиши при последовательных вызовах.

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

Мультиагентная работа и git worktree. Когда несколько агентов работают над одним проектом одновременно, основное предположение состоит в том, что каждый агент работает в собственном git worktree. Worktree — это независимые файловые копии одного репозитория: у агента A и агента B есть своя копия каждого файла, поэтому они никогда не перезаписывают правки друг друга. tokensave автоматически определяет, когда запрос поступает из worktree, вложенного в основной checkout, и обслуживает результаты из правильного графа веток. Изменения накапливаются независимо и в конечном итоге объединяются через 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 Service были удалены в версии 6.0.0. Встроенный системный наблюдатель за файлами, заменивший демон, сам был удалён в версии 6.1.1 (он вызывал неконтролируемое потребление CPU и памяти на больших монорепозиториях с глубокими деревьями 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 и заменяет запущенный бинарный файл на месте. Поддерживает каналы stable и beta независимо.

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

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

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

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

warning: could not refresh tokensave config for: copilot.
  Run tokensave install to see the error.

Запустите 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 [--idle-timeout-secs N]   # Start MCP server (N: exit after N idle seconds)
tokensave servers [--json]         # List running servers and the index each one holds
tokensave monitor                  # Live TUI showing MCP calls across all projects
tokensave memory [--clean]         # Per-instance RSS report for all tokensave processes
tokensave upgrade                  # Self-update to latest version
tokensave channel [stable|beta]    # Show or switch update channel
tokensave doctor [--agent NAME]    # Check installation health
tokensave githooks [on|off] [--local]  # Manage git hooks (--local: this repo only, no core.hooksPath)
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}. Никаких cookie, никакого отслеживания, никакого идентификатора пользователя. 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

Полный (средний + всё остальное) — по умолчанию

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

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

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

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 покрывают обход графа вызовов, анализ влияния, обнаружение мёртвого кода, сопоставление тестов, предпросмотр переименования, иерархии типов, обнаружение циклических зависимостей, ранжирование по сложности, аналитику здоровья кода (Gini, DSM, глубина зависимостей, взвешенные по риску пробелы в тестах), атомарные примитивы редактирования и многое другое. Ближайший конкурент (code-review-graph) имеет 22 инструмента; у остальных — 5–9.

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

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

Индексация нескольких веток

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

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

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

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

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

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

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

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

«tokensave not initialized»

Каталог .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 использует слишком много оперативной памяти, вы можете отключить MCP-сервер для конкретного проекта, установив TOKENSAVE_DISABLE_SERVER=true в его окружении. Сервер корректно завершает работу без инициализации.

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

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

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

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

DISABLE_TOKENSAVE=true остаётся поддерживаемым устаревшим псевдонимом для конфигураций, созданных до того, как эта переменная была помещена в пространство имён.

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

Этот проект — порт оригинальной реализации CodeGraph на TypeScript от @colbymchenry на Rust. Порт сохраняет ту же архитектуру и интерфейс 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