ctxopt

English below / Español abajo

🇪🇸 Español

Una sola configuración de contexto para todos tus agentes de IA de programación (Claude Code, Codex, Antigravity, Cursor).

El problema

Los agentes de IA para programar procesan contexto (archivos, código, historial) en cada tarea. Mientras más grande el proyecto, más fácil es que el agente revise información que no necesita — y eso tiene un costo real en tokens.

Qué hace ctxopt

• ctxopt init — analiza tu proyecto y detecta su stack (lenguajes, frameworks, gestor de paquetes, sistema de pruebas)
• ctxopt generate — crea AGENTS.md (el estándar abierto que ya leen Codex, Antigravity y Cursor de forma nativa) y su adaptador CLAUDE.md para Claude Code
• ctxopt hooks — instala un filtro que reduce la salida de tests/builds verbosos a solo lo relevante, antes de que el agente la reciba
• ctxopt memory init — crea una memoria persistente entre sesiones (.agents/memory.md) que el propio agente decide cómo llenar
• ctxopt agents — instala subagentes con modelo asignado según la tarea (búsquedas y tests en un modelo barato, documentación en uno más capaz)
• ctxopt adapters — verifica compatibilidad multi-agente y agrega un respaldo para versiones de Cursor que aún no leen AGENTS.md nativo

Nunca sobrescribe configuración que ya tengas — si algo existe, guarda una sugerencia aparte en .ctxopt/ en vez de tocarlo.

Evidencia real (no cifras de marketing)

Medido en un proyecto real (Next.js + TypeScript + Supabase, ~220 archivos), comparando la misma tarea con y sin ctxopt:

• En tareas de exploración de código (ej. localizar una integración): 64.5% menos tokens de contexto nuevo procesados
• En costo total medido sobre 3 tareas variadas: 16% de ahorro — con una tarea puntual donde el resultado fue neutro/mixto, no siempre hay ganancia
• El hook de filtrado redujo una salida de test real de 35 a 6 líneas relevantes, conservando siempre el resumen real (no un genérico "sin errores")

El ahorro depende del tipo de tarea: es mayor cuando el agente necesita explorar o buscar, y menor en tareas puntuales donde ya conoce el contexto. No prometemos un número fijo — corre tu propia medición con /usage antes y después.

Estado del proyecto

🚧 En desarrollo activo, probado en un proyecto real de producción.

Uso

npm install
npm run build
node dist/index.js init --path /ruta/a/tu/proyecto
node dist/index.js generate --path /ruta/a/tu/proyecto
node dist/index.js hooks --path /ruta/a/tu/proyecto
node dist/index.js memory init --path /ruta/a/tu/proyecto
node dist/index.js agents --path /ruta/a/tu/proyecto
node dist/index.js adapters --path /ruta/a/tu/proyecto

Licencia

MIT — libre para usar, modificar y distribuir.

🇬🇧 English

One context configuration for all your AI coding agents (Claude Code, Codex, Antigravity, Cursor).

The problem

AI coding agents process context (files, code, history) on every task. The bigger the project, the easier it is for the agent to load information it doesn't actually need for the task at hand — and that has a real token cost.

What ctxopt does

• ctxopt init — scans your project and detects its stack (languages, frameworks, package manager, test runner)
• ctxopt generate — creates AGENTS.md (the open standard already read natively by Codex, Antigravity, and Cursor) and its CLAUDE.md adapter for Claude Code
• ctxopt hooks — installs a filter that trims verbose test/build output down to what's relevant, before the agent ever sees it
• ctxopt memory init — creates persistent memory between sessions (.agents/memory.md) that the agent itself decides how to fill
• ctxopt agents — installs subagents with a model assigned per task (search and tests on a cheap model, docs on a more capable one)
• ctxopt adapters — checks multi-agent compatibility and adds a fallback for Cursor versions that don't yet read AGENTS.md natively

Never overwrites configuration you already have — if something exists, it saves a suggestion in .ctxopt/ instead of touching it.

Real evidence (not marketing numbers)

Measured on a real project (Next.js + TypeScript + Supabase, ~220 files), comparing the same task with and without ctxopt:

• On code-exploration tasks (e.g. locating an integration): 64.5% less new context processed
• On total cost measured across 3 varied tasks: 16% savings overall — with one specific task where the result was neutral/mixed, gains aren't guaranteed every time
• The filtering hook reduced a real test run from 35 to 6 relevant lines, while always preserving the real summary (never a generic "no errors")

Savings depend on the type of task: bigger when the agent needs to explore or search, smaller on one-off tasks where it already knows the context. We don't promise a fixed number — measure your own project with /usage before and after.

Project status

🚧 Active development, tested on a real production project.

Usage

npm install
npm run build
node dist/index.js init --path /path/to/your/project
node dist/index.js generate --path /path/to/your/project
node dist/index.js hooks --path /path/to/your/project
node dist/index.js memory init --path /path/to/your/project
node dist/index.js agents --path /path/to/your/project
node dist/index.js adapters --path /path/to/your/project

License

MIT — free to use, modify, and distribute.