tokensave

Inteligência Semântica de Código para Agentes de Codificação com IA

Menos tokens • Menos chamadas de ferramentas • 100% local

Por que tokensave?

Agentes de codificação com IA desperdiçam tokens explorando bases de código. Cada grep, glob e leitura de arquivo custa dinheiro. Em tarefas complexas, os agentes geram múltiplos subagentes de Exploração que varrem centenas de arquivos apenas para construir contexto.

tokensave dá aos agentes um grafo de conhecimento semântico pré-indexado. Em vez de escanear arquivos, o agente consulta o grafo e obtém respostas instantâneas e estruturadas -- os símbolos certos, suas relações e o código-fonte, em uma única chamada.

Como Funciona

┌──────────────────────────────────────────────────────────────┐
│  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       │                       │
│              └───────────────────────┘                       │
└──────────────────────────────────────────────────────────────┘

Sem tokensave: Agentes usam grep, glob e Read para escanear arquivos -- muitas chamadas de API, alto uso de tokens.

Com tokensave: Agentes consultam o grafo via ferramentas MCP -- resultados instantâneos, processamento local, menos tokens.

Principais Recursos

Início Rápido

1. Instalação

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 (qualquer plataforma):

# 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)

Binários pré-compilados (Linux, Windows, macOS):

Baixe da última versão e coloque o binário no seu PATH.

2. Configure seu agente

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

Cada agente tem seu servidor MCP registrado no formato de configuração nativo. Claude Code recebe adicionalmente um hook PreToolUse (bloqueia agentes de Exploração desperdiçadores), um hook UserPromptSubmit, um hook Stop, regras de prompt no CLAUDE.md e permissões de ferramentas auto-permitidas. Kiro recebe configuração MCP global, tokensave.md de direcionamento carregado como recurso e um agente padrão gerenciado por tokensave com aprovação permissiva de ferramentas integradas/tokensave, hooks de proteção de delegação e sincronização pós-gravação; agentes Kiro gerenciados pelo usuário são preservados.

Instalações globais do OMP visam o perfil relatado pelo omp config path puro, gravando <resolved-agent-dir>/mcp.json e <resolved-agent-dir>/rules/tokensave.md. Exporte OMP_PROFILE ou o PI_PROFILE compatível do OMP ao instalar em um perfil nomeado; o resolvedor do OMP também honra PI_CONFIG_DIR e PI_CODING_AGENT_DIR. Tokensave confia nesse resolvedor nativo em vez de duplicar a lógica de perfil do OMP. Tokensave instala regras MCP e consultivas para OMP; não instala aplicação de hooks do OMP.

Todas as alterações são idempotentes -- seguro executar novamente após atualizar. Após a configuração do agente, serão oferecidos hooks globais de git post-commit e post-checkout. tokensave uninstall remove esses hooks junto com as integrações de agente; passe --keep-git-hooks para deixá-los, ou gerencie-os separadamente com tokensave githooks.

Instalação local ao projeto

Por padrão, tokensave install registra o servidor MCP na configuração global do seu agente (ex.: ~/.claude.json). Para registrar tokensave apenas para o projeto atual, adicione --local:

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

Isso grava configuração com escopo de projeto que você pode commitar e compartilhar com sua equipe. Para Claude, isso é ./.mcp.json, ./.claude/settings.json e ./CLAUDE.md; OMP usa ./.omp/mcp.json e ./.omp/rules/tokensave.md sem invocar o CLI do OMP. Agentes suportados: claude, cursor, droid, gemini, zed, opencode, roo-code, kiro, auggie, omp, plank (cada um grava seu próprio arquivo de projeto, ex.: .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 para plank). Outros agentes não têm configuração com escopo de projeto e relatam um erro com --local.

Remova uma instalação local ao projeto com tokensave uninstall --local.

3. Indexe seu projeto

cd /path/to/your/project
tokensave init

Isso cria um diretório .tokensave/ com o banco de dados do grafo de conhecimento. Inicialização e sincronização são comandos separados: init é um opt-in único por projeto, enquanto sync apenas atualiza projetos que já foram inicializados. Isso evita que os hooks globais do git criem bancos de dados silenciosamente em repositórios que você nunca pretendeu indexar. Após init, use tokensave sync para atualizar incrementalmente -- apenas arquivos alterados são reindexados.

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

Sincronização Resiliente a Falhas

Gramáticas tree-sitter são código C/C++ compilado. Elas ocasionalmente atingem uma asserção interna ou terminam o processo por caminhos que o tratamento de panic do Rust não pode interceptar. A partir da v4.3.0, cada arquivo é analisado dentro de um subprocesso worker de curta duração: se uma gramática der segfault, chamar abort() ou atingir estouro de pilha, apenas o worker morre. O pool o reinicia, o arquivo problemático é registrado e ignorado, e sync continua.

