tokensave

Inteligencia Semántica de Código para Agentes de Codificación con IA

Menos tokens • Menos llamadas a herramientas • 100% local

¿Por qué tokensave?

Los agentes de codificación con IA desperdician tokens explorando bases de código. Cada grep, glob y lectura de archivo cuesta dinero. En tareas complejas, los agentes generan múltiples subagentes de Exploración que escanean cientos de archivos solo para construir contexto.

tokensave les da a los agentes un grafo de conocimiento semántico preindexado. En lugar de escanear archivos, el agente consulta el grafo y obtiene respuestas estructuradas al instante: los símbolos correctos, sus relaciones y el código fuente, en una sola llamada.

Cómo 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       │                       │
│              └───────────────────────┘                       │
└──────────────────────────────────────────────────────────────┘

Sin tokensave: Los agentes usan grep, glob y Read para escanear archivos: muchas llamadas a la API, alto uso de tokens.

Con tokensave: Los agentes consultan el grafo mediante herramientas MCP: resultados instantáneos, procesamiento local, menos tokens.

Características Clave

Inicio Rápido

1. Instalación

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 (cualquier 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)

Binarios precompilados (Linux, Windows, macOS):

Descarga desde la última versión y coloca el binario en tu PATH.

2. Configura tu 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 registra su servidor MCP en el formato de configuración nativo. Claude Code además recibe un hook PreToolUse (bloquea agentes de Exploración derrochadores), un hook UserPromptSubmit, un hook Stop, reglas de prompt en CLAUDE.md y permisos de herramientas auto-permitidos. Kiro recibe configuración MCP global, tokensave.md de dirección cargado como recurso y un agente predeterminado gestionado por tokensave con aprobación permisiva de herramientas integradas/tokensave, hooks de salvaguarda de delegación y sincronización posterior a escritura; los agentes Kiro gestionados por el usuario se conservan.

Las instalaciones globales de OMP apuntan al perfil reportado por omp config path puro, escribiendo <resolved-agent-dir>/mcp.json y <resolved-agent-dir>/rules/tokensave.md. Exporta OMP_PROFILE o el PI_PROFILE compatible de OMP al instalar en un perfil con nombre; el resolvedor de OMP también honra PI_CONFIG_DIR y PI_CODING_AGENT_DIR. Tokensave confía en ese resolvedor nativo en lugar de duplicar la lógica de perfiles de OMP. Tokensave instala MCP y reglas de asesoramiento para OMP; no instala la aplicación de hooks de OMP.

Todos los cambios son idempotentes: es seguro ejecutarlos de nuevo después de actualizar. Después de la configuración del agente, se te ofrecerán hooks globales de git post-commit y post-checkout. tokensave uninstall elimina esos hooks junto con las integraciones de agentes; pasa --keep-git-hooks para dejarlos, o adminístralos por separado con tokensave githooks.

Instalación local al proyecto

Por defecto, tokensave install registra el servidor MCP en tu configuración de agente global (p. ej., ~/.claude.json). Para registrar tokensave solo para el proyecto actual, añade --local:

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

Esto escribe configuración con alcance de proyecto que puedes confirmar y compartir con tu equipo. Para Claude eso es ./.mcp.json, ./.claude/settings.json y ./CLAUDE.md; OMP usa ./.omp/mcp.json y ./.omp/rules/tokensave.md sin invocar la CLI de OMP. Agentes compatibles: claude, cursor, droid, gemini, zed, opencode, roo-code, kiro, auggie, omp, plank (cada uno escribe su propio archivo de proyecto, p. ej., .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). Otros agentes no tienen configuración con alcance de proyecto y reportan un error con --local.

Elimina una instalación local al proyecto con tokensave uninstall --local.

3. Indexa tu proyecto

cd /path/to/your/project
tokensave init

Esto crea un directorio .tokensave/ con la base de datos del grafo de conocimiento. La inicialización y la sincronización son comandos separados: init es un opt-in único por proyecto, mientras que sync solo actualiza proyectos que ya fueron inicializados. Esto evita que los hooks globales de git creen bases de datos silenciosamente en repos que nunca tuviste la intención de indexar. Después de init, usa tokensave sync para actualizar incrementalmente: solo se reindexan los archivos cambiados.

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

Sincronización Resiliente a Fallos

Las gramáticas tree-sitter son código C/C++ compilado. Ocasionalmente alcanzan una aserción interna o terminan el proceso por rutas que el manejo de pánico de Rust no puede interceptar. A partir de v4.3.0, cada archivo se analiza dentro de un subproceso trabajador de corta duración: si una gramática causa un segfault, llama a abort() o alcanza un desbordamiento de pila, solo muere el trabajador. El pool lo reinicia, el archivo infractor se registra y se omite, y sync continúa.

El trabajador es un subcomando oculto extract-worker autenticado contra el padre mediante un token de 256 bits por generación, requerido tanto como variable de entorno TOKENSAVE_WORKER_TOKEN como los primeros 32 bytes recibidos en stdin. La invocación directa por usuarios falla. El valor predeterminado es available_parallelism() trabajadores; opta por no participar con TOKENSAVE_DISABLE_SUBPROCESS=1.

