# Context Code

Context Code es una herramienta de programacion agentica que se ejecuta en tu terminal, entiende tu base de codigo y te ayuda a avanzar mas rapido con comandos en lenguaje natural.

📖 **Sitio Web Oficial de Documentación:** [docs.iaforged.com](https://docs.iaforged.com/)

Puede:
- Leer y entender tu proyecto
- Editar archivos y aplicar cambios
- Ejecutar comandos de terminal
- Ayudarte con depuracion, refactors y flujos de trabajo

## Primeros pasos

Instala Context Code con el gestor de paquetes que prefieras (npm, pnpm, yarn). El paquete publicado es el mismo:

```sh
npm install -g @iaforged/context-code
```

```sh
pnpm add -g @iaforged/context-code
```

Luego abre tu proyecto y ejecuta:

```sh
context
```

Los launchers (`context` y `contextcode`) arrancan Node con el heap subido a 8 GB (`--max-old-space-size=8192`) para aguantar sesiones largas con contexto pesado sin reventar por memoria.

### Modo autonomo (sin prompts de permisos)

Si quieres arrancar directamente en modo bypass (equivalente a lanzar `context --dangerously-skip-permissions`), usa el bin hermano `contextcode`:

```sh
contextcode
```

Hace exactamente lo mismo que `context` pero inyecta el flag `--dangerously-skip-permissions` antes de arrancar, asi `/objetivo` y otras tareas autonomas ejecutan Bash/Edit/Write sin pedirte confirmacion para cada paso. Util en sesiones largas de refactor, migraciones o flujos autonomos donde no quieres parar a confirmar cada accion.

## Comandos clave

Atajos imprescindibles para sacarle partido al CLI desde el primer minuto.

### `/objetivo <meta>`

Fija una condicion de fin y deja que el agente itere solo hasta cumplirla. Funciona con el modelo y proveedor que tengas activos en ese momento (Claude, OpenAI, Gemini, DeepSeek, ZAI, MiniMax, OpenRouter, Ollama, etc.) y bumpea permisos a `bypassPermissions` mientras dura. Ver detalles completos en la seccion "Objetivo autonomo" mas abajo.

```text
/objetivo todos los tests de auth pasan en pnpm test
/objetivo clear
```

### `/login deepseek`

Inicia sesion contra DeepSeek y desbloquea su familia de modelos (incluida la V4 con contexto de 1M tokens, mucho mayor que los 200k tipicos de Claude o GPT). Ver detalles en la seccion "Provider DeepSeek".

```text
/login deepseek
```

## Flujo recomendado (Agent-First)

El flujo principal ahora se basa en `/agent`.

1. Abre el gestor de agentes:

```text
/agent
```

2. Crea agentes por rol (por ejemplo: `backend`, `frontend`, `qa`, `docs`).
3. Pide tu objetivo directamente en el hilo principal para que el sistema delegue automaticamente.

Comandos utiles de `/agent`:

- `/agent list [proveedor]`
- `/agent create <proveedor> <name> [profile]`
- `/agent setup <proveedor> [model] [profile]`
- `/agent show <proveedor> <name>`
- `/agent set-role <proveedor> <name> <role>`
- `/agent set-orchestrator <proveedor> <name> <true|false>`
- `/agent set-model <proveedor> <name> <model|clear>`

Ejemplos rapidos:

```text
/agent setup openai gpt-5
/agent setup claude opus
/agent setup deepseek deepseek-v4-pro
/agent setup zai
/agent list openai
```

## Dictado local

El CLI incluye dictado local con `whisper.cpp`, independiente del proveedor con el que estes logeado.

Flujo recomendado:

```text
/dictar install
/dictar
```

Comandos disponibles:

- `/dictar install` descarga e instala automaticamente el backend local y el modelo `base`.
- `/dictar status` muestra el backend y el modelo configurados.
- `/dictar` activa o desactiva el dictado local.
- `/voice` se mantiene como alias de compatibilidad, pero el nombre recomendado es `/dictar`.

Optimizacion de velocidad: `whisper-cli` se invoca por defecto con decodificacion greedy (`-bs 1 -bo 1`), sin timestamps (`-nt`) y paralelizando con el numero de cores fisicos detectados (hasta 8). Da entre 1.5x y 2x de speedup vs. los defaults sin perdida apreciable de calidad. Si quieres forzar un numero distinto de threads, exporta:

```sh
export CONTEXT_CODE_DICTATION_THREADS=12
```

Para mas velocidad aun, usa un modelo mas pequeno como `tiny` con `/dictar install tiny` (aprox 5x mas rapido que `base`, calidad un poco menor).

## Bridges moviles: WhatsApp y Telegram

Context Code puede recibir y enviar mensajes desde WhatsApp y Telegram usando el mismo flujo de ejecucion del CLI (equivalente al comportamiento de `/remote-control`).

### Principios de funcionamiento

- Todo mensaje entrante se inyecta como prompt del CLI.
- Las respuestas del agente se reflejan al chat movil con etiquetas de rol.
- Los comandos de administracion del bridge se manejan en el bridge; los slash no-admin pueden pasar al CLI.
- Al reabrir una conversacion (`/resume` o `/resumen`), el mirror evita replay masivo por defecto.
- Cada mensaje entrante de WhatsApp se marca como leido (los dos checks azules) en cuanto el bridge lo procesa. Grupos y newsletters quedan excluidos para no notificar lecturas fuera de los chats de control.

### Configuracion de WhatsApp

1. Ejecuta `/whatsapp` y completa el wizard (QR, destinatario primario y allowlist).
2. Inicia el bridge con `/whatsapp start` (o desde el menu).
3. Verifica estado con:
   - `/whatsapp status`
   - `/whatsapp permitidos`
   - `/whatsapp info`

Comandos disponibles desde chat de WhatsApp:

- `/help`, `/ayuda`, `/ayudame`
- `/status`
- `/repos`
- `/use <alias>` o `/cd <alias>`
- `/workspace-sync`
- `/proveedores`, `/provider <nombre>`
- `/modelo <nombre>` o `/model <nombre>`
- `/profiles`, `/profile <nombre>`

### Configuracion de Telegram

1. Ejecuta `/telegram` y configura el token de `@BotFather`.
2. Inicia el bot desde el wizard.
3. Verifica estado con:
   - `/telegram status`
   - `/telegram permitidos`
   - `/telegram info`

Comandos disponibles desde chat de Telegram:

- `/help`, `/ayuda`, `/ayudame`
- `/status`
- `/repos`
- `/use <alias>` o `/cd <alias>`
- `/workspace-sync`
- `/proveedores`, `/provider <nombre>`
- `/modelo` o `/model`
- `/perfiles` o `/profiles`
- `/perfil <nombre>` o `/profile <nombre>`

### Modo resume mirror (configurable)

Controla cuanto contexto se espeja al abrir una sesion anterior:

- `CONTEXT_BRIDGE_RESUME_MIRROR_MODE=summary` (default): envia solo `first` + `last`.
- `CONTEXT_BRIDGE_RESUME_MIRROR_MODE=none`: no envia contexto historico.
- `CONTEXT_BRIDGE_RESUME_MIRROR_MODE=full`: envia historial completo.

Tambien se acepta `CONTEXT_RESUME_MIRROR_MODE` como alias.

Comportamiento por defecto:

- el modelo por defecto es `base`, que es multidioma;
- el idioma por defecto del dictado es espanol (`es`);
- si quieres otro idioma o autodeteccion, puedes ajustarlo en la configuracion.

## Objetivo autonomo

`/objetivo` fija una condicion de fin que el agente persigue por su cuenta hasta cumplirla. Al cerrar cada turno, el mismo modelo y proveedor que tengas activos evaluan si la condicion ya se cumplio. Si no, te informan que falta y el agente sigue trabajando; si si, el objetivo se limpia y se anuncia el resultado.

Inspirado en `/goal` de Claude Code, pero compatible con cualquier proveedor que soporte el CLI (Claude, OpenAI, Bedrock, Vertex, Gemini, DeepSeek, OpenRouter, Ollama, ZAI, MiniMax, etc.) y con el modelo que tengas seleccionado en cada momento. El evaluador usa exactamente el mismo proveedor y modelo que tu sesion activa: no hay "modelo oculto" detras.

Comandos:

- `/objetivo <condicion de fin>` fija la meta y arranca la evaluacion automatica al cierre de cada turno.
- `/objetivo` (sin argumentos) muestra el estado actual: meta, tiempo transcurrido, turnos completados y ultima razon devuelta por el evaluador.
- `/objetivo clear` cancela el objetivo activo. Tambien valen `stop`, `off`, `reset`, `cancel`, `cancelar`, `limpiar`, `parar`, `detener` y `none`.
- Alias del comando: `/meta` y `/mision`.

Comportamiento:

- Sin limite de turnos: si le diste una tarea, la termina. Cortas con `/objetivo clear` o `Ctrl+C` cuando quieras.
- Bypass automatico de permisos: al fijar la meta, el modo de permisos cambia automaticamente a `bypassPermissions` (equivalente a `--dangerously-skip-permissions`) para que el agente pueda ejecutar Bash/Edit/Write sin detenerse a pedir confirmacion en cada paso. Al cancelar o cumplir, se restaura el modo previo. Si el modo bypass no esta disponible en tu entorno (gate corporativo) o ya estabas en bypass, no se cambia y el comando te lo avisa.
- Footer en tiempo real: mientras hay objetivo activo, el prompt muestra `o objetivo - 4m 12s - 7t` con el tiempo transcurrido (cronometro que corre cada segundo) y los turnos completados.
- Poda local de tool_results entre turnos: antes de pasarle el historial al evaluador, el CLI poda localmente los `tool_result` voluminosos (logs, dumps, snapshots de archivos). El evaluador recibe solo el resumen necesario para decidir si la condicion se cumplio. Cuesta cero tokens extra de proveedor y mantiene la latencia y el coste por turno planos, sin importar cuanto haya producido el agente.
- Timeout y fallback automatico: si el evaluador no responde dentro del timeout, el sistema asume "aun no cumplido" con motivo de fallback y deja al agente continuar. El bucle nunca se cuelga porque el evaluador este lento o falle.
- Entre turno y turno, antes de continuar trabajando, aparece en el chat un mensaje visible del estilo `o Continuando hacia el objetivo (turno 3 - 4m 12s) - Aun falta: <razon>`, asi siempre ves cuanto lleva, en que turno va y que falta segun el evaluador.
- Toda la actividad del agente (mensajes, llamadas a herramientas, resultados) se ve en el chat como en cualquier conversacion normal: puedes seguir el trabajo paso a paso mientras corre.
- Cuando el evaluador devuelve "cumplido", aparece `o Objetivo cumplido en <duracion> (<N> turnos) - <evidencia>` en el chat.
- El estado es de sesion: no se persiste a disco. `/clear` o cerrar la sesion lo elimina.
- Si la red o el parse del evaluador fallan en un turno, el turno termina normal y no bloquea la conversacion.

Ejemplos:

```text
/objetivo todos los tests de auth pasan en pnpm test
/objetivo el modulo src/services/db usa solo PostgreSQL, sin imports legacy de MySQL
/objetivo
/objetivo clear
/meta termina la migracion a pnpm sin romper el build
/mision stop
```

Consejos:

- Funciona mejor con condiciones medibles ("los tests X pasan", "el archivo Y no contiene Z") que con metas vagas.
- Si el agente da varias vueltas sin avanzar, cancela y reformula con una condicion mas concreta.

## Provider DeepSeek

DeepSeek esta soportado de forma nativa. Lo interesante es el contexto: la familia V4 maneja hasta 1M de tokens, muy por encima de Claude (200k) o GPT (200k), asi que es la opcion natural para tareas con mucho contexto (auditorias de codebase enteras, repos grandes, conversaciones largas con muchos archivos pegados).

Login:

```text
/login deepseek
```

El comando te pide la API key (formato `sk-...`). Tambien puedes saltarte el prompt exportando la variable de entorno antes de arrancar:

```sh
export DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx
```

Opcionalmente, si usas un gateway propio o un proxy compatible con la API de DeepSeek, configura el endpoint:

```sh
export DEEPSEEK_BASE_URL=https://api.deepseek.com/v1
```

Por defecto el CLI usa `https://api.deepseek.com/v1` (OpenAI-compatible), asi que cualquier proxy que respete ese contrato funciona sin tocar codigo.

Modelos disponibles:

- `deepseek-v4-pro` y `deepseek-v4-flash`: familia V4, contexto 1M tokens. `pro` para tareas que requieren razonamiento mas profundo, `flash` para respuestas rapidas.
- `deepseek-chat` y `deepseek-reasoner`: aliases V3 estables, contexto 128k. Utiles si quieres un comportamiento mas predecible o no necesitas el contexto extendido.

Una vez logeado, selecciona el modelo como con cualquier otro proveedor:

```text
/model deepseek-v4-pro
```

## MCP integrados

Context Code soporta MCP externos, pero tambien incluye MCP integrados para ciertos flujos del runtime.

MCP integrados principales:

- `database`: expone herramientas de base de datos con prefijo `mcp__database__*` para operaciones como conexion, consultas, esquema, indices y transacciones sobre `Oracle`, `SQL Server`, `PostgreSQL` y `MySQL`.
- `semble`: expone herramientas de busqueda de codigo con prefijo `mcp__semble__*`, en particular `mcp__semble__search` y `mcp__semble__find_related`.
- `remotion`: expone herramientas de video con prefijo `mcp__remotion__*` para inicializar proyectos, listar composiciones, abrir preview, generar bundles y renderizar `mp4/webm/gif` programaticamente.
- `playwright`: automatizacion de navegador via el paquete oficial de Microsoft (`@playwright/mcp`). Se levanta on-demand con `npx -y @playwright/mcp@latest`, asi que no agrega peso al binario. Cross-platform (macOS, Linux, Windows) y configurable con `/playwright` (ver siguiente seccion).

Comportamiento de `semble`:

- en el primer arranque, el CLI instala `semble` automaticamente si hace falta;
- si `uv` no existe, intenta instalarlo en una carpeta administrada por la aplicacion;
- despues instala `semble`, hace un warmup inicial y descarga el modelo local que usa para embeddings.

MCP opcionales o dependientes de plataforma/features:

- `context-in-chrome`: integracion MCP para automatizacion y contexto desde navegadores Chromium compatibles cuando esa capacidad esta habilitada.
- `computer-use`: MCP orientado a interaccion asistida con interfaz grafica; su disponibilidad depende de plataforma y gates internos.

Para registrar servidores MCP externos y ver mas detalle sobre esta arquitectura:

- [Guia de MCP](docs/MCP_SERVERS.md)

## Playwright MCP

El servidor `playwright` viene preinstalado y se gestiona desde el CLI con el comando `/playwright`. Las preferencias (navegador, modo visible/oculto, ejecutable custom) se guardan en `~/.context/config.json` bajo `playwrightMcpConfig` y los cambios se aplican al siguiente arranque del CLI.

Comandos disponibles:

- `/playwright` abre el menu interactivo con todas las acciones.
- `/playwright status` muestra la configuracion actual.
- `/playwright browser <chromium|chrome|firefox|webkit|msedge>` cambia el navegador. El typeahead del prompt sugiere los valores validos a medida que escribes.
- `/playwright visible` activa el modo headed (veras la ventana del navegador). Es el default.
- `/playwright headless` oculta el navegador (`--headless`).
- `/playwright executable <ruta>` apunta a un binario custom (Brave, Vivaldi, Edge dev, etc.). `clear` lo borra.
- `/playwright device <nombre>` emula un dispositivo (ej. `"iPhone 15"`). `clear` lo borra.
- `/playwright viewport <ancho>x<alto>` fija el viewport (ej. `1280x720`). `clear` lo borra.
- `/playwright reset` borra toda la config y vuelve a los defaults.
- `/playwright help` muestra la ayuda completa.

Sugerencias por plataforma:

- Windows: `msedge` no requiere descarga (Edge viene preinstalado). `chrome` si lo tienes.
- macOS: `chrome` usa el Chrome del sistema sin descarga, o el default `chromium`.
- Linux: `chromium` (default) o `chrome` si esta instalado.

La primera vez que uses `chromium`, `firefox` o `webkit` necesitas descargar el binario de Playwright. Ejecuta:

```sh
npx playwright install chromium
```

`chrome` y `msedge` usan el navegador instalado en el sistema y no requieren descarga.

Si necesitas desactivar Playwright MCP (por ejemplo en un entorno CI sin acceso a `npm`), exporta:

```sh
export CONTEXT_CODE_DISABLE_PLAYWRIGHT_MCP=1
```

## Extension de navegador de Context Code

La extension de navegador permite que el agente use herramientas MCP para leer y operar paginas web abiertas en Chromium (por ejemplo: navegar, leer texto de pagina, buscar texto en DOM y listar pestanas).

Para que sirve:

- obtener contexto real de una web durante una tarea;
- automatizar pasos repetitivos de navegacion;
- combinar acciones de navegador con cambios de codigo dentro del mismo flujo agentico.

Requisitos:

- Context Code CLI instalado y actualizado;
- navegador Chromium compatible (Chrome, Edge o derivado);
- extension de Context Code cargada en modo desarrollador (unpacked);
- Native Messaging habilitado por el CLI (conexion automatica al usar las tools MCP).

Instalacion local de la extension (unpacked):

1. Abre `chrome://extensions/` (o la pagina equivalente en tu navegador).
2. Activa "Developer mode".
3. Pulsa "Load unpacked".
4. Selecciona la carpeta:
   - `D:\Documents\GitHub\Claude\claude-code_V1\Context_Code_V1\apps\browser-extension`
5. Verifica que la extension quede habilitada.

Conexion con Native Host via CLI (automatica):

- al ejecutar Context Code y usar el MCP de navegador, el CLI prepara/usa el host nativo para hablar con la extension;
- no necesitas levantar un servidor manual aparte para el flujo normal de uso;
- si cambias el navegador o reinstalas perfiles, revalida que la extension siga habilitada en `chrome://extensions/`.

Ejemplos de uso desde una conversacion:

```text
Abre https://example.com con la tool mcp__context-in-chrome__navigate
```

```text
Lista mis pestanas activas con mcp__context-in-chrome__tabs_context_mcp
```

```text
Lee el contenido visible de la pagina actual con mcp__context-in-chrome__read_page
```

```text
Busca el texto "pricing" en la pagina con mcp__context-in-chrome__find
```

Notas:

- si una tool no responde, revisa primero que la extension siga cargada y activa;
- en entornos corporativos, politicas del navegador pueden bloquear Native Messaging;
- los errores del bridge de navegador se reportan con prefijo `[context-browser]`.

## Publicacion y empaquetado

Estas notas aplican solo si publicas el paquete o trabajas en el build local. Para el usuario final que solo instala el CLI no cambia nada.

- Minificacion automatica con Terser: el bundle que se publica al registry va minificado en el paso de build oficial. La reduccion ronda el 62% del tamano frente a la salida sin procesar, asi que el `npm install -g` baja y arranca mas rapido.
- Bundle servido desde `dist/`: el paquete ya no incluye un `cli.js` en la raiz; los launchers (`context` y `contextcode`) caen automaticamente a `dist/src/entrypoints/cli.js`. Para el usuario final el comportamiento es identico.
- Build rapido para iteracion local: cuando estas tocando codigo y solo quieres ver tus cambios, salta el paso de minify con:

```sh
pnpm build:fast
```

El build oficial sigue siendo:

```sh
pnpm build
```

Y para publicar al registry, sigue el procedimiento documentado en [docs/PUBLISH.md](docs/PUBLISH.md). El flujo interno usa pnpm pero el paquete publicado se instala igual con npm, pnpm o yarn.

## Documentación

Hemos organizado toda la documentación técnica, guías operativas y arquitectura del proyecto en español.

* **[🪐 Sitio Web Oficial de Documentación (docs.iaforged.com)](https://docs.iaforged.com/)** - *Nuestra documentación interactiva oficial con la guía de primeros pasos, manual de comandos especializados (`/privacySettings`, `/memory`, `/objetivo`, `/dictar`), ecosistema MCP e integraciones.*
* **[Guía Maestra de Context Code (Overview en Español)](../docs/OVERVIEW.md)** - *Nuestra guía local premium con arquitectura y pautas de funcionamiento.*

## Reporte de errores

Usa el comando `/bug` dentro de Context Code.

## Recoleccion, uso y retencion de datos

Cuando usas Context Code, pueden recopilarse datos de uso y retroalimentacion como se describe en la documentacion.

- [Politicas de uso de datos](https://code.iaforged.com/docs/en/data-usage)