O worker é um subcomando extract-worker oculto autenticado contra o pai via um token de 256 bits por spawn, exigido tanto como variável de ambiente TOKENSAVE_WORKER_TOKEN quanto como os primeiros 32 bytes recebidos no stdin. Invocação direta por usuários falha. Padrão de available_parallelism() workers; opte por sair com TOKENSAVE_DISABLE_SUBPROCESS=1.

Primitivas de edição (tokensave_str_replace, tokensave_insert_at, etc.) ainda rodam em processo: elas visam um arquivo por vez onde a sobrecarga de subprocesso dominaria, e uma falha de extração ali é imediatamente visível ao agente.

Indexação Multi-Branch (Opcional)

tokensave pode opcionalmente manter um grafo de código separado por branch git. Quando habilitado, trocar de branch nunca dá resultados desatualizados e nunca reindexa arquivos que você já analisou em outro branch. O rastreamento multi-branch é opt-in -- sem ele, tokensave usa um único banco de dados para todos os branches.

Como funciona

Quando você rastreia um branch, tokensave copia o banco de dados ancestral mais próximo e sincroniza apenas os arquivos que diferem. Isso significa que rastrear um branch de feature a partir de main é quase instantâneo -- apenas analisa os arquivos que você alterou.

Comandos 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

Ferramentas MCP entre branches

Três ferramentas MCP permitem consultas entre branches sem trocar seu checkout:

• tokensave_branch_search -- busca símbolos no grafo de outro branch
• tokensave_branch_diff -- compara grafos de código entre dois branches: símbolos adicionados, removidos e alterados (assinatura diferente). Suporta filtros de arquivo e tipo.
• tokensave_branch_list -- lista branches rastreados com tamanhos de banco de dados, branch pai e tempos de sincronização

Fallback de branch

Quando o servidor MCP não encontra um banco de dados para o branch atual, ele atende a partir do banco de dados do branch ancestral mais próximo e inclui um aviso em cada resposta de ferramenta sugerindo que você execute tokensave branch add.

Rastreamento automático de branch (v7.3.0)

Uma vez que o modo multi-branch é inicializado (um primeiro tokensave branch add manual criou os metadados de branch), novos branches podem ser rastreados automaticamente em vez de cair no banco de dados ancestral. Dois mecanismos independentes cobrem isso; projetos em modo de banco único nunca são afetados, e nenhum mecanismo jamais toca o banco de dados do branch padrão. Git hook (no checkout de branch). O hook post-checkout que o tokensave install configura reconhece um checkout de branch (em oposição a um checkout de arquivo) e executa o tokensave branch add em segundo plano. Esse comando não faz nada quando o branch já é rastreado ou é o branch padrão, então a alternância comum entre branches conhecidos não custa nada. O checkout inicial de um git clone novo e de um git worktree add novo também é um checkout de branch, e pode cair em um branch que não é o padrão (git clone -b feature, git worktree add -b feature); nesse caso, o hook executa o tokensave init primeiro e o tokensave branch add depois, nessa ordem. Um hook escrito por uma versão anterior mantém o corpo com o qual foi instalado — o instalador nunca reescreve um existente — então, nessas instalações, um worktree novo ainda precisa do auto_track abaixo, ou de um tokensave branch add manual.

Auto-rastreamento na abertura (opt-in). Quando o TokenSave::open é executado — comando CLI ou início do servidor MCP — e o branch ativo não é rastreado, o tokensave pode rastreá-lo na hora, copiando o DB do ancestral rastreado mais próximo e registrando-o nos metadados do branch. Isso é controlado pelo campo de configuração auto_track (padrão false) ou pela variável de ambiente TOKENSAVE_AUTO_TRACK, que substitui a configuração por execução (qualquer valor a habilita, exceto 0, false, no, off ou vazio). A cópia é a mesma cópia quase instantânea do DB ancestral que um branch add manual realiza; nenhuma sincronização é executada nesse momento — o hook post-commit mantém o DB do novo branch atualizado conforme você faz commits, ou execute o tokensave sync para atualizar imediatamente. O auto-rastreamento é estritamente de melhor esforço: qualquer falha é reportada como um aviso e o open() prossegue com o fallback usual de ancestral, então nunca pode quebrar uma chamada de ferramenta.

Em resumo: com o hook instalado, ao fazer checkout de um novo branch de feature — incluindo o branch em que um clone ou worktree novo inicia — ele ganha transparentemente seu próprio grafo por branch; com o auto_track habilitado, até um branch criado fora de um checkout é capturado na primeira vez que o tokensave abre o projeto nele.

Consulte docs/BRANCHING-USER-GUIDE.md para o guia completo.

Memória Entre Sessões

Três ferramentas MCP persistem decisões e contexto de área de código entre sessões, armazenados no .tokensave/tokensave.db por projeto.

Use estas para que o agente não precise reexplicar escolhas de arquitetura a cada sessão.

Livro-Razão de Economias

Cada chamada MCP grava uma linha somente de acréscimo no ~/.tokensave/global.db (tabela savings_ledger). Inspecione com o tokensave gain:

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

As estimativas em dólar usam o módulo de preços existente (preço de entrada do Sonnet, atualizado diariamente via LiteLLM).