Las primitivas de edición (tokensave_str_replace, tokensave_insert_at, etc.) aún se ejecutan en proceso: apuntan a un archivo a la vez donde la sobrecarga de subprocesos dominaría, y un fallo del extractor allí es inmediatamente visible para el agente.

Indexación Multi-Rama (Opcional)

tokensave puede mantener opcionalmente un grafo de código separado por rama de git. Cuando está habilitado, cambiar de rama nunca te da resultados obsoletos y nunca reindexa archivos que ya analizaste en otra rama. El seguimiento multi-rama es opt-in: sin él, tokensave usa una sola base de datos para todas las ramas.

Cómo funciona

Cuando rastreas una rama, tokensave copia la base de datos del ancestro más cercano y sincroniza solo los archivos que difieren. Esto significa que rastrear una rama de características desde main es casi instantáneo: solo analiza los archivos que has cambiado.

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

Herramientas MCP entre ramas

Tres herramientas MCP permiten consultas entre ramas sin cambiar tu checkout:

• tokensave_branch_search -- busca símbolos en el grafo de otra rama
• tokensave_branch_diff -- compara grafos de código entre dos ramas: símbolos añadidos, eliminados y cambiados (la firma difiere). Admite filtros de archivo y tipo.
• tokensave_branch_list -- lista ramas rastreadas con tamaños de base de datos, rama padre y tiempos de sincronización

Respaldo de rama

Cuando el servidor MCP no puede encontrar una base de datos para la rama actual, sirve desde la base de datos de la rama ancestro más cercana e incluye una advertencia en cada respuesta de herramienta sugiriendo que ejecutes tokensave branch add.

Seguimiento automático de ramas (v7.3.0)

Una vez que el modo multi-rama está inicializado (un primer tokensave branch add manual creó los metadatos de rama), las nuevas ramas se pueden rastrear automáticamente en lugar de recurrir a la base de datos del ancestro. Dos mecanismos independientes cubren esto; los proyectos en modo de base de datos única nunca se ven afectados, y ningún mecanismo toca jamás la base de datos de la rama predeterminada. Git hook (al cambiar de rama). El hook post-checkout que configura tokensave install reconoce un checkout de rama (a diferencia de un checkout de archivo) y ejecuta tokensave branch add en segundo plano. Ese comando no hace nada cuando la rama ya está rastreada o es la rama predeterminada, por lo que cambiar entre ramas conocidas no cuesta nada. El checkout inicial de un git clone nuevo y de un git worktree add nuevo también es un checkout de rama, y puede aterrizar en una rama que no sea la predeterminada (git clone -b feature, git worktree add -b feature); allí el hook ejecuta tokensave init primero y tokensave branch add después, en ese orden. Un hook escrito por una versión anterior conserva el cuerpo con el que se instaló (el instalador nunca reescribe uno existente), por lo que en esas instalaciones un worktree nuevo aún necesita auto_track a continuación, o un tokensave branch add manual.

Auto-rastreo al abrir (opt-in). Cuando se ejecuta TokenSave::open (comando CLI o inicio del servidor MCP) y la rama activa no está rastreada, tokensave puede rastrearla en el momento copiando la base de datos del ancestro rastreado más cercano y registrándola en los metadatos de la rama. Esto está controlado por el campo de configuración auto_track (predeterminado false) o la variable de entorno TOKENSAVE_AUTO_TRACK, que anula la configuración por ejecución (cualquier valor lo habilita excepto 0, false, no, off o vacío). La copia es la misma copia casi instantánea de la base de datos del ancestro que realiza un branch add manual; no se ejecuta ninguna sincronización en ese momento: el hook post-commit mantiene la base de datos de la rama nueva actualizada mientras haces commits, o ejecuta tokensave sync para actualizarla de inmediato. El auto-rastreo es estrictamente de mejor esfuerzo: cualquier fallo se reporta como advertencia y open() continúa con el respaldo habitual del ancestro, por lo que nunca puede romper una llamada de herramienta.

En resumen: con el hook instalado, al hacer checkout de una rama de funcionalidad nueva (incluida la rama en la que comienza un clon o worktree nuevo) se le otorga de forma transparente su propio grafo por rama; con auto_track habilitado, incluso una rama creada fuera de un checkout se detecta la primera vez que tokensave abre el proyecto en ella.

Consulta docs/BRANCHING-USER-GUIDE.md para la guía completa.

Memoria entre sesiones

Tres herramientas MCP persisten decisiones y contexto de áreas de código entre sesiones, almacenados en el .tokensave/tokensave.db por proyecto.

Úsalas para que el agente no tenga que reexplicar las decisiones de arquitectura sesión tras sesión.

Registro de ahorros

Cada llamada MCP escribe una fila de solo añadido en ~/.tokensave/global.db (tabla savings_ledger). Inspecciónalo con tokensave gain:

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

Las estimaciones en dólares usan el módulo de precios existente (precios de entrada de Sonnet, actualizados diariamente vía LiteLLM).

Benchmark reproducible

