tokensave

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

Menos tokens • Menos llamadas a herramientas • 100% local

¿Por qué tokensave?

Los agentes de programació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 proporciona a los agentes un grafo de conocimiento semántico preindexado. En lugar de escanear archivos, el agente consulta el grafo y obtiene respuestas instantáneas y estructuradas: 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 a través de herramientas MCP: resultados instantáneos, procesamiento local, menos tokens.

Características Clave

Inicio Rápido

1. Instalar

Homebrew (macOS):

brew install aovestdipaperino/tap/tokensave

Scoop (Windows):

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

Cargo (cualquier plataforma):

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

Descárgalos desde la última versión y coloca el binario en tu PATH.

2. Configurar 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 opencode        # OpenCode
tokensave install --agent pi              # Pi (pi.dev)
tokensave install --agent qwen            # Qwen Code
tokensave install --agent roo-code        # Roo Code
tokensave install --agent vibe            # Mistral Vibe
tokensave install --agent zed             # Zed
tokensave install --agent grok            # Grok Build (xAI)
tokensave install --git-hook yes           # auto-install the global post-commit and post-checkout hooks (no prompt)
tokensave install --git-hook no            # skip the post-commit and post-checkout hooks (no prompt)

Cada agente registra su servidor MCP en el formato de configuración nativo. Claude Code recibe adicionalmente un hook PreToolUse (bloquea agentes Explore derrochadores), un hook UserPromptSubmit, un hook Stop, reglas de prompt en CLAUDE.md y permisos de herramientas auto-permitidos. Kiro obtiene configuración MCP global, dirección tokensave.md cargada como recurso y un agente predeterminado gestionado por tokensave con aprobación permisiva de herramientas integradas/de tokensave, hooks de barandilla de delegación y sincronización post-escritura; los agentes Kiro gestionados por el usuario se preservan.

Todos los cambios son idempotentes: es seguro ejecutarlos de nuevo después de una actualización. Después de la configuración del agente, se te ofrecerán hooks globales de git post-commit y post-checkout.

Instalación local del proyecto

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

tokensave install --local --agent claude

Esto escribe una configuración con ámbito de proyecto que puedes commitear y compartir con tu equipo. Para Claude, eso es ./.mcp.json, ./.claude/settings.json y ./CLAUDE.md. Agentes soportados: claude, cursor, droid, gemini, zed, opencode, roo-code, kiro, auggie (cada uno escribe su propio archivo de proyecto, por ejemplo, .cursor/mcp.json, .factory/mcp.json, .gemini/settings.json, .zed/settings.json, opencode.json, .roo/mcp.json, .kiro/settings/mcp.json, .augment/settings.json). Otros agentes no tienen configuración con ámbito de proyecto y reportan un error con --local.

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

3. Indexar 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 una inclusión voluntaria única 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 repositorios que nunca pretendiste indexar. Después de init, usa tokensave sync para actualizar incrementalmente: solo se reindexan los archivos modificados.

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

Sincronización Resistente a Fallos

Las gramáticas de tree-sitter son código C/C++ compilado. Ocasionalmente, alcanzan una aserción interna o terminan el proceso por vías que el manejo de pánico de Rust no puede interceptar. A partir de la v4.3.0, cada archivo se analiza dentro de un subproceso trabajador de corta duración: si una gramática produce un segfault, llama a abort() o alcanza un desbordamiento de pila, solo el trabajador muere. El grupo lo regenera, el archivo ofensivo 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 parte de los usuarios falla. Por defecto, usa available_parallelism() trabajadores; exclúyete con TOKENSAVE_DISABLE_SUBPROCESS=1.

Las primitivas de edición (tokensave_str_replace, tokensave_insert_at, etc.) aún se ejecutan en el proceso: apuntan a un archivo a la vez, donde la sobrecarga del subproceso 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 opcional: sin él, tokensave usa una única 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 funcionalidad 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). Soporta filtros de archivo y tipo.
• tokensave_branch_list -- lista las ramas rastreadas con tamaños de BD, rama padre y tiempos de sincronización

Repliegue de rama

Cuando el servidor MCP no puede encontrar una base de datos para la rama actual, sirve desde la BD de la rama ancestro más cercana e incluye una advertencia en cada respuesta de herramienta sugiriendo ejecutar 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 la rama), las nuevas ramas pueden rastrearse automáticamente en lugar de recurrir a la BD ancestro. Dos mecanismos independientes cubren esto; los proyectos en modo de BD única nunca se ven afectados, y ninguno de los mecanismos toca la base de datos de la rama por defecto.