Benchmark Reproduzível

O tokensave bench executa um conjunto fixo de consultas através do tokensave_context e reporta economias de recuperação em relação a uma linha de base de arquivo completo (espelha a metodologia CCE):

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

Medido neste repositório (o próprio tokensave) usando o conjunto de consultas genérico incluído:

Agregado: 88% de economia média de recuperação (142.8k → 5.5k tokens em 10 consultas).

O conjunto de consultas padrão visa padrões presentes na maioria dos codebases de aplicativos (CLIs, daemons, serviços). Execute-o no seu próprio projeto com o tokensave bench para ver seus números, ou escreva um arquivo de consulta personalizado (--queries my.toml) para uma recuperação mais precisa.

Benchmark criterion contra grandes repositórios reais

O benches/large_repos.rs é um micro-benchmark criterion que exercita as ferramentas MCP de ponta a ponta contra quatro grandes codebases de código aberto fixados em refs constantes. Cada ferramenta é acionada por pelo menos 5 consultas com argumentos (ids de nós, nomes qualificados, globs de arquivos, …) amostrados do grafo indexado uma vez por repositório, para que os tempos sejam reproduzíveis entre execuções.

Repositórios e refs fixados (definidos no benches/repos.rs):

Cada repositório é clonado superficialmente (git init + git fetch --progress --depth 1 origin <ref> + checkout FETCH_HEAD) no primeiro uso e armazenado em cache localmente; execuções subsequentes reutilizam o checkout. A saída do Git é transmitida para o terminal, para que o fetch de vários GB mostre progresso em tempo real.

Ferramentas cobertas (5 consultas cada). Ferramentas de leitura — 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. Ferramentas de escrita — str_replace, multi_str_replace, insert_at e (se o ast-grep estiver em PATH) ast_grep_rewrite.

Sincronização forçada em cada execução. Antes de qualquer benchmark disparar, o harness executa o equivalente ao tokensave sync --force em cada repositório (index_all() independentemente da frescor do .tokensave/) para que os tempos sempre reflitam a fonte fixada.

Benchmarks de escrita e limpeza. As ferramentas de escrita mutam arquivos. Para manter a pré-condição de "correspondência deve ser única", o harness usa o iter_batched do criterion — um pequeno arquivo de rascunho sob <repo>/.tokensave-bench-scratch/ é reescrito com conteúdo conhecido antes de cada iteração cronometrada, e então a ferramenta de edição é executada contra ele. Após todos os benchmarks terminarem, o harness executa o git stash --include-untracked && git stash drop dentro de cada repositório preparado para que a árvore de trabalho retorne ao ref fixado.

Configuração do criterion. O benchmark substitui os padrões do criterion para sample_size = 10 e measurement_time = 30s (vs. os 100 / 5s padrão), o que dá a cada tempo por consulta ~30 segundos de medição — suficiente para que ferramentas lentas como o tokensave_context no polkadot-sdk produzam números estáveis.

Execute:

# 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

Se o TOKENSAVE_BENCH_REPOS_DIR não estiver definido, o benchmark imprime um aviso e registra zero benchmarks (para que o cargo bench --all continue barato nas máquinas dos contribuidores).

Configuração (tudo opcional, via ambiente):

Filtrar benchmarks usa a CLI padrão do criterion — por exemplo, apenas a ferramenta search no scipy:

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

Relatórios (HTML + amostras brutas) ficam sob target/criterion/.

Para alterar os refs fixados (ex.: para uma versão mais nova ou um SHA específico), edite o REPOS no benches/repos.rs e exclua o marcador $TOKENSAVE_BENCH_REPOS_DIR/<repo>/.bench-ref correspondente para que a próxima execução busque novamente. Se você pular a limpeza pós-execução (ex.: você Ctrl-C no meio do benchmark), executar o git stash --include-untracked && git stash drop dentro de cada diretório de repositório o restaura manualmente.

Sonda de matriz de teste MCP (scripts/mcp_probe)

O scripts/mcp_probe/ é um harness Python que aciona o tokensave serve via stdio contra um conjunto configurável de repositórios reais e exercita cada ferramenta MCP somente leitura com 5 variantes de consulta por linguagem, produzindo uma tabela de status por ferramenta / por repositório. O mesmo harness serve a dois propósitos:

• Varredura de regressão. Novo suporte a linguagem, nova ferramenta ou refatoração — reexecute a matriz e qualquer célula que recém erre, expire ou retorne resultados vazios se destaca como um 🚩.
• Sonda de desempenho. Os tempos por chamada são registrados em TSV; o mesmo corpus fixo de repositórios serve como uma comparação grosseira entre versões. O bug atual do ciclo tokensave_inheritance_depth foi encontrado por este harness quando uma única ferramenta no polkadot-sdk expirou em >60 s.