tokensave bench ejecuta un conjunto fijo de consultas a través de tokensave_context y reporta ahorros de recuperación frente a una línea base de archivo completo (refleja la metodología CCE):

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

Medido contra este repositorio (el propio tokensave) usando el conjunto de consultas genérico incluido:

Agregado: 88% de ahorro medio de recuperación (142.8k → 5.5k tokens en 10 consultas).

El conjunto de consultas predeterminado apunta a patrones presentes en la mayoría de los codebases de aplicaciones (CLIs, daemons, servicios). Ejecútalo en tu propio proyecto con tokensave bench para ver tus números, o escribe un archivo de consultas personalizado (--queries my.toml) para una recuperación más precisa.

Benchmark criterion contra repositorios grandes del mundo real

benches/large_repos.rs es un micro-benchmark de criterion que ejercita las herramientas MCP de extremo a extremo contra cuatro codebases de código abierto grandes fijados en refs constantes. Cada herramienta se impulsa con al menos 5 consultas con argumentos (ids de nodos, nombres calificados, globs de archivos, …) muestreados del grafo indexado una vez por repositorio, por lo que los tiempos son reproducibles entre ejecuciones.

Repositorios y refs fijados (definidos en benches/repos.rs):

Cada repositorio se clona superficialmente (git init + git fetch --progress --depth 1 origin <ref> + checkout FETCH_HEAD) en el primer uso y se cachea localmente; las ejecuciones posteriores reutilizan el checkout. La salida de Git se transmite al terminal para que la descarga de varios GB muestre progreso en tiempo real.

Herramientas cubiertas (5 consultas cada una). Herramientas de lectura: 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. Herramientas de escritura: str_replace, multi_str_replace, insert_at y (si ast-grep está en PATH) ast_grep_rewrite.

Sincronización forzada en cada ejecución. Antes de que se dispare cualquier benchmark, el arnés ejecuta el equivalente de tokensave sync --force en cada repositorio (index_all() independientemente de la frescura de .tokensave/) para que los tiempos siempre reflejen el código fuente fijado.

Benchmarks de escritura y limpieza. Las herramientas de escritura mutan archivos. Para mantener la condición previa de "la coincidencia debe ser única", el arnés usa el iter_batched de criterion: un pequeño archivo de scratch bajo <repo>/.tokensave-bench-scratch/ se reescribe con contenido conocido antes de cada iteración cronometrada, y luego la herramienta de edición se ejecuta contra él. Después de que todos los benchmarks terminen, el arnés ejecuta git stash --include-untracked && git stash drop dentro de cada repositorio preparado para que el árbol de trabajo vuelva al ref fijado.

Configuración de criterion. El benchmark anula los valores predeterminados de criterion a sample_size = 10 y measurement_time = 30s (frente a los 100 / 5s estándar), lo que da a cada tiempo por consulta ~30 segundos de medición, suficiente para que herramientas lentas como tokensave_context en polkadot-sdk produzcan números estables.

Ejecútalo:

# 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

Si TOKENSAVE_BENCH_REPOS_DIR no está definido, el benchmark imprime un aviso y registra cero benchmarks (para que cargo bench --all siga siendo barato en las máquinas de los contribuidores).

Configuración (todo opcional, vía entorno):

Filtrar benchmarks usa la CLI estándar de criterion; por ejemplo, solo la herramienta search en scipy:

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

Los informes (HTML + muestras crudas) se guardan bajo target/criterion/.

Para cambiar los refs fijados (p. ej. a una versión más reciente o un SHA específico), edita REPOS en benches/repos.rs y elimina el marcador $TOKENSAVE_BENCH_REPOS_DIR/<repo>/.bench-ref correspondiente para que la próxima ejecución vuelva a descargar. Si omites la limpieza posterior a la ejecución (p. ej. haces Ctrl-C a mitad del benchmark), ejecutar git stash --include-untracked && git stash drop dentro de cada directorio de repositorio lo restaura manualmente.

Sonda de matriz de pruebas MCP (scripts/mcp_probe)

scripts/mcp_probe/ es un arnés de Python que impulsa tokensave serve sobre stdio contra un conjunto configurable de repositorios reales y ejercita cada herramienta MCP de solo lectura con 5 variantes de consulta por lenguaje, produciendo una tabla de estado por herramienta / por repositorio. El mismo arnés sirve para dos propósitos:

• Barrido de regresión. Nuevo soporte de lenguaje, nueva herramienta o refactor: vuelve a ejecutar la matriz y cualquier celda que falle, expire o devuelva resultados vacíos destaca como una 🚩.
• Sonda de rendimiento. Los tiempos por llamada se registran en TSV; el mismo corpus fijo de repositorios sirve como comparación aproximada entre versiones. El bug actual del ciclo tokensave_inheritance_depth se encontró con este arnés cuando una sola herramienta en polkadot-sdk expiró a >60 s.

Estructura — probe.py es el controlador (JSON-RPC con coincidencia de ids para que una herramienta lenta no pueda contaminar llamadas posteriores), isolated.py vuelve a ejecutar una sola herramienta con un servidor nuevo por llamada (evita la cola del servidor), build_matrix.py lee el TSV y emite markdown, los módulos tools/<lang>.py contribuyen conjuntos de consultas por lenguaje (Rust incluido; añade Python/Go/… añadiendo un módulo nuevo), repos.toml lista los repositorios objetivo (anula vía $TOKENSAVE_PROBE_REPOS).

