ctx-manager

Un CLI de ingeniería de contexto agnóstico al proveedor y servidor MCP para desarrollo agéntico multilingüe.

ctx-manager se sitúa entre tu carpeta Docs/ (PRDs, documentos de arquitectura, planes de fases, especificaciones de API) y los agentes de codificación de IA (Claude Code, Cursor, Windsurf), reduciendo el gasto de tokens de dos maneras:

• Segmentación de documentos determinista basada en encabezados — extrae exactamente la sección que necesitas de un archivo de plano, no todo el archivo. Estructural (regex sobre encabezados de Markdown), no RAG/embeddings.

• Un Memory_Ledger.md de solo añadidura y validado con git — estado de sesión preciso para que los agentes no vuelvan a derivar o alucinen lo que ya se ha construido. Cada entrada se verifica contra la salida real de git status antes de marcarse como verificada.

Funciona de manera idéntica en Rust, Go, TypeScript, Python o cualquier otra pila -- ctx-manager nunca toca el código fuente de tu aplicación, solo Docs/.

Instalación

uvx --from ctx-manager ctx --help

Sin configuración de virtualenv, no se requiere instalación global.

Related MCP server: Claude Session MCP

Uso

Segmenta un archivo de plano por encabezado:

ctx build --slice "PRD.md > 5. Feature List"

Imprime el contenido de la sección coincidente en stdout — canalízalo a CLAUDE.md o a donde tu agente lea el contexto.

Segmenta automáticamente la siguiente fase, basándose en el historial del ledger:

ctx build --auto-phase

Lee Memory_Ledger.md para la última fase completada y segmenta automáticamente la sección de la siguiente fase de Phase_file.md — sin necesidad de un objetivo --slice manual. Si el ledger aún no tiene entradas de fases completadas, recurre a la Fase 0 con una advertencia.

Añade una entrada verificada al ledger de sesión:

ctx append-ledger --summary "Implemented the login endpoint" --category completed

Comprueba git status contra tu proyecto antes de escribir, y prefija la entrada con [Verified: N files changed], [Reasoning/State Only] o [Unverified: not a git repo] según lo que encuentre — de modo que la afirmación de "hecho" autoinformada por un agente se verifica contra lo que realmente ocurrió en el disco.

Ejecutar como servidor MCP stdio (para Cursor, Windsurf, Claude Desktop):

ctx mcp

Expone query_slice, append_ledger_entry y get_current_phase como herramientas MCP, llamando exactamente al mismo camino de código que los comandos CLI anteriores.

Configuración

ctx-manager busca hacia arriba desde tu directorio actual un .context/config.toml. Si no encuentra ninguno, usa valores predeterminados sensatos (carpeta Docs/, Memory_Ledger.md, etc.) y advierte una vez.

[project]
docs_dir = "Docs/"
ledger_file = "Memory_Ledger.md"
phase_file = "Phase_file.md"

[blueprint_files]
files = ["PRD.md", "Architecture.md", "API_Spec.md"]

[git]
scope = "docs_dir"  # or "repo_root"

Anula la búsqueda por completo con --project-root.

Integración con Claude Code

Los hooks de ejemplo SessionStart/SessionEnd (auto-refrescar CLAUDE.md antes de una sesión mediante --auto-phase, auto-registrar en el ledger después) están en examples/claude_code_hooks/.

Principios de diseño

1. Docs/ entra, Docs/ sale — nunca toca el código fuente de la aplicación, en ningún lenguaje.

2. Barato antes que pesado — re de la stdlib antes que embeddings, subprocess git antes que una librería de git, stdio local antes que cualquier servicio de red.

3. Ledger de solo añadidura — ningún camino de código sobrescribe Memory_Ledger.md por completo. Nunca.

4. Fallar alto, no en silencio — un encabezado o archivo faltante devuelve un error explícito, nunca contenido vacío sobre el que un agente pueda alucinar.

Consulta Docs/Architecture.md y Docs/PRD.md para el documento de diseño completo (este proyecto se usa a sí mismo — su propia carpeta Docs/ es segmentada y rastreada por ctx-manager durante su propio desarrollo).

Limitaciones

ctx-manager no puede evitar que un agente lo omita. Nada aquí impide que un agente con acceso directo al sistema de archivos lea Docs/PRD.md directamente en lugar de pasar por ctx build. Esto es un límite estructural, no una característica faltante — un CLI basado en subprocesos no tiene enganche en las llamadas de herramienta de lectura de archivos de otro proceso.

Si necesitas una aplicación real (no solo una convención), eso tiene que venir del propio runtime del agente:

• Claude Code: usa reglas permissions.deny en .claude/settings.json para bloquear que la herramienta Read toque Docs/*.md directamente, forzando la dependencia del CLAUDE.md que genera ctx build --auto-phase. Consulta la documentación de permisos de Claude Code — esto no es algo que ctx-manager configure por ti.

• Clientes MCP (Cursor, Windsurf, etc.): los controles de acceso al sistema de archivos que ese cliente exponga, si los hay — fuera del control de ctx-manager.

Sin uno de esos, ctx-manager es una convención que se espera que el agente siga, respaldada por el historial de sesión verificado (el ledger) — no una sandbox.

Desarrollo

git clone <this-repo>
cd ctx-manager
uv sync
uv run pytest

Licencia

MIT — consulta LICENSE.