Layout — o probe.py é o driver (JSON-RPC com correspondência de id, para que uma ferramenta lenta não possa envenenar chamadas subsequentes), o isolated.py reexecuta uma única ferramenta com um servidor novo por chamada (escapa do enfileiramento do servidor), o build_matrix.py lê o TSV e emite markdown, os módulos tools/<lang>.py contribuem com conjuntos de consultas por linguagem (Rust incluído; adicione Python/Go/… criando um novo módulo), o repos.toml lista os repositórios alvo (substitua via $TOKENSAVE_PROBE_REPOS).

Execução rápida:

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

As células de saída são ✓ 5/5 (limpo), 🐛 e/N (erros), ⏱ N/N (timeouts), ∅ E/N (vazio), 🐢 ok/slow (chamadas >10 s). Qualquer célula com erro ou timeout ganha um 🚩 na coluna mais à direita. O detalhe por chamada com os primeiros 100 caracteres de cada erro fica no log TSV para acompanhamento.

Diferente do benchmark criterion acima: o criterion mede a latência por iteração para um conjunto focado de ferramentas em refs fixados e produz relatórios estatísticos sob target/criterion/; o mcp_probe exercita todas as ferramentas com um conjunto de consultas mais amplo em quaisquer repositórios que você apontar, otimizando para amplitude de cobertura em vez de precisão de medição.

80+ Ferramentas MCP

O servidor expõe mais de 80 ferramentas (uma a menos quando o binário opcional ast-grep não está no PATH); as tabelas abaixo agrupam as mais comumente usadas por categoria. A maioria é somente leitura, segura para chamar em paralelo e anotada com readOnlyHint. Os primitivos de edição são limitados a arquivos únicos e reindexam no lugar; as ferramentas de linha de base de sessão e gravação de memória também mutam o estado local do .tokensave e são anotadas como não somente leitura. As três ferramentas principais (tokensave_context, tokensave_search, tokensave_status) são marcadas como anthropic/alwaysLoad para que ignorem a ida e volta da busca de ferramentas do cliente.

Consultar outro projeto inicializado

As ferramentas de leitura semântica podem consultar um grafo local explicitamente selecionado sem reiniciar o servidor MCP:

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

Os resultados selecionados incluem proveniência canônica de raiz/branch. Os IDs de nós são namespaced para aquele grafo, e os seletores correspondentes devem ser repetidos em chamadas de acompanhamento. Por exemplo, um acompanhamento a uma consulta selecionada por branch inclui ambos os valores:

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

O graph_root deve ser a raiz absoluta exata de um projeto já inicializado. O graph_branch é opcional e, quando fornecido, deve nomear um branch rastreado. As aberturas selecionadas são somente leitura: elas nunca inicializam, sincronizam, migram, rastreiam automaticamente ou gravam dados de grafo/fonte. Elas também não contribuem para a contabilidade de economias. Chamadas sem seletores se comportam exatamente como antes. graph_root só é útil se você souber que o outro projeto existe, então o servidor informa: projetos inicializados que estão diretamente ao lado da raiz servida são nomeados no MCP instructions, em tokensave_status, e em resultados vazios de tokensave_search / tokensave_context — o ponto em que uma sessão concluiria que um símbolo não existe em vez de olhar ao lado (#375). Apenas irmãos imediatos são oferecidos, no máximo cinco, e nada é aberto ou indexado em nome deles; consultar um ainda exige um graph_root explícito.

Seletores estão intencionalmente indisponíveis em ferramentas que escrevem, executam comandos externos ou dependem do checkout atual: as primitivas de edição, ferramentas de VCS e branch, diagnóstico e execução de testes, introspecção de dependências e runtime, ferramentas de workflow e memória de sessão, a ferramenta de cache persistente (tokensave_redundancy), e administração do servidor. Essas ferramentas rejeitam um seletor em vez de ignorá-lo silenciosamente.

Descoberta

Artefatos não-código

tokensave_files cobre mais do que código-fonte. Arquivos cuja extensão está listada em artifact_extensions (.feature, .json, .yaml, .yml, .sql, .toml, .proto, .graphql, .md por padrão) são rastreados por caminho, então perguntas como "onde estão os arquivos .feature para o fluxo de login?" têm uma resposta de grafo em vez de um find bloqueado (#323). Eles nunca são analisados e não contribuem com símbolos; kind: "artifact" e kind: "code" filtram entre os dois, e análises que significam "código" os excluem. Uma extensão já tratada por um extrator de linguagem é ignorada nesta lista, então não pode ser usada para impedir que uma linguagem seja analisada.

A lista também decide o que a busca literal pode examinar (#442). Uma busca literal (literal: true) sobre tokensave_search lê bytes em vez de símbolos, então não precisa de parser — mas itera os arquivos indexados, então só pode alcançar um arquivo para o qual o índice tenha uma linha. Um template .html rastreado ou uma folha de estilo .css não tem extrator nem entrada de artefato padrão, então suas correspondências estão ausentes; adicione a extensão aqui e execute tokensave sync -f e suas linhas serão pesquisadas como qualquer outra, relatadas com enclosing: null já que não há contexto de símbolo. Uma resposta literal que não conseguiu alcançar todos os arquivos rastreados informa isso em um bloco unscanned nomeando a contagem e as extensões, então uma resposta parcial nunca é apresentada como completa.

Grafo de Chamadas e Impacto

Qualidade de Código

Análises de Saúde do Código

Cinco ferramentas revelam sinais de qualidade estrutural a partir do grafo existente. A pontuação composta usa uma média geométrica sobre dimensões independentes, então nenhuma delas pode ser manipulada isoladamente.

Sessões

Capture métricas de saúde no início de uma sessão de codificação com IA, depois compare no final para ver o que melhorou ou regrediu.

Primitivas de Edição

Quatro ferramentas de escrita que permitem que agentes modifiquem arquivos sem riscos de regex ou aspas de shell. Cada uma é de arquivo único, ancorada e aciona uma reindexação no local após a escrita, para que o grafo nunca fique desatualizado.

Git e Fluxo de Trabalho

Sistema de Tipos

Portabilidade

Multi-Branch

Recursos MCP

Quatro recursos são expostos via resources/list e resources/read:

• tokensave://status — estatísticas do grafo como JSON
• tokensave://files — árvore de arquivos indexados agrupada por diretório
• tokensave://overview — resumo do projeto com distribuição de linguagens e tipos de símbolos
• tokensave://branches — branches rastreadas com tamanhos de banco de dados e informações do pai

Rastreamento de Tokens

tokensave mede os tokens que economiza em cada chamada de ferramenta MCP. Cada resposta de ferramenta inclui uma linha tokensave_metrics: before=N after=M mostrando quantos tokens de arquivo bruto foram evitados por aquela chamada específica.

Desativando o relatório. A linha de métricas, junto com uma frase no MCP instructions, pede que o agente relate as economias a você — o que significa que o modelo gasta tokens de saída narrando uma economia que tokensave fez em tokens de entrada. Tokens de saída são o tipo mais caro, então se seu agente mencionar tokensave em quase todas as interações, essa narração pode anular o ganho (#356). Defina report_savings como false em .tokensave/config.json, ou a variável de ambiente TOKENSAVE_REPORT_SAVINGS para sobrescrever por execução (qualquer valor a ativa, exceto 0, false, no, off ou vazio). Tanto a linha de métricas quanto a instrução desaparecem; tokensave install também para de escrever a regra de relatório em arquivos de prompt do agente. A medição não é afetada de qualquer forma — cada chamada ainda entra no registro de economias, então tokensave gain, tokensave list, status e monitor continuam relatando exatamente como antes. O padrão permanece true.

Observabilidade de custos

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

Analisa transcrições de sessão do Claude Code (~/.claude/projects/**/*.jsonl), classifica cada interação de API em uma de 13 categorias de tarefa, calcula o custo em dólares usando preços de modelos e armazena resultados em ~/.tokensave/global.db para consultas agregadas rápidas. Os preços são atualizados a partir do LiteLLM a cada 24 horas e recorrem a uma tabela embutida quando offline.

O cabeçalho tokensave status inclui uma linha de custo mostrando o gasto de hoje, o total de 7 dias e a taxa de eficiência (tokens economizados / tokens totais). A TUI tokensave monitor mostra um painel de custo ao vivo junto com o feed de economias. Ao final de cada sessão do Claude Code, o manipulador hook_stop imprime um recibo de uma linha no terminal.

Categorias de classificação de tarefas: Codificação, Depuração, Desenvolvimento de Recursos, Refatoração, Testes, Exploração, Planejamento, Delegação, Operações Git, Build/Deploy, Brainstorming, Conversa, Geral. A classificação é determinística (correspondência de padrões em nomes de ferramentas e comandos Bash), não requer chamadas de LLM e é adaptada do AgentSeal/codeburn.

Monitor ao vivo

tokensave monitor

Uma TUI global que mostra chamadas de ferramentas MCP de todos os projetos em tempo real, via um buffer circular compartilhado mapeado em memória em ~/.tokensave/monitor.mmap. Cada entrada mostra o nome do projeto, nome da ferramenta e delta de tokens. Um painel de custo no topo mostra o gasto de hoje, economias, eficiência e modelo principal (atualizado a cada 30 segundos).

Diagnósticos de memória

tokensave memory [--clean]

Um relatório de memória abrangente da máquina para cada processo do tokensave (servidores MCP, sincronizações, execuções de índice), via uma tabela compartilhada mapeada em memória em ~/.tokensave/memory.mmap. Cada instância faz auto-amostragem do seu RSS da melhor forma possível na inicialização, a cada chamada de ferramenta MCP, e em torno das fases de sincronização/resolução, para que o relatório mostre o RSS atual e o pico com a fase que produziu o pico — os dados necessários para atribuir o uso elevado de memória (veja #253). As linhas são sinalizadas como alive, dead (um processo morto por OOM deixa seu pico/fase para trás como um registro forense), ou orphan (ainda em execução, mas reparentado para o init). --clean limpa slots mortos.

PEAK PHASE nomeia a maior amostra, portanto é tão preciso quanto a amostragem. Sincronizações incrementais registram, em ordem: sync:extract, sync:resolve:load_nodes, sync:resolve:build_caches, sync:resolve:refs, sync:variants, sync:done. Um índice completo registra index:extract, index:resolve:build_caches, index:resolve:refs, index:resolve:done, index:insert, index:done.

Cada um é registrado após o trabalho que nomeia. Antes, eram registrados antes do trabalho, então cada amostra reportava o RSS da etapa anterior sob o rótulo da próxima etapa — o que atribuía 73 MiB ao carregamento de nós que na verdade pertenciam ao carregamento das referências não resolvidas, uma etapa sem nenhuma amostra, e apontava uma investigação de memória para o subsistema errado por meses (#409). Se você adicionar uma fase, faça a amostragem após o trabalho, não antes, e adicione uma para qualquer etapa grande o suficiente para conter o pico.

Contadores de sessão e tempo de vida

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 renderiza as estatísticas do índice do projeto, a distribuição de linguagens, a linha de custo (hoje / 7d / eficiência) e os totais de tempo de vida do projeto e mundial:

Contador mundial

Todos os usuários do tokensave contribuem para um contador agregado anônimo. tokensave status mostra tanto o total do seu projeto quanto o total mundial. O upload envia apenas um único número (ex.: 4823) sem informações de identificação. Opte por não participar com tokensave disable-upload-counter.

Frescor do Índice

O tokensave mantém o grafo atualizado sem um daemon em segundo plano ou um observador de arquivos em nível de sistema operacional.

Verificação de desatualização sob demanda. Cada chamada de ferramenta MCP verifica se algum arquivo indexado foi modificado desde a última sincronização. Se arquivos desatualizados forem encontrados, eles são reextraídos antes que a resposta da ferramenta seja retornada. Um intervalo de espera de 30 segundos impede que chamadas consecutivas revistam a árvore a cada tecla pressionada.

Sincronização de recuperação na conexão. Quando o servidor MCP inicia, ele imediatamente executa uma sincronização de recuperação não bloqueante que captura quaisquer alterações feitas enquanto nenhum agente estava anexado — um git pull, uma edição de IDE, uma etapa de build — para que a primeira chamada de ferramenta de uma sessão veja um índice atualizado.

Trabalho multiagente e worktrees git. Quando vários agentes trabalham no mesmo projeto simultaneamente, a suposição forte é que cada agente opera em sua própria worktree git. Worktrees são checkouts independentes do sistema de arquivos do mesmo repositório: o agente A e o agente B têm cada um sua própria cópia de cada arquivo, então nunca sobrescrevem as edições em andamento um do outro. O tokensave detecta automaticamente quando uma consulta vem de uma worktree aninhada dentro do checkout principal e serve resultados do grafo de branch correto. As alterações se acumulam independentemente e são eventualmente reconciliadas via git merge ou rebase — o mesmo processo usado para qualquer outro desenvolvimento paralelo. Este design evita a complexidade e os modos de falha de bloqueio entre agentes sobre um diretório mutável compartilhado.

Fluxos de trabalho somente CLI. Se você executar comandos tokensave sem um agente anexado (sem servidor MCP), a verificação de desatualização não está em execução entre comandos. Instale hooks git para manter o índice atualizado automaticamente após cada commit ou clone:

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

Atualizando da versão 5.x

O comando autônomo tokensave daemon e seu autostart via launchd/systemd/Serviço do Windows foram removidos na versão 6.0.0. O observador de arquivos embutido em nível de sistema operacional que substituiu o daemon foi ele próprio removido na versão 6.1.1 (causava CPU e memória descontrolados em grandes monorepos com árvores profundas de node_modules ou target). O modelo de desatualização sob demanda acima é o design atual.

Se você ainda tiver um autostart de daemon da versão 5.x, remova-o:

• 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 (de um terminal elevado)

Se você não se lembrar do nome exato: launchctl list | grep tokensave / systemctl --user list-units | grep tokensave / sc.exe query state= all | findstr -i tokensave.

Auto-Atualização

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 baixa o binário correto da plataforma dos lançamentos do GitHub e substitui o binário em execução no local. Suporta canais estável e beta independentemente.

Versionamento e atualizações

Os números de versão do tokensave parecem SemVer, mas não o seguem: o componente que muda codifica a manutenção que a atualização requer, que o tokensave executa automaticamente no próximo lançamento — você nunca executa uma reinstalação ou reindexação manualmente.

Reinstalação global. Na primeira execução de um novo build menor ou maior, o tokensave silenciosamente reexecuta install para cada agente que registrou, para que a configuração do agente sempre aponte para o binário atual e exponha o conjunto atual de ferramentas. Bumps de patch pulam isso — o marcador de versão em execução é simplesmente avançado.

A reinstalação é genuinamente silenciosa: a saída de configuração por agente que você vê de um tokensave install explícito é suprimida aqui, então nunca aparece na frente de um tokensave init ou tokensave sync comum. Se a configuração de um agente não puder ser atualizada — o aplicativo não está instalado, ou sua configuração está em um local somente leitura — você recebe uma linha nomeando os agentes que falharam:

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

Execute tokensave install para ver o erro subjacente. Os marcadores de versão avançam de qualquer forma, então um caminho de configuração que nunca pode ser gravado é relatado uma vez por atualização em vez de ser tentado novamente em cada comando subsequente.

Reindexação forçada por projeto (somente maior). Um bump maior significa que os índices do projeto devem ser reconstruídos. O tokensave faz isso de forma preguiçosa e por projeto: na primeira chamada de ferramenta MCP em um projeto após uma atualização maior, ele gera uma reindexação completa em segundo plano (equivalente a tokensave sync --force) que nunca bloqueia a resposta da ferramenta.

Fallback Brew / cargo. Atualizações externas que substituem o binário fora de tokensave upgrade — brew upgrade tokensave ou cargo install tokensave — são detectadas da mesma forma: se a versão em execução for mais nova que a última versão que executou uma instalação, a reinstalação é executada no próximo lançamento, assim como após uma auto-atualização.

Veja TOKENSAVE-VERSIONING.md para saber por que o tokensave diverge do SemVer (codificar manutenção na versão é o que torna atualizações sem intervenção possíveis), a mecânica dos marcadores, a versão independente do esquema do banco de dados e as regras do mantenedor para cortar lançamentos.

Referência da 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

Execute uma verificação de saúde abrangente da sua instalação do tokensave:

tokensave doctor

Verificações: localização do binário, índice do projeto, banco de dados global, configuração do usuário, integração do agente (servidor MCP, hooks, permissões, regras de prompt) e conectividade de rede. Se alguma permissão de ferramenta estiver faltando após uma atualização, ele informa para você executar tokensave install. Use --agent para verificar apenas um agente específico.

O Doctor também valida que cada hook instalado usa o subcomando correto do tokensave e auto-repara hooks quebrados.

Como Funciona com o Claude Code

Uma vez configurado, o Claude Code usa automaticamente o tokensave em vez de ler arquivos brutos quando precisa entender seu código. Três camadas se reforçam mutuamente:

O resultado: o Claude obtém o mesmo entendimento de código com muito menos tokens. Um agente Explore típico lê 20-50 arquivos; o tokensave retorna os símbolos, relacionamentos e trechos de código relevantes do seu índice pré-construído.

Chamadas de Rede e Privacidade

A funcionalidade principal do tokensave (indexação, busca, consultas de grafo, servidor MCP) é 100% local — seu código nunca sai da sua máquina.

O upload do contador mundial envia um único POST HTTP com um corpo JSON como {"amount": 4823}. Sem cookies, sem rastreamento, sem ID de usuário. O Cloudflare Worker registra o país do seu endereço IP (derivado dos cabeçalhos da requisição) para estatísticas geográficas agregadas — seu endereço IP real não é armazenado.

A atualização de preços de modelo busca um arquivo JSON público do GitHub (raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json) para manter os preços dos modelos Claude atualizados para tokensave cost. Nenhum dado é enviado — é um GET HTTPS simples. A resposta é armazenada em cache em ~/.tokensave/pricing.json por 24 horas. Se a busca falhar, o tokensave usa sua tabela de preços compilada.

Mais de 50 Linguagens

O tokensave suporta mais de 50 linguagens de programação organizadas em três níveis controlados por flags de recursos do Cargo. Cada nível inclui todas as linguagens do nível abaixo dele. Cabeçalhos de Markdown são extraídos como nós Module com arestas hierárquicas Contains para que a estrutura do documento participe das consultas de grafo junto com o código-fonte.

Lite -- --no-default-features

Sempre compilado. O menor binário para as linguagens mais populares, além de Svelte e Astro (extração de bloco de script via o extrator TypeScript, sem dependência extra de gramática).

Médio (Lite + 9 mais) -- --features medium

Completo (Médio + todo o resto) -- padrão

Linguagens individuais também podem ser selecionadas manualmente sem um nível completo:

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

Todos os extratores compartilham a mesma profundidade: funções, classes, métodos, campos, imports, grafos de chamada, cadeias de herança, docstrings, métricas de complexidade, extração de decoradores/anotações e rastreamento de dependências entre arquivos.

tokensave vs CodeGraph

tokensave é uma reescrita em Rust do CodeGraph (Node.js/TypeScript) feita do zero. Ambos constroem grafos de código semânticos para agentes de codificação de IA, mas divergem significativamente em escopo e capacidades.

O CodeGraph foi pioneiro na abordagem e continua sendo uma escolha sólida se você prefere ferramentas npm e só precisa da integração com Claude Code. tokensave estende o conceito com análise mais profunda, mais agentes, suporte multi-branch e um binário nativo sem dependências de runtime.

Para comparações detalhadas contra CodeGraph, Dual-Graph (GrapeRoot), code-review-graph e OpenWolf, veja docs/COMPARABLE-TOOLS.md.

Por que tokensave em vez das Alternativas

Várias ferramentas reduzem o uso de tokens para agentes de codificação de IA. Aqui está o porquê de tokensave se destacar.

Binário nativo único, zero dependências

Toda alternativa exige um runtime: Python, Node.js ou ambos. tokensave é distribuído como um único binário Rust de ~25 MB com todas as 50+ gramáticas tree-sitter incluídas. Nada mais para instalar.

Inteligência de código mais profunda

tokensave trabalha no nível de símbolos: funções, structs, campos, arestas de chamada, hierarquias de tipos, métricas de complexidade. Alternativas como Dual-Graph (GrapeRoot) trabalham no nível de arquivos -- elas sabem quais arquivos existem, mas não conseguem responder "quem chama esta função?" ou "o que quebra se eu mudar este struct?" As 80+ ferramentas MCP especializadas do tokensave cobrem travessia de grafo de chamadas, análise de impacto, detecção de código morto, mapeamento de testes, pré-visualização de renomeação, hierarquias de tipos, detecção de dependências circulares, classificação de complexidade, análises de saúde do código (Gini, DSM, profundidade de dependência, lacunas de teste ponderadas por risco), primitivas de edição atômicas e mais. O concorrente mais próximo (code-review-graph) tem 22 ferramentas; outros têm 5-9.

Suporte mais amplo a agentes

Mais de uma dúzia de integrações com agentes de codificação de IA com formatos de configuração nativos por agente. Nenhuma outra ferramenta cobre tantos agentes com uma integração tão profunda. Claude Code recebe hooks, regras de prompt e permissões de ferramentas auto-permitidas. Kiro recebe configuração MCP global, direcionamento tokensave.md carregado como recurso, um agente gerenciado com aprovação de ferramentas permissiva integrada/tokensave, e hooks para guardrails de delegação além de sincronização pós-escrita. Outros agentes recebem registro de servidor MCP em seu formato de configuração nativo.

Indexação multi-branch

A única ferramenta neste espaço com bancos de dados de grafo por branch opcionais e diff e busca entre branches. Quando habilitado, alternar branches é instantâneo -- sem necessidade de reindexação.

Rastreamento de tokens por chamada

A única ferramenta que relata exatamente quantos tokens cada chamada individual de ferramenta MCP economizou, além de um monitor TUI ao vivo em todos os projetos e contadores vitalícios.

Totalmente open source

Rust licenciado sob MIT, auditável de ponta a ponta. O mecanismo central do Dual-Graph (graperoot no PyPI) é proprietário -- você não pode ver o que ele faz com seu grafo de código. OpenWolf é AGPL-3.0, o que exige que trabalhos derivados sejam open-sourced.

Performance

Benchmark de índice completo em uma base de código mista Rust/Java/Scala de 1.782 arquivos (57K nós, 103K arestas):

Solução de problemas

"tokensave not initialized"

O diretório .tokensave/ não existe no seu projeto.

tokensave init

Servidor MCP não conectando

O agente de IA não vê as ferramentas do tokensave.

1. Garanta que a configuração do agente inclua o servidor MCP do tokensave (execute tokensave doctor)
2. Reinicie o agente completamente
3. Verifique se tokensave está no seu PATH: which tokensave

Símbolos ausentes na busca

• Execute tokensave sync para atualizar o índice
• Verifique se a linguagem é suportada (veja a tabela acima)
• Verifique se o arquivo não está excluído por .gitignore

Indexação lenta

Projetos grandes demoram mais no primeiro índice completo.

• Execuções subsequentes usam sincronização incremental e são muito mais rápidas
• Use tokensave sync (não --force) para atualizações do dia a dia
• A desatualização é verificada automaticamente em cada chamada de ferramenta MCP enquanto um agente está conectado

Desabilitando tokensave para projetos específicos

Se um projeto for grande demais e tokensave usar RAM demais, você pode desabilitar o servidor MCP por projeto definindo TOKENSAVE_DISABLE_SERVER=true no ambiente dele. O servidor sai limpo sem inicializar.

Claude Code — adicione ao .claude/settings.json do seu projeto:

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

Outros agentes — defina a variável de ambiente em qualquer configuração que seu agente use para iniciar servidores MCP.

Você também pode defini-la globalmente via shell (TOKENSAVE_DISABLE_SERVER=true claude), mas isso desabilita o servidor MCP do tokensave para todos os projetos na sessão.

DISABLE_TOKENSAVE=true continua suportado como um alias de compatibilidade obsoleto para configurações criadas antes desta variável ser namespaced.

Origem

Este projeto é uma porta em Rust da implementação original em TypeScript do CodeGraph por @colbymchenry. A porta mantém a mesma arquitetura e interface de ferramentas MCP enquanto aproveita Rust para performance e bindings nativos de tree-sitter.

Building

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

Histórico de Estrelas

Patrocinadores

Assinatura de código gratuita no Windows fornecida por SignPath.io, certificado por SignPath Foundation

Licença

Licença MIT -- veja LICENSE para detalhes.

tokensave.dev