Hook de git (al hacer checkout de rama). El hook post-checkout que tokensave install configura 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 por defecto, por lo que el cambio ordinario entre ramas conocidas no cuesta nada.

Seguimiento automático al abrir (opcional). Cuando TokenSave::open se ejecuta — comando CLI o inicio del servidor MCP — y la rama activa no está rastreada, tokensave puede rastrearla en el momento copiando la BD 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 (por defecto 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 BD ancestro que realiza un branch add manual; no se ejecuta ninguna sincronización en ese momento — el hook post-commit mantiene la BD de la nueva rama actualizada a medida que haces commits, o ejecuta tokensave sync para actualizar inmediatamente. El seguimiento automático es estrictamente de mejor esfuerzo: cualquier fallo se reporta como una advertencia y open() procede con el repliegue habitual al ancestro, por lo que nunca puede romper una llamada a herramienta.

En resumen: con el hook instalado, hacer checkout de una nueva rama de funcionalidad le da transparentemente su propio grafo por rama; con auto_track habilitado, incluso una rama creada fuera de un checkout (por ejemplo, en un worktree nuevo) 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 área de código entre sesiones, almacenadas en el .tokensave/tokensave.db por proyecto.

Úsalas para que el agente no tenga que volver a explicar decisiones de arquitectura entre sesiones.

Libro de Ahorros

Cada llamada MCP escribe una fila de solo agregar en ~/.tokensave/global.db (tabla savings_ledger). Inspecciona 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 e informa los 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 bases de código de aplicaciones (CLIs, demonios, 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 ajustada.

Prueba de criterio 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 grandes bases de código de código abierto fijadas en referencias constantes. Cada herramienta es impulsada por al menos 5 consultas con argumentos (ids de nodo, nombres cualificados, globs de archivo, …) muestreados del grafo indexado una vez por repositorio, para que los tiempos sean reproducibles entre ejecuciones.

Repositorios y referencias fijadas (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 almacena en caché localmente; las ejecuciones posteriores reutilizan la copia local. La salida de Git se transmite a la terminal para que la descarga de varios GB muestre el 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 active cualquier benchmark, el arnés ejecuta el equivalente a tokensave sync --force en cada repositorio (index_all() independientemente de la frescura de .tokensave/) para que los tiempos siempre reflejen la fuente fijada.

Pruebas 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 utiliza iter_batched de criterion — un pequeño archivo temporal bajo <repo>/.tokensave-bench-scratch/ se reescribe con contenido conocido antes de cada iteración cronometrada, luego la herramienta de edición se ejecuta contra él. Después de que todos los benchmarks finalizan, el arnés ejecuta git stash --include-untracked && git stash drop dentro de cada repositorio preparado para que el árbol de trabajo vuelva a la referencia fijada.

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 medición de 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.
# 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á configurada, la prueba imprime un aviso y registra cero benchmarks (para que cargo bench --all se mantenga ligero en las máquinas de los colaboradores).

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

El filtrado de benchmarks utiliza 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 sin procesar) se almacenan en target/criterion/.

Para cambiar las referencias fijadas (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 siguiente ejecución lo vuelva a obtener. Si omites la limpieza posterior a la ejecución (p. ej., haces Ctrl-C a mitad de la prueba), 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 una refactorización — vuelve a ejecutar la matriz y cualquier celda que ahora tenga errores, tiempo de espera agotado o devuelva resultados vacíos se destaca como un 🚩.
• Sonda de rendimiento. Los tiempos por llamada se registran en TSV; el mismo corpus fijo de repositorios sirve como una comparación aproximada entre versiones. El ciclo actual de errores de tokensave_inheritance_depth fue encontrado por este arnés cuando una sola herramienta en polkadot-sdk agotó el tiempo de espera a >60 s.

Diseño — probe.py es el controlador (JSON-RPC con id coincidente para que una herramienta lenta no pueda envenenar las llamadas posteriores), isolated.py vuelve a ejecutar una sola herramienta con un servidor nuevo por llamada (escapa del encolamiento del servidor), build_matrix.py lee el TSV y emite markdown, los módulos tools/<lang>.py contribuyen con conjuntos de consultas por lenguaje (Rust incluido; añade Python/Go/… agregando un nuevo módulo), repos.toml enumera los repositorios objetivo (anular 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 (tiempos de espera agotados), ∅ E/N (vacío), 🐢 ok/slow (llamadas >10 s). Cualquier celda que tenga un error o tiempo de espera agotado gana un 🚩 en la columna de más a la derecha. El detalle por llamada con los primeros 100 caracteres de cada error se registra en el archivo TSV para seguimiento.

Diferente del benchmark de criterion anterior: criterion mide la latencia por iteración para un conjunto de herramientas enfocado en referencias fijadas y produce informes estadísticos bajo target/criterion/; mcp_probe ejercita cada herramienta con un conjunto de consultas más amplio en los repositorios a los que apuntes, optimizando para 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 a continuación agrupan las más comúnmente usadas por categoría. La mayoría son de solo lectura, seguras para llamar en paralelo y anotadas con readOnlyHint. Las primitivas de edición están limitadas a archivos individuales y se reindexan en el lugar; las herramientas de línea base de sesión y grabación de memoria también mutan el estado local de .tokensave y están anotadas como no de solo lectura. Las tres herramientas principales (tokensave_context, tokensave_search, tokensave_status) están marcadas como anthropic/alwaysLoad para que eviten el viaje de ida y vuelta de búsqueda de herramientas del cliente.

Descubrimiento

Grafo de Llamadas e Impacto

Calidad del Código

Analíticas de Salud del Código

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

Sesiones

Toma una instantánea de las métricas de salud al inicio de una sesión de codificación de IA, luego compara al final para ver qué mejoró o retrocedió.

Primitivas de Edición

Cuatro herramientas de escritura que permiten a los agentes modificar archivos sin los riesgos de expresiones regulares o escapes de shell. Cada una es de archivo único, anclada y desencadena una reindexación 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 agrupados 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 a herramienta MCP. Cada respuesta de herramienta incluye una línea tokensave_metrics: before=N after=M que muestra cuántos tokens de archivos sin procesar se evitaron con esa llamada específica.

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 las transcripciones de sesión 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 los 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 no hay 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 a la fuente 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 Funcionalidades, Refactorización, Pruebas, Exploración, Planificación, Delegación, Operaciones Git, Construcció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 a LLM y está adaptada de AgentSeal/codeburn.

Monitor en vivo

tokensave monitor

Una TUI global que muestra las llamadas a herramientas MCP de todos los proyectos en tiempo real, a través de un búfer circular mapeado en memoria compartida 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).

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 muestra las estadísticas del índice del proyecto, desglose de lenguajes, fila de costos (hoy / 7d / eficiencia) y totales de por vida del proyecto y mundial:

Contador mundial

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

Frescura del Índice

tokensave mantiene el grafo actualizado sin un demonio en segundo plano ni un observador de archivos a nivel de SO.

Verificación de desactualización 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 desactualizados, se reextraen antes de devolver la respuesta de la herramienta. Un período de espera de 30 segundos evita que las llamadas consecutivas re-recorran 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 conectado — un git pull, una edición del IDE, un paso de construcción — para que la primera llamada a herramienta de una sesión vea un índice fresco.

Trabajo multi-agente y worktrees de git. Cuando múltiples agentes trabajan en el mismo proyecto concurrentemente, la suposición fuerte es que cada agente opera en su propio worktree de git. Los worktrees 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 worktree anidado dentro de la copia principal y sirve resultados del grafo de la rama correcta. Los cambios se acumulan de forma independiente y eventualmente 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 con CLI. Si ejecutas comandos tokensave sin un agente conectado (sin servidor MCP), la verificación de desactualización no se ejecuta entre comandos. Instala hooks de git para mantener el índice fresco automáticamente después de cada commit o clonación:

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

Actualizando desde 5.x

El comando independiente tokensave daemon y su inicio automático launchd/systemd/Servicio de Windows se eliminaron en 6.0.0. El observador de archivos integrado a nivel de SO que reemplazó al demonio fue a su vez eliminado en 6.1.0 (causaba un uso descontrolado de CPU y memoria en monorepositorios grandes con árboles profundos de node_modules o target). El modelo de desactualización bajo demanda anterior es el diseño actual.

Si todavía tienes un inicio automático del demonio de 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 una terminal elevada)

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 el lugar. Soporta canales estable y beta de forma independiente.

Versionado y actualizaciones

Los números de versión de tokensave se parecen a SemVer pero no lo siguen: el componente que cambia codifica el mantenimiento que requiere la actualización, el cual 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 vuelve a ejecutar 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 incrementos de parche se saltan esto — el marcador de versión en ejecución simplemente se avanza.

Reindexación forzada por proyecto (solo mayor). Un incremento mayor significa que los índices del proyecto deben reconstruirse. tokensave hace esto de forma diferida 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.

Alternativa 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 reciente 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 se aparta 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 la base de datos y las reglas para los mantenedores al 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                    # Start MCP server
tokensave monitor                  # Live TUI showing MCP calls across all projects
tokensave upgrade                  # Self-update to latest version
tokensave channel [stable|beta]    # Show or switch update channel
tokensave doctor [--agent NAME]    # Check installation health
tokensave branch add|list|remove|removeall|gc   # Multi-branch management
tokensave current-counter          # Show per-project token counter
tokensave reset-counter            # Reset per-project token counter
tokensave disable-upload-counter   # Opt out of worldwide counter uploads
tokensave enable-upload-counter    # Re-enable worldwide counter uploads

tokensave doctor

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

tokensave doctor

Verifica: ubicación del binario, índice del proyecto, BD global, configuración de usuario, integración del agente (servidor MCP, hooks, permisos, reglas de prompt) y conectividad de red. Si falta algún permiso de herramienta después de una actualización, te indica que ejecutes tokensave install. Usa --agent para verificar solo un agente específico.

Doctor también valida que cada hook instalado use el subcomando correcto de tokensave y repara automáticamente los hooks 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 de Exploración típico lee de 20 a 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 grafos, servidor MCP) es 100% local -- tu código nunca sale de tu máquina.

La carga del contador mundial envía un único HTTP POST 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 las cabeceras de la solicitud) para estadísticas geográficas agregadas -- tu dirección IP real no se almacena.

La actualización 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 HTTPS GET 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 lenguajes

tokensave soporta más de 50 lenguajes de programación organizados en tres niveles controlados por flags de características de Cargo. Cada nivel incluye todos los lenguajes del nivel inferior. Las cabeceras Markdown se extraen como nodos Module con aristas jerárquicas Contains para que la estructura del documento participe en las consultas del grafo 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 de gramática adicional).

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

Full (Medium + todo lo demás) -- predeterminado

Los lenguajes individuales también se pueden seleccionar 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 desde cero en Rust 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 las herramientas npm y solo necesitas integración con Claude Code. tokensave extiende el concepto con análisis más profundo, más agentes, soporte multirrama y un binario nativo sin dependencias de tiempo de ejecución.

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

Por qué tokensave frente a las alternativas

Varias herramientas reducen el uso de tokens para agentes de codificación de IA. He aquí por qué tokensave destaca.

Binario nativo único, cero dependencias

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

Inteligencia de código más profunda

tokensave trabaja a nivel de símbolo: funciones, estructuras, campos, aristas de llamada, 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 esta estructura?". Las más de 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 dependencia, brechas de prueba ponderadas por riesgo), primitivas de edición atómica y más. El competidor más cercano (code-review-graph) tiene 22 herramientas; otros tienen 5-9.

Soporte de agente 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 steering cargado como recurso, un agente gestionado con aprobación permisiva de herramientas integradas/tokensave, y hooks para barreras de delegación más sincronización post-escritura. Otros agentes obtienen registro de servidor MCP en su formato de configuración nativo.

Indexación multirrama

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

Seguimiento de tokens por llamada

La única herramienta que informa exactamente cuántos tokens ahorró cada llamada de herramienta MCP individual, 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 extremo a extremo. 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, que requiere que los trabajos derivados sean de código abierto.

Rendimiento

Benchmark de indexación completa en un código base mixto 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 completamente
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 soportado (ver tabla arriba)
• Verifica 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 las actualizaciones diarias
• La obsolescencia se verifica automáticamente en cada llamada a la herramienta MCP mientras un agente está conectado

Deshabilitar tokensave para proyectos específicos

Si un proyecto es demasiado grande y tokensave consume demasiada RAM, puedes deshabilitarlo por proyecto configurando DISABLE_TOKENSAVE=true en el entorno del servidor MCP. El servidor se cierra limpiamente sin inicializarse.

Claude Code — añade a tu .claude/settings.json del proyecto:

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

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

También puedes configurarlo globalmente a través del shell (DISABLE_TOKENSAVE=true claude), pero esto deshabilita tokensave para cada proyecto en la sesión.

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, aprovechando Rust para el rendimiento y los bindings 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