Ejecución rápida:

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

Las celdas de salida son ✓ 5/5 (limpio), 🐛 e/N (errores), ⏱ N/N (timeouts), ∅ E/N (vacío), 🐢 ok/slow (llamadas >10 s). Cualquier celda con error o timeout recibe una 🚩 en la columna más a la derecha. El detalle por llamada con los primeros 100 caracteres de cada error se guarda en el registro TSV para seguimiento.

A diferencia del benchmark criterion anterior: criterion mide la latencia por iteración para un conjunto enfocado de herramientas en refs fijados y produce informes estadísticos bajo target/criterion/; mcp_probe ejercita cada herramienta con un conjunto de consultas más amplio en los repositorios que le indiques, optimizando la amplitud de cobertura en lugar de la precisión de medición.

Más de 80 herramientas MCP

El servidor expone más de 80 herramientas (una menos cuando el binario opcional ast-grep no está en PATH); las tablas siguientes agrupan las más usadas por categoría. La mayoría son de solo lectura, seguras de llamar en paralelo y anotadas con readOnlyHint. Las primitivas de edición están limitadas a archivos individuales y reindexan en el lugar; las herramientas de línea base de sesión y registro de memoria también mutan el estado local de .tokensave y están anotadas como no solo lectura. Las tres herramientas principales (tokensave_context, tokensave_search, tokensave_status) están marcadas como anthropic/alwaysLoad para que omitan el viaje de ida y vuelta de búsqueda de herramientas del cliente.

Consultar otro proyecto inicializado

Las herramientas de lectura semántica pueden consultar un grafo local seleccionado explícitamente sin reiniciar el servidor MCP:

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

Los resultados seleccionados incluyen procedencia canónica de raíz/rama. Los ids de nodos tienen espacio de nombres en ese grafo, y los selectores coincidentes deben repetirse en llamadas posteriores. Por ejemplo, un seguimiento de una consulta seleccionada por rama incluye ambos valores:

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

graph_root debe ser la raíz absoluta exacta de un proyecto ya inicializado. graph_branch es opcional y, cuando se proporciona, debe nombrar una rama rastreada. Las aperturas seleccionadas son de solo lectura: nunca inicializan, sincronizan, migran, auto-rastrean ni escriben datos de grafo/fuente. Tampoco contribuyen al cálculo de ahorros. Las llamadas sin selectores se comportan exactamente como antes. graph_root solo es útil si sabes que el otro proyecto existe, por lo que el servidor te lo indica: los proyectos inicializados que se encuentran directamente junto a la raíz servida se nombran en el instructions de MCP, en tokensave_status, y en resultados vacíos de tokensave_search / tokensave_context — el punto en el que una sesión concluiría que un símbolo no existe en lugar de mirar al lado (#375). Solo se ofrecen hermanos inmediatos, como máximo cinco, y no se abre ni indexa nada en su nombre; consultar uno aún requiere un graph_root explícito.

Los selectores no están disponibles intencionalmente en herramientas que escriben, ejecutan comandos externos o dependen del checkout actual: las primitivas de edición, las herramientas de VCS y ramas, el diagnóstico y la ejecución de pruebas, la introspección de dependencias y runtime, las herramientas de flujo de trabajo y memoria de sesión, la herramienta de caché persistente (tokensave_redundancy), y la administración del servidor. Esas herramientas rechazan un selector en lugar de ignorarlo silenciosamente.

Descubrimiento

Artefactos no relacionados con código

tokensave_files cubre más que el código fuente. Los archivos cuya extensión está listada en artifact_extensions (.feature, .json, .yaml, .yml, .sql, .toml, .proto, .graphql, .md por defecto) se rastrean por ruta, de modo que preguntas como "¿dónde están los archivos .feature para el flujo de inicio de sesión?" tienen una respuesta de grafo en lugar de un find bloqueado (#323). Nunca se analizan y no contribuyen símbolos; kind: "artifact" y kind: "code" filtran entre los dos, y los análisis que significan "código" los excluyen. Una extensión ya manejada por un extractor de lenguaje se ignora en esta lista, por lo que no se puede usar para evitar que un lenguaje se analice.

La lista también decide qué puede mirar la búsqueda literal (#442). Una búsqueda literal (literal: true) sobre tokensave_search lee bytes en lugar de símbolos, por lo que no necesita analizador — pero itera los archivos indexados, por lo que solo puede alcanzar un archivo para el que el índice tenga una fila. Una plantilla .html rastreada o una hoja de estilo .css no tiene ni extractor ni entrada de artefacto predeterminada, por lo que sus coincidencias faltan; agrega la extensión aquí y ejecuta tokensave sync -f y sus líneas se buscan como cualquier otra, reportadas con enclosing: null ya que no hay contexto de símbolo. Una respuesta literal que no pudo alcanzar cada archivo rastreado lo indica en un bloque unscanned que nombra el recuento y las extensiones, de modo que una respuesta parcial nunca se presenta como completa.

Grafo de llamadas e impacto

Calidad del código

Análisis de salud del código

Cinco herramientas muestran señales de calidad estructural desde el grafo existente. La puntuación compuesta usa una media geométrica sobre dimensiones independientes para que ninguna pueda ser manipulada individualmente.

Sesiones

Captura métricas de salud al inicio de una sesión de codificación de IA, luego compara al final para ver qué mejoró o empeoró.

Primitivas de edición

Cuatro herramientas de escritura que permiten a los agentes modificar archivos sin riesgos de regex o comillas de shell. Cada una es de un solo archivo, anclada y dispara un re-indexado en el lugar después de escribir para que el grafo nunca quede desactualizado.

Git y flujo de trabajo

Sistema de tipos

Portabilidad

Multi-rama

Recursos MCP

Se exponen cuatro recursos a través de resources/list y resources/read:

• tokensave://status -- estadísticas del grafo como JSON
• tokensave://files -- árbol de archivos indexados agrupado por directorio
• tokensave://overview -- resumen del proyecto con distribución de lenguajes y tipos de símbolos
• tokensave://branches -- ramas rastreadas con tamaños de BD e información del padre

Seguimiento de tokens

tokensave mide los tokens que ahorra en cada llamada de herramienta MCP. Cada respuesta de herramienta incluye una línea tokensave_metrics: before=N after=M que muestra cuántos tokens de archivo sin procesar se evitaron con esa llamada específica.

Desactivar el informe. La línea de métricas, junto con una frase en el instructions de MCP, pide al agente que informe los ahorros — lo que significa que el modelo gasta tokens de salida narrando un ahorro que tokensave hizo en tokens de entrada. Los tokens de salida son el tipo más caro, así que si tu agente menciona tokensave en casi cada turno, esa narración puede compensar la ganancia (#356). Establece report_savings a false en .tokensave/config.json, o la variable de entorno TOKENSAVE_REPORT_SAVINGS para anularlo por ejecución (cualquier valor lo habilita excepto 0, false, no, off o vacío). Tanto la línea de métricas como la instrucción desaparecen; tokensave install también deja de escribir la regla de informe en los archivos de prompt del agente. La medición no se toca de ninguna manera — cada llamada aún aterriza en el libro de ahorros, por lo que tokensave gain, tokensave list, status y monitor siguen informando exactamente como antes. El valor predeterminado sigue siendo true.

Observabilidad de costos

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

Analiza transcripciones de sesiones de Claude Code (~/.claude/projects/**/*.jsonl), clasifica cada turno de API en una de 13 categorías de tareas, calcula el costo en dólares usando precios de modelos y almacena resultados en ~/.tokensave/global.db para consultas agregadas rápidas. Los precios se actualizan desde LiteLLM cada 24 horas y recurren a una tabla integrada cuando está sin conexión.

El encabezado tokensave status incluye una fila de costos que muestra el gasto de hoy, el total de 7 días y la relación de eficiencia (tokens ahorrados / tokens totales). La TUI tokensave monitor muestra un panel de costos en vivo junto con el feed de ahorros. Al final de cada sesión de Claude Code, el manejador hook_stop imprime un recibo de una línea en la terminal.

Categorías de clasificación de tareas: Codificación, Depuración, Desarrollo de funciones, Refactorización, Pruebas, Exploración, Planificación, Delegación, Operaciones de Git, Compilación/Despliegue, Lluvia de ideas, Conversación, General. La clasificación es determinista (coincidencia de patrones en nombres de herramientas y comandos Bash), no requiere llamadas LLM y está adaptada de AgentSeal/codeburn.

Monitor en vivo

tokensave monitor

Una TUI global que muestra llamadas de herramientas MCP de todos los proyectos en tiempo real, a través de un búfer circular compartido mapeado en memoria en ~/.tokensave/monitor.mmap. Cada entrada muestra el nombre del proyecto, el nombre de la herramienta y el delta de tokens. Un panel de costos en la parte superior muestra el gasto de hoy, ahorros, eficiencia y el modelo principal (actualizado cada 30 segundos).

Diagnósticos de memoria

tokensave memory [--clean]

Un informe de memoria a nivel de máquina para cada proceso de tokensave (servidores MCP, sincronizaciones, ejecuciones de índice), a través de una tabla compartida mapeada en memoria en ~/.tokensave/memory.mmap. Cada instancia se auto-muestrea su RSS de la mejor manera posible al inicio, en cada llamada a herramienta MCP, y alrededor de las fases de sincronización/resolución, por lo que el informe muestra el RSS actual y máximo con la fase que produjo el máximo — los datos necesarios para atribuir el uso elevado de memoria (ver #253). Las filas se marcan como alive, dead (un proceso eliminado por OOM deja su máximo/fase como registro forense), o orphan (aún en ejecución pero re-parentado a init). --clean purga las ranuras muertas.

PEAK PHASE nombra la muestra más alta, por lo que solo es tan precisa como el muestreo. Las sincronizaciones incrementales registran, en orden: sync:extract, sync:resolve:load_nodes, sync:resolve:build_caches, sync:resolve:refs, sync:variants, sync:done. Un índice completo registra index:extract, index:resolve:build_caches, index:resolve:refs, index:resolve:done, index:insert, index:done.

Cada uno se registra después del trabajo que nombra. Antes se registraban antes, por lo que cada muestra reportaba el RSS del paso anterior bajo la etiqueta del siguiente paso — lo que atribuyó 73 MiB a la carga de nodos que en realidad pertenecían a la carga de las referencias no resueltas, un paso sin muestra alguna, y apuntó una investigación de memoria al subsistema equivocado durante meses (#409). Si agregas una fase, muestrea después del trabajo, no antes, y agrega una para cualquier paso lo suficientemente grande como para contener el máximo.

Contadores de sesión y de por 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 las estadísticas del índice del proyecto, el desglose de idiomas, la fila de costos (hoy / 7d / eficiencia), y los totales de por vida del proyecto y mundiales:

Contador mundial

Todos los usuarios de tokensave contribuyen a un contador agregado anónimo. tokensave status muestra tanto tu total del proyecto como el total mundial. La carga envía solo un número único (por ejemplo, 4823) sin información de identificación. Exclúyete con tokensave disable-upload-counter.

Frescura del índice

tokensave mantiene el gráfico actualizado sin un demonio en segundo plano ni un observador de archivos a nivel de sistema operativo.

Verificación de obsolescencia bajo demanda. Cada llamada a herramienta MCP verifica si algún archivo indexado ha sido modificado desde la última sincronización. Si se encuentran archivos obsoletos, se re-extraen antes de que se devuelva la respuesta de la herramienta. Un período de enfriamiento de 30 segundos evita que llamadas consecutivas vuelvan a recorrer el árbol en cada pulsación de tecla.

Sincronización de puesta al día al conectar. Cuando el servidor MCP se inicia, ejecuta inmediatamente una sincronización de puesta al día no bloqueante que recoge cualquier cambio realizado mientras no había ningún agente adjunto — un git pull, una edición de IDE, un paso de compilación — para que la primera llamada a herramienta de una sesión vea un índice fresco.

Trabajo multi-agente y árboles de trabajo de git. Cuando múltiples agentes trabajan en el mismo proyecto de forma concurrente, la suposición fuerte es que cada agente opera en su propio árbol de trabajo de git. Los árboles de trabajo son copias de trabajo independientes del sistema de archivos del mismo repositorio: el agente A y el agente B tienen cada uno su propia copia de cada archivo, por lo que nunca sobrescriben las ediciones en curso del otro. tokensave detecta automáticamente cuando una consulta proviene de un árbol de trabajo anidado dentro del checkout principal y sirve resultados desde el gráfico de ramas correcto. Los cambios se acumulan de forma independiente y finalmente se reconcilian mediante git merge o rebase — el mismo proceso utilizado para cualquier otro desarrollo paralelo. Este diseño evita la complejidad y los modos de fallo del bloqueo entre agentes sobre un directorio mutable compartido.

Flujos de trabajo solo CLI. Si ejecutas comandos tokensave sin un agente adjunto (sin servidor MCP), la verificación de obsolescencia no se ejecuta entre comandos. Instala ganchos de git para mantener el índice fresco automáticamente después de cada commit o clon:

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

Actualización desde 5.x

El comando independiente tokensave daemon y su inicio automático launchd/systemd/Servicio de Windows fueron eliminados en 6.0.0. El observador de archivos a nivel de sistema operativo integrado que reemplazó al demonio fue eliminado a su vez en 6.1.1 (causaba CPU y memoria descontrolados en monorepos grandes con árboles profundos de node_modules o target). El modelo de obsolescencia bajo demanda anterior es el diseño actual.

Si aún tienes un inicio automático de demonio desde 5.x, elimínalo:

• 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 (desde un terminal elevado)

Si no recuerdas el nombre exacto: launchctl list | grep tokensave / systemctl --user list-units | grep tokensave / sc.exe query state= all | findstr -i tokensave.

Auto-actualización

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 descarga el binario de plataforma correcto desde los lanzamientos de GitHub y reemplaza el binario en ejecución en su lugar. Admite canales estable y beta de forma independiente.

Versionado y actualizaciones

Los números de versión de tokensave parecen SemVer pero no lo siguen: el componente que cambia codifica el mantenimiento que requiere la actualización, que tokensave realiza automáticamente en el siguiente lanzamiento — nunca ejecutas una reinstalación o reindexación manualmente.

Reinstalación global. En la primera ejecución de una nueva compilación menor o mayor, tokensave re-ejecuta silenciosamente install para cada agente que ha registrado, de modo que la configuración del agente siempre apunte al binario actual y exponga el conjunto de herramientas actual. Los bumps de parche omiten esto — el marcador de versión en ejecución simplemente se avanza.

La reinstalación es genuinamente silenciosa: la salida de configuración por agente que ves de un tokensave install explícito se suprime aquí, por lo que nunca aparece frente a un tokensave init o tokensave sync ordinario. Si la configuración de un agente no se puede refrescar — la aplicación no está instalada, o su configuración vive en algún lugar de solo lectura — obtienes una línea que nombra a los agentes que fallaron:

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

Ejecuta tokensave install para ver el error subyacente. Los marcadores de versión avanzan de cualquier manera, por lo que una ruta de configuración que nunca se puede escribir se informa una vez por actualización en lugar de reintentarse en cada comando posterior.

Reindexación forzada por proyecto (solo mayor). Un bump mayor significa que los índices del proyecto deben reconstruirse. tokensave hace esto de forma perezosa y por proyecto: en la primera llamada a herramienta MCP en un proyecto después de una actualización mayor, genera una reindexación completa en segundo plano (equivalente a tokensave sync --force) que nunca bloquea la respuesta de la herramienta.

Respaldo de Brew / cargo. Las actualizaciones externas que reemplazan el binario fuera de tokensave upgrade — brew upgrade tokensave o cargo install tokensave — se detectan de la misma manera: si la versión en ejecución es más nueva que la última versión que realizó una instalación, la reinstalación se ejecuta en el siguiente lanzamiento tal como lo haría después de una auto-actualización.

Consulta TOKENSAVE-VERSIONING.md para saber por qué tokensave diverge de SemVer (codificar el mantenimiento en la versión es lo que hace posibles las actualizaciones sin intervención), la mecánica de los marcadores, la versión independiente del esquema de base de datos y las reglas de mantenimiento para publicar lanzamientos.

Referencia de 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

Ejecuta una verificación de salud integral de tu instalación de tokensave:

tokensave doctor

Verificaciones: ubicación del binario, índice del proyecto, base de datos global, configuración de usuario, integración de agente (servidor MCP, ganchos, permisos, reglas de prompt) y conectividad de red. Si faltan permisos de herramientas después de una actualización, te dice que ejecutes tokensave install. Usa --agent para verificar solo un agente específico.

Doctor también valida que cada gancho instalado use el subcomando correcto de tokensave y repara automáticamente los ganchos rotos.

Cómo funciona con Claude Code

Una vez configurado, Claude Code usa automáticamente tokensave en lugar de leer archivos sin procesar cuando necesita entender tu base de código. Tres capas se refuerzan mutuamente:

El resultado: Claude obtiene la misma comprensión del código con muchos menos tokens. Un agente Explore típico lee 20-50 archivos; tokensave devuelve los símbolos, relaciones y fragmentos de código relevantes desde su índice preconstruido.

Llamadas de red y privacidad

La funcionalidad principal de tokensave (indexación, búsqueda, consultas de gráfico, servidor MCP) es 100% local — tu código nunca sale de tu máquina.

La carga del contador mundial envía un solo POST HTTP con un cuerpo JSON como {"amount": 4823}. Sin cookies, sin seguimiento, sin ID de usuario. El Cloudflare Worker registra el país de tu dirección IP (derivado de los encabezados de la solicitud) para estadísticas geográficas agregadas — tu dirección IP real no se almacena.

El refresco de precios de modelos obtiene un archivo JSON público de GitHub (raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json) para mantener los precios de los modelos de Claude actualizados para tokensave cost. No se envían datos — es un GET HTTPS simple. La respuesta se almacena en caché en ~/.tokensave/pricing.json durante 24 horas. Si la obtención falla, tokensave usa su tabla de precios compilada.

Más de 50 idiomas

tokensave admite más de 50 lenguajes de programación organizados en tres niveles controlados por indicadores de características de Cargo. Cada nivel incluye todos los lenguajes del nivel inferior. Los encabezados de Markdown se extraen como nodos Module con bordes jerárquicos Contains para que la estructura del documento participe en las consultas de gráfico junto con el código fuente.

Lite -- --no-default-features

Siempre compilado. El binario más pequeño para los lenguajes más populares, más Svelte y Astro (extracción de bloques de script a través del extractor de TypeScript, sin dependencia adicional de gramática).

Medio (Lite + 9 más) -- --features medium

Completo (Medio + todo lo demás) -- predeterminado

Los lenguajes individuales también se pueden seleccionar manualmente sin un nivel completo:

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

Todos los extractores comparten la misma profundidad: funciones, clases, métodos, campos, importaciones, grafos de llamadas, cadenas de herencia, docstrings, métricas de complejidad, extracción de decoradores/anotaciones y seguimiento de dependencias entre archivos.

tokensave vs CodeGraph

tokensave es una reescritura en Rust desde cero de CodeGraph (Node.js/TypeScript). Ambos construyen grafos de código semánticos para agentes de codificación de IA, pero divergen significativamente en alcance y capacidades.

CodeGraph fue pionero en el enfoque y sigue siendo una opción sólida si prefieres herramientas npm y solo necesitas integración con Claude Code. tokensave extiende el concepto con análisis más profundo, más agentes, soporte multi-rama y un binario nativo sin dependencias de runtime.

Para comparaciones detalladas contra CodeGraph, Dual-Graph (GrapeRoot), code-review-graph y OpenWolf, consulta docs/COMPARABLE-TOOLS.md.

Por Qué Elegir tokensave Sobre las Alternativas

Varias herramientas reducen el uso de tokens para agentes de codificación de IA. Aquí está por qué tokensave se destaca.

Un solo binario nativo, cero dependencias

Cada alternativa requiere un runtime: Python, Node.js o ambos. tokensave se distribuye como un único binario Rust de ~25 MB con todas las 50+ gramáticas tree-sitter incluidas. Nada más que instalar.

La inteligencia de código más profunda

tokensave trabaja a nivel de símbolos: funciones, structs, campos, aristas de llamadas, jerarquías de tipos, métricas de complejidad. Alternativas como Dual-Graph (GrapeRoot) trabajan a nivel de archivo: saben qué archivos existen pero no pueden responder "¿quién llama a esta función?" o "¿qué se rompe si cambio este struct?" Las 80+ herramientas MCP especializadas de tokensave cubren recorrido de grafos de llamadas, análisis de impacto, detección de código muerto, mapeo de pruebas, vista previa de renombrado, jerarquías de tipos, detección de dependencias circulares, clasificación de complejidad, analíticas de salud del código (Gini, DSM, profundidad de dependencias, brechas de prueba ponderadas por riesgo), primitivas de edición atómicas y más. El competidor más cercano (code-review-graph) tiene 22 herramientas; otros tienen 5-9.

El soporte de agentes más amplio

Más de una docena de integraciones de agentes de codificación de IA con formatos de configuración nativos por agente. Ninguna otra herramienta cubre tantos agentes con una integración tan profunda. Claude Code obtiene hooks, reglas de prompt y permisos de herramientas auto-permitidos. Kiro obtiene configuración MCP global, tokensave.md de dirección cargado como recurso, un agente gestionado con aprobación de herramientas integradas/tokensave permisiva, y hooks para salvaguardas de delegación más sincronización posterior a la escritura. Otros agentes obtienen registro del servidor MCP en su formato de configuración nativo.

Indexación multi-rama

La única herramienta en este espacio con bases de datos de grafos por rama opcionales y diff y búsqueda entre ramas. Cuando está habilitado, cambiar de rama es instantáneo: no se requiere re-indexación.

Seguimiento de tokens por llamada

La única herramienta que informa exactamente cuántos tokens ahorró cada llamada individual de herramienta MCP, más un monitor TUI en vivo en todos los proyectos y contadores de por vida.

Completamente de código abierto

Rust con licencia MIT, auditable de principio a fin. El motor central de Dual-Graph (graperoot en PyPI) es propietario: no puedes ver qué hace con tu grafo de código. OpenWolf es AGPL-3.0, lo que requiere que los trabajos derivados sean de código abierto.

Rendimiento

Benchmark de índice completo en una base de código mixta Rust/Java/Scala de 1,782 archivos (57K nodos, 103K aristas):

Solución de Problemas

"tokensave no inicializado"

El directorio .tokensave/ no existe en tu proyecto.

tokensave init

El servidor MCP no se conecta

El agente de IA no ve las herramientas de tokensave.

1. Asegúrate de que la configuración del agente incluya el servidor MCP de tokensave (ejecuta tokensave doctor)
2. Reinicia el agente por completo
3. Verifica que tokensave esté en tu PATH: which tokensave

Símbolos faltantes en la búsqueda

• Ejecuta tokensave sync para actualizar el índice
• Verifica que el lenguaje sea compatible (consulta la tabla anterior)
• Confirma que el archivo no esté excluido por .gitignore

La indexación es lenta

Los proyectos grandes tardan más en el primer índice completo.

• Las ejecuciones posteriores usan sincronización incremental y son mucho más rápidas
• Usa tokensave sync (no --force) para actualizaciones diarias
• La desactualización se verifica automáticamente en cada llamada de herramienta MCP mientras un agente está conectado

Deshabilitar tokensave para proyectos específicos

Si un proyecto es demasiado grande y tokensave usa demasiada RAM, puedes deshabilitar el servidor MCP por proyecto estableciendo TOKENSAVE_DISABLE_SERVER=true en su entorno. El servidor sale limpiamente sin inicializar.

Claude Code — agrega a .claude/settings.json de tu proyecto:

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

Otros agentes — establece la variable de entorno en la configuración que tu agente use para lanzar servidores MCP.

También puedes establecerla globalmente a través del shell (TOKENSAVE_DISABLE_SERVER=true claude), pero esto deshabilita el servidor MCP de tokensave para todos los proyectos en la sesión.

DISABLE_TOKENSAVE=true sigue siendo compatible como alias de compatibilidad obsoleto para configuraciones creadas antes de que esta variable recibiera un espacio de nombres.

Origen

Este proyecto es un port a Rust de la implementación original en TypeScript de CodeGraph por @colbymchenry. El port mantiene la misma arquitectura e interfaz de herramientas MCP mientras aprovecha Rust para el rendimiento y los enlaces nativos de tree-sitter.

Compilación

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

Historial de Estrellas

Patrocinadores

Firma de código gratuita en Windows proporcionada por SignPath.io, certificado por SignPath Foundation

Licencia

Licencia MIT — consulta LICENSE para más detalles.

tokensave.dev