albatrossflyon-coder · webbrain-one · Aug 4, 2026
diff --git a/README.es-ES.md b/README.es-ES.md
@@ -0,0 +1,299 @@
+
+
+# claude-token-operator-kit
+
+<p align="center">
+  <img src="docs/banner-walk.gif" alt="claude-token-operator-kit" width="100%"/>
+</p>
+
+Todo lo que necesitas para ejecutar Claude Code (o cualquier agente de código IA) de forma profesional por 20 USD/mes.
+
+No es un tutorial. Es un sistema funcional. Instálalo, configúralo y tu agente IA se convertirá en una herramienta completamente diferente.
+
+---
+
+## El Problema
+
+La mayoría de las personas utiliza los agentes de código IA como un autocompletado más inteligente. Obtienen resultados inconsistentes, se encuentran con los límites de contexto sin previo aviso, pierden trabajo entre sesiones y se preguntan por qué la IA comienza a estar de acuerdo con todo lo que dicen a mitad de una sesión larga.
+
+El problema no es el modelo. Es la configuración.
+
+La perspectiva de Andrej Karpathy es útil aquí: los LLM no son cajas mágicas, son sistemas deterministas con modos de fallo bien comprendidos. La decadencia del contexto es real. La adulación (sycophancy) es un artefacto del entrenamiento. El "razonamiento" puede ser performante — parece correcto pero es erróneo. Una vez que comprendes los modos de fallo, puedes diseñar soluciones que los eviten.
+
+Este kit hace exactamente eso.
+
+---
+
+## Compatible Con
+
+| Agente | Archivo de configuración | Estado |
+|-------|------------|--------|
+| **Claude Code** | `CLAUDE.md` | Nativo — soporte completo |
+| **Gemini CLI** | `GEMINI.md` | Adapta la configuración, mismos principios |
+| **GitHub Copilot** | `.github/copilot-instructions.md` | Adapta las reglas de precisión + prioridad de herramientas |
+| **Codex CLI** | `AGENTS.md` | Adapta la configuración |
+| **Cursor / Windsurf** | `.cursorrules` | Adapta la sección de reglas de precisión |
+| **Goose** | Extensión TOM + archivo de contexto | Inyecta vía `GOOSE_MOIM_MESSAGE_FILE` |
+
+El **medidor de tokens**, el **sistema de sesiones** y el **sistema de memoria** son nativos de Claude Code. Las **reglas de precisión**, la **prioridad de herramientas** y los **conceptos de habilidades** funcionan en cualquier lugar donde puedas inyectar un prompt del sistema.
+
+---
+
+## Qué Incluye
+
+### 1. CLAUDE.md — La Configuración del Operador
+Configuración plug-and-play que le otorga a tu agente IA:
+- Reglas de precisión basadas en la propia investigación de Anthropic sobre degradación
+- Sistema de prioridad de herramientas (crítico — ver sección inferior)
+- Restricciones de Bash
+- Reglas de gestión de sesiones
+- Reglas de tokens de salida para eliminar la inflación de respuestas
+
+### 2. Habilidades (Skills) — Programas de Prompt Reutilizables
+Ejécutalas dentro de Claude Code mediante `/nombre-habilidad`:
+
+| Habilidad | Qué hace |
+|-------|-------------|
+| `save-session` | Captura el estado completo de la sesión en un archivo con fecha. Nunca más pierdas el contexto. |
+| `resume-session` | Carga la última sesión y te da un resumen antes de tocar cualquier cosa. |
+| `verify` | Bucle de verificación cruzada CC + segundo modelo para salidas de alto riesgo. |
+| `caveman` | Respuestas ultracompresadas. ~75% de reducción de tokens, cero pérdida de precisión. |
+
+### 3. Sistema de Memoria — Memoria Persistente entre Sesiones
+Memoria automática que persiste a través de todas las conversaciones:
+- `user/` — quién eres, preferencias, nivel de experiencia
+- `project/` — trabajo en curso, decisiones, bloqueos
+- `feedback/` — correcciones y patrones confirmados (evita que Claude repita errores)
+- `reference/` — referencias a sistemas externos
+
+### 4. cc-token-gauge — Panel de Tokens en Vivo
+Segundo panel de terminal. En tiempo real: % de contexto, costo, eficiencia de caché, riesgo de degradación.
+
+```bash
+python tools/cc-token-gauge/context_gauge.py
+```
+
+---
+
+## La Sección Más Importante: fff + jMunch
+
+**Esta es la parte que la mayoría de la gente omite. No la saltes.**
+
+De manera predeterminada, los agentes IA recurren a comandos bash para leer archivos, buscar en bases de código y encontrar contenido. Bash funciona, pero es un horno de tokens. Cada llamada a `cat`, `grep` y `find` quema tokens en el formateo de salida, sobrecarga del shell y volcado de archivos en bruto.
+
+La solución: herramientas MCP dedicadas que devuelven exactamente lo que la IA necesita, nada más.
+
+### fff — Buscador Rápido de Archivos
+Reemplaza por completo `find`, `ls` y el escaneo de directorios. Resultados clasificados por frecencia (frecuentes + recientes primero). Ordenes de magnitud más rápido que find de bash.
+
+**En tu CLAUDE.md, indícale a tu IA explícitamente:**
+```
+File search → fff (mcp__fff__find_files)
+File content search → fff grep (mcp__fff__grep)
+NEVER use bash find, ls, grep, or rg for file operations
+```
+
+Sin esta regla, tu agente recurrirá por defecto a bash. Con ella, el uso de tokens en operaciones de archivos cae un 70%+.
+
+Instalación (Windows — descargar binario precompilado):
+```bash
+# Download fff-mcp-x86_64-pc-windows-msvc.exe from:
+# https://github.com/dmtrKovalenko/fff.nvim/releases/latest
+# Place at: C:\Users\<you>\.local\bin\fff-mcp.exe
+# Current stable: v0.9.6
+```
+
+Instalación (macOS/Linux — ejecutar el script de instalación):
+```bash
+curl -fsSL https://raw.githubusercontent.com/dmtrKovalenko/fff.nvim/main/install-mcp.sh | sh
+```
+
+### jCodeMunch — Navegación Semántica de Código (v1.80.1)
+Reemplaza la lectura de archivos de código completos. Tu IA obtiene definiciones de símbolos, referencias y gráficos de llamadas, no 500 líneas de código fuente en bruto.
+
+**Novedad en v1.80+: Modo Gateway v2** — jMunch ahora funciona como un proxy universal para CUALQUIER aplicación IA que utilice las APIs HTTP de OpenAI o Anthropic, no solo servidores MCP. No se requieren cambios de código. Medido: 95–98.9% de reducción de tokens en aplicaciones envueltas.
+
+**En tu CLAUDE.md:**
+```
+Code files (.py/.ts/.tsx) → jCodeMunch (mcp__jcodemunch__*)
+Call list_repos before reading any code file
+```
+
+**Crítico: costo de tokens MCP vs CLI.** Los servidores MCP cargan sus definiciones completas de herramientas en cada turno de mensaje, incluso cuando nunca los llamas. Una sesión con 5 MCP pesados puede arrastrar 70k tokens de peso muerto por turno. Los CLIs cuestan cero tokens en reposo, solo tokens cuando se llaman. Si una herramienta tiene un equivalente CLI, prefírelo. Cambiar MCP por CLIs puede ahorrar el 40% de los tokens de tu sesión antes de escribir una sola línea de código.
+
+### jDocMunch — Navegación de Documentos a Nivel de Sección
+Reemplaza la lectura de documentos markdown completos. Tu IA consulta secciones específicas, no archivos enteros.
+
+**En tu CLAUDE.md:**
+```
+Doc files (.md/.mdx/.rst) → jDocMunch (mcp__jdocmunch__*)
+Call search_sections before reading any markdown
+```
+
+### jDataMunch — Navegación de Datos Estructurados
+Reemplaza la lectura de archivos JSON, HTML y de datos en bruto. Tu IA consulta conjuntos de datos, describe columnas y muestra filas, no volcados de archivos en bruto.
+
+**En tu CLAUDE.md:**
+```
+Data files (.json/.html, >100 lines) → jDataMunch (mcp__jdatamunch__*)
+```
+
+### jmunch-mcp — Compresor de Respuestas MCP
+Envuelve a toda la familia jMunch (y cualquier servidor MCP) como un proxy transparente. Comprime respuestas MCP voluminosas antes de que impacten tu ventana de contexto.
+
+Ahorros medidos:
+- GitHub MCP: **88.3% de reducción de tokens**
+- Firecrawl MCP: **98.9% de reducción de tokens**
+- Rendimiento en tiempo real (wall-clock): **19-43% más rápido**
+
+Instalación:
+```bash
+pip install jmunch-mcp
+```
+
+Conéctalo a tu configuración MCP (reemplaza los comandos directos jcodemunch/jdocmunch/jdatamunch con el proxy jmunch-mcp apuntando a un TOML de configuración). Consulta [guides/tool-stack.md](./guides/tool-stack.md) para instrucciones completas de conexión.
+
+### RTK — Rust Token Killer
+Proxy CLI que comprime la salida de comandos de shell antes de que impacte tu contexto. Intercepa `git`, `npm`, `pytest`, `tsc` y más de 100 comandos adicionales, eliminando el ruido antes de que tu IA lo vea.
+
+Reporta una reducción del 60-90% en comandos de desarrollo comunes.
+
+Instalación (Windows):
+```bash
+# Download from https://github.com/rtk-ai/rtk/releases/latest
+# Pick rtk-x86_64-pc-windows-msvc.zip
+rtk init -g  # wires into Claude Code automatically
+```
+
+Instalación (macOS/Linux):
+```bash
+curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh
+rtk init -g
+```
+
+### jragmunch — CLI RAG de Claude sin interfaz (Headless)
+Envuelve `claude -p` (Claude Code headless) con recuperación jcodemunch precableada, para que las llamadas por lotes/scripted extraigan fragmentos de código relevantes bajo demanda en lugar de insertar archivos completos en el prompt. Agnóstico a la autenticación — ejecuta contra el crédito del Agent SDK de tu suscripción Claude por defecto ($0 de costo real dentro del crédito mensual), o `--use-api` para uso en equipo/CI según los TOS de Anthropic.
+
+Verbos: `ask`, `index`, `run`, `review`, `changelog`, `refactor`, `tests`, `sweep`, `doctor`.
+
+**En tu CLAUDE.md / scripts, úsalo para:**
+```
+Batch/scripted Claude calls (PR review, changelog, fan-out refactors) → jragmunch
+Requires jcodemunch-mcp registered as an MCP server
+```
+
+Instalación:
+```bash
+pip install jragmunch
+jragmunch doctor
+```
+
+Repositorio: [jgravelle/jragmunch-cli](https://github.com/jgravelle/jragmunch-cli)
+
+### Por Qué Esto es Relevante en un Plan de 20 USD/Mes
+
+En Claude Pro, cada token cuenta. Una sesión típica leyendo archivos vía bash vs. el stack completo:
+
+| Operación | Tokens Bash | Tokens fff+jMunch | Con jmunch-mcp |
+|-----------|------------|-------------------|-----------------|
+| Buscar un archivo en repo grande | ~2,000 | ~50 | ~50 |
+| Leer un símbolo de código | ~3,000 (archivo completo) | ~200 (solo símbolo) | ~25 |
+| Buscar respuesta en doc | ~5,000 (doc completo) | ~300 (sección) | ~35 |
+| Llamada GitHub MCP | ~8,000 | ~8,000 | ~940 |
+
+En una sesión completa: **50-75% de ahorro con fff+jMunch, hasta 90% de ahorro adicional con jmunch-mcp en llamadas MCP.**
+
+**La regla que tu IA debe seguir:**
+> Usa fff y jMunch para TODAS las operaciones de archivos. Bash es solo para comandos git, instalación de paquetes y ejecución de CLI. Nunca bash-grep. Nunca bash-cat. Nunca bash-find.
+
+---
+
+## El Stack de 20 USD/Mes
+
+| Herramienta | Costo | Propósito |
+|------|------|---------|
+| Claude Pro | 20 USD/mes | La IA |
+| fff | Gratuito | Búsqueda de archivos eficiente en tokens |
+| jCodeMunch + jDocMunch + jDataMunch | Gratuito | Navegación de código/docs/datos eficiente en tokens |
+| jmunch-mcp | Gratuito | Compresor de respuestas MCP (reducción 88-99%) |
+| jragmunch | Gratuito | CLI RAG eficiente en tokens para Claude headless |
+| RTK | Gratuito | Compresor de salida de shell (reducción 60-90%) |
+| NotebookLM (pipeline de investigación) | Gratuito | Extracción de conocimiento |
+| Este kit | Gratuito | Configuración + habilidades + sistema de memoria |
+
+**Total: 20 USD/mes.**
+
+---
+
+## La Investigación Detrás de las Reglas de Precisión
+
+La propia investigación de Anthropic identifica 5 modos de fallo en sesiones largas de IA:
+
+1. **El circuito de "no lo sé" se anula** — señales contradictorias en un contexto largo generan falsa confianza
+2. **Razonamiento performante** — las respuestas parecen correctas pero la lógica subyacente es errónea
+3. **Adulación (Sycophancy)** — la IA deduce ingenierilmente el acuerdo con tu sugerencia en lugar de verificar de forma independiente
+4. **Inercia interna** — no puede autocorregirse a mitad de frase incluso cuando está equivocado
+5. **Decadencia del contexto** — las instrucciones iniciales se desvanecen, las posteriores dominan
+
+**Límites clave:**
+- Mensaje 30+: comienza la degradación
+- Contexto 50%: planifica `/compact`
+- Contexto 80%: `/compact` inmediatamente
+
+Las reglas de precisión en `CLAUDE.md` y el medidor de riesgo de degradación en `cc-token-gauge` son implementaciones directas de esta investigación.
+
+---
+
+## Inicio Rápido
+
+```bash
+# 1. Clone
+git clone https://github.com/albatrossflyon-coder/claude-token-operator-kit
+
+# 2. Copy config
+cp config/CLAUDE.md ~/.claude/CLAUDE.md
+
+# 3. Install skills
+cp -r skills/* ~/.claude/skills/
+
+# 4. Start token gauge (second terminal)
+python tools/cc-token-gauge/context_gauge.py
+
+# 5. Install fff + jMunch (see guides/tool-stack.md)
+```
+
+Guía completa de configuración: [guides/20-dollar-setup.md](./guides/20-dollar-setup.md)
+
+---
+
+## La Gran Imagen
+
+Este kit es el resultado de un pipeline de investigación:
+
+1. Videos de YouTube + artículos van a cuadernos de **NotebookLM**
+2. NLM extrae conocimiento estructurado vía CLI
+3. Ese conocimiento se codifica en **habilidades**, **reglas de CLAUDE.md** y **archivos de memoria**
+4. La IA ejecuta esas reglas en cada sesión
+
+El medidor de tokens se construyó porque NLM hizo visible la investigación de degradación de Anthropic. La habilidad `verify` existe porque esa misma investigación mostró que la IA dará respuestas incorrectas con confianza en sesiones largas. Cada pieza se conecta.
+
+---
+
+## Créditos
+
+- **Perspectiva de Karpathy** — El trabajo de Andrej Karpathy sobre la comprensión de los LLM como sistemas deterministas con modos de fallo conocidos
+- **fff** — [dmtrKovalenko](https://github.com/dmtrKovalenko/fff.nvim) — el kit de búsqueda de archivos más rápido para agentes IA. Núcleo del ahorro de tokens del 50-75%.
+- **jCodeMunch** — [jgravelle](https://github.com/jgravelle/jcodemunch-mcp) — navegación semántica de código vía MCP
+- **jDocMunch** — [jgravelle](https://github.com/jgravelle/jdocmunch-mcp) — navegación markdown a nivel de sección vía MCP
+- **jDataMunch** — [jgravelle](https://github.com/jgravelle/jdatamunch-mcp) — navegación de datos estructurados vía MCP
+- **jmunch-mcp** — [jgravelle](https://github.com/jgravelle/jmunch-mcp) — proxy compresor de respuestas MCP. Envuelve cualquier servidor MCP y reduce el costo de tokens de respuesta un 88-99%.
+- **jragmunch** — [jgravelle](https://github.com/jgravelle/jragmunch-cli) — CLI RAG eficiente en tokens para Claude headless, con recuperación jcodemunch precableada.
+- **RTK** — [rtk-ai](https://github.com/rtk-ai/rtk) — Rust Token Killer. Proxy CLI que comprime la salida de shell 60-90% antes de impactar tu contexto.
+- **NotebookLM** — Google — pipeline de investigación que hizo visible la investigación de degradación de Anthropic
+- **Monitoreo de tokens** — [ai-token-dashboard](https://github.com/albatrossflyon-coder/ai-token-dashboard) — panel de tokens en vivo para CC, Hermes, Gemini y más
+
+---
+
+## Licencia
+
+MIT