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.

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:

npm install -g @iaforged/context-code

Luego abre tu proyecto y ejecuta:

context

Documentacion

• Resumen general

Skills de Context

Context usa .context/skills como carpeta oficial de skills del proyecto y ~/.context/skills como carpeta global de usuario.

Formato:

.context/skills/<nombre-skill>/SKILL.md

Comandos:

/skills
/skills import
/skills import .claude
/skills import .codex
/skills import .agents

Uso practico:

• /skills lista las skills disponibles.
• /skills import busca skills legacy en .claude/skills, .codex/skills y .agents/skills, y las copia a .context/skills.
• /skills import .claude importa solo desde .claude/skills.
• Las nuevas skills deben crearse en .context/skills/<nombre>/SKILL.md.
• CONTEXT_CONFIG_DIR es la variable principal para cambiar la carpeta global; CLAUDE_CONFIG_DIR queda como fallback temporal de compatibilidad.

Sistema multi-proveedor y multi-perfil

Context Code ya funciona con una capa de proveedores mas flexible. La idea base es separar:

• el provider como backend de inferencia
• el provider profile como perfil guardado dentro de ese proveedor
• el agentName como nombre operativo pensado para futuros subagentes

Provider profile

Un provider profile es una configuracion persistida para un proveedor concreto. Sirve para guardar datos que quieres recordar por separado, por ejemplo:

• base URL
• ultimo modelo usado
• credenciales o token, cuando el proveedor lo soporta

El nombre del perfil es el identificador humano que ves en el comando. El agentName es el nombre tecnico que queda preparado para el futuro sistema de subagentes. Por ejemplo:

/provider ollama profile local

Puede guardar un perfil llamado local con un agentName del estilo ollama-local.

Comando /provider

El comando /provider ahora sirve para cambiar de proveedor y tambien para activar un perfil concreto.

/provider
/provider list
/provider ollama
/provider zai profile main
/provider ollama profile local

Comportamiento de /provider:

• /provider (sin argumentos) abre el selector interactivo de proveedores.
• /provider list muestra una tabla detallada con todos tus proveedores, perfiles guardados, estado de conexión (Conectado/Desconectado) y perfiles activos.
• /provider <proveedor> cambia al proveedor especificado.
• /provider <proveedor> profile <nombre> activa (o crea) un perfil específico para ese proveedor.
• /provider <proveedor> <URL> cambia la Base URL del proveedor (ej. /provider ollama http://localhost:11434/v1).
• /provider <proveedor> clear restaura la URL por defecto del proveedor.

Tambien existe /profile para inspeccionar y navegar perfiles ya guardados:

/profile
/profile list
/profile current
/profile use ollama local
/profile rename ollama local gpu-lab
/profile model ollama gpu-lab llama3.2
/profile model ollama gpu-lab clear
/profile agent ollama gpu-lab ollama-lab
/profile remove all
/profile remove ollama gpu-lab

Comportamiento de /profile:

• /profile o /profile list muestra todos los perfiles guardados por proveedor.
• /profile current muestra el perfil activo.
• /profile use <proveedor> <perfil> activa el perfil y restaura su ultimo modelo si existe.
• /profile rename <proveedor> <actual> <nuevo> renombra el perfil.
• /profile model <proveedor> <perfil> <modelo> corrige o fija el ultimo modelo guardado para ese perfil.
• /profile model <proveedor> <perfil> clear limpia el modelo guardado.
• /profile agent <proveedor> <perfil> <agentName> cambia el nombre tecnico del perfil para futuros subagentes.
• /profile remove <proveedor> <perfil> elimina el perfil.
• /profile remove all elimina todos los perfiles guardados de una sola vez.

Notas importantes:

• El nombre visible del perfil y el agentName no son lo mismo.
• El nombre visible sirve para navegar con /provider ... profile ... o /profile use ....
• agentName queda reservado como identificador operativo para el futuro sistema de subagentes.
• Al renombrar un perfil, sus credenciales por perfil tambien se mueven al nuevo identificador para no perder API keys u OAuth.
• Al borrar un perfil, tambien se limpian sus credenciales scoped cuando existen.
• /profile remove all limpia todos los perfiles y sus credenciales scoped asociadas, pero no toca los fallbacks legacy de compatibilidad.

Comportamiento esperado:

• /provider abre la seleccion de proveedor.
• /provider <proveedor> cambia al proveedor activo.
• /provider <proveedor> profile <nombre> selecciona o crea ese perfil y lo deja activo.
• La configuracion de ese perfil se reutiliza la proxima vez que vuelvas al mismo proveedor o perfil.

Despues de activar un perfil, puedes seguir ajustando sus valores con los comandos normales del proveedor:

/provider ollama http://localhost:11434/v1
/provider ollama clear
/provider list
/model

Soporte Multi-cuenta real

Context Code permite gestionar múltiples cuentas del mismo proveedor (como varias cuentas de Claude o OpenAI) de forma independiente.

/login --profile personal
/login --profile trabajo

• Al usar el flag --profile (o -p), las credenciales se guardan específicamente en ese perfil.
• El sistema detecta automáticamente si el perfil ya existe o crea uno nuevo.
• Puedes saltar entre cuentas fácilmente usando /provider claude profile personal o listarlas todas con /provider list.

Persistencia por perfil

La persistencia queda separada por perfil cuando el proveedor lo soporta.

• base URL queda guardada por perfil.
• ultimo modelo queda guardado por perfil.
• credenciales quedan guardadas por perfil cuando aplica, incluyendo OAuth y API keys.
• Si no existe un perfil nuevo, el sistema intenta reutilizar o migrar la configuracion vieja para no romper instalaciones existentes.

SQLite autogenerable

La metadata de proveedores y perfiles ahora se apoya en una base SQLite autogenerable:

• archivo: ~/.context/provider-state.sqlite3
• se crea sola al arrancar si no existe
• si hay configuracion legacy previa, puede migrarla con /profile migrate
• en Windows/Linux, las credenciales de proveedores tambien se almacenan en esta misma DB
• esas credenciales se guardan cifradas localmente antes de persistirse en secure_storage

Que se guarda ahi:

• perfiles por proveedor
• perfil activo
• proveedor activo
• ultimo modelo por proveedor
• estado runtime necesario para restaurar contexto rapido
• API keys, tokens OAuth y credenciales scoped por perfil, mediante la tabla secure_storage
• el contenido de secure_storage.value ya no queda en JSON legible; se cifra localmente antes de escribirse

Migracion de credenciales:

• si existe ~/.context/.credentials.json, se importa automaticamente a SQLite la primera vez que se lee el storage seguro
• si la importacion termina bien, el archivo legacy .credentials.json se elimina para evitar dos fuentes de verdad
• en macOS se mantiene el flujo de keychain con fallback, segun el backend disponible

Estado actual:

• Windows/Linux ya trabajan en modo SQLite-only para providers, perfiles, modelos, base URLs y credenciales
• /status y /profile migrate muestran si el runtime quedo completamente migrado
• macOS sigue usando keychain/fallback por diseno; esa ruta queda fuera de esta migracion

Proveedores actuales

Estos son los proveedores visibles hoy y su estado general:

• Claude (Anthropic): usa OAuth y ahora puede resolver sesion por perfil, manteniendo fallback al storage anterior.
• OpenAI / Codex: usa OAuth por perfil con compatibilidad hacia atras.
• OpenRouter: usa API key y endpoint configurable por perfil.
• Ollama Local: ya trabaja con perfiles; no usa API key y guarda base URL y modelo por perfil.
• Ollama Cloud: usa endpoint configurable y queda alineado con la capa de perfiles.
• Z.AI: ya trabaja con perfiles; guarda API key, base URL y modelo por perfil.
• MiniMax: usa API key y endpoint compatible con Anthropic por perfil.

Compatibilidad hacia atras

La migracion esta pensada para no romper la configuracion anterior:

• los valores anteriores pueden servir de base para crear el perfil por defecto durante la migracion inicial
• /profile migrate limpia el remanente legacy cuando la DB ya quedo consistente
• en Windows/Linux el objetivo final ya es SQLite-only

Notas de uso

• Ollama esta pensado como backend local, con el default en http://localhost:11434/v1.
• Z.AI requiere API key por perfil y es el primer proveedor no local con soporte real de perfiles.
• Claude, OpenAI, OpenRouter, MiniMax y Ollama Cloud ya resuelven su estado desde la arquitectura nueva con fallback a la configuracion anterior.
• El comando /model sigue existiendo y ahora debe entenderse junto con el perfil activo.

Equipos con varios proveedores

Esta parte permite usar varios proveedores como si fueran un equipo de trabajo. No necesitas aprender terminos internos: piensa en cuatro niveles simples.

• workspace: representa un proveedor dentro del sistema de equipos, por ejemplo claude, openai, minimax u ollama.
• agent: es un perfil operativo dentro de un proveedor. Ejemplo: claude/frontend-lead o openai/backend-lead.
• team: es el equipo completo para un objetivo. Ejemplo: core-dev.
• domain (o dominio): es un area de trabajo dentro del team. Ejemplos: frontend, backend, docs, planning, tests, review, database. Cuando creas un team con /workspace setup, el sistema arma 4 dominios por defecto (frontend, backend, docs, planning); los que no asignes a un agente quedaran como warnings al ejecutar.
• run: es una ejecucion guardada de un objetivo. Tiene tareas, mensajes, resultados y estado.

Mini glosario para no confundirse con los roles internos:

• orquestador global: el agente que coordina todo el team. Lee el objetivo del usuario, lo descompone, asigna trabajo a cada dominio y consolida los reportes finales para entregartelos a ti.
• orquestador local: por dominio. Recibe la parte del objetivo que le toca, decide como dividirla entre los miembros del dominio (o como hacerla solo en modo autonomo) y reporta de vuelta al orquestador global.
• lead: el agente principal de un dominio. En la mayoria de los flujos, el orquestador local y el lead son el mismo agente.
• modo autonomo: cuando un dominio no tiene miembros extra, el orquestador local asume internamente los roles que necesite (planner, executor, reviewer, etc.) sin necesitar mas agentes configurados.
• global-plan / squad-plan / domain-report / run-report: tipos de mensajes que se guardan en la run. El primero lo emite el orquestador global al planear, el segundo cada orquestador local cuando recibe su tarea, y los reportes son lo que devuelven cuando terminan. Los puedes ver con /run messages <run-id>.

Orden normal de uso:

1. Configuras un proveedor y un perfil con /provider, /login y /model.
2. Ejecutas /workspace setup para crear el equipo base sin hacer todo a mano.
3. Revisas el equipo con /team show.
4. Generas una corrida con /orchestrate.
5. Ejecutas o revisas la corrida con /run.
6. Si quieres seleccion automatica o fallback, usas /policy.

/workspace

/workspace sirve para revisar que proveedores pueden participar en equipos. Un workspace no es una carpeta del proyecto; aqui significa "este proveedor esta disponible para tener agentes".

Comandos:

/workspace
/workspace list
/workspace show minimax
/workspace enable claude
/workspace disable openrouter
/workspace setup
/workspace orchestrator
/workspace setup core-dev orchestrator=backend claude/main:frontend openai/work:backend

Uso practico:

• /workspace list muestra los proveedores registrados para equipos.
• /workspace show minimax muestra si MiniMax esta habilitado para equipos.
• /workspace enable claude permite que agentes de Claude participen en equipos.
• /workspace disable openrouter evita que OpenRouter sea usado por la orquestacion.
• /workspace setup abre el wizard interactivo.
• /workspace orchestrator abre un selector para elegir equipo y cambiar su orquestador principal.
• /workspace setup core-dev orchestrator=backend claude/main:frontend openai/work:backend salta el wizard y crea una base de equipo lista para usar.

El wizard de /workspace setup tiene opciones para:

• preparar un proveedor/perfil
• abrir login o configuracion si faltan credenciales
• llevarte a seleccionar modelo usando /model
• escribir el nombre del equipo
• escoger el orquestador principal desde perfiles existentes, crear/activar un perfil nuevo, elegir un area o usar un valor personalizado
• crear el comando base para armar el equipo con autocompletado
• mostrar workspaces disponibles
• mostrar ayuda y ejemplo

Cuando ya tienes perfiles listos, el modo rapido hace esto por ti:

1. Habilita cada proveedor como workspace.
2. Crea un agente por area con nombre <area>-lead.
3. Conecta cada agente al perfil que escribiste.
4. Crea el equipo si todavia no existe.
5. Usa orchestrator=... como coordinador principal, o el primer agente si no lo indicas.
6. Crea o actualiza las areas del equipo.

El input tambien ayuda con autocompletado para /workspace: subcomandos, proveedores, perfiles guardados y areas comunes como frontend, backend, docs, tests, review, database y devops.

Para cambiar el orquestador principal despues de crear el equipo:

/workspace orchestrator

Ese wizard primero muestra los equipos guardados y luego los agentes disponibles para asignar uno como coordinador global. Si prefieres hacerlo directo:

/workspace orchestrator core-dev openai/backend-lead

Formato rapido:

/workspace setup <equipo> [orchestrator=<area|proveedor/agente>] <proveedor/perfil:area> [...]

Ejemplo:

/workspace setup core-dev orchestrator=backend claude/main:frontend openai/work:backend minimax/main:docs

En ese ejemplo:

• core-dev es el equipo.
• claude/main:frontend crea o reutiliza claude/frontend-lead.
• openai/work:backend crea o reutiliza openai/backend-lead.
• minimax/main:docs crea o reutiliza minimax/docs-lead.
• orchestrator=backend pone a openai/backend-lead como coordinador principal.

Cuando usarlo:

• si un proveedor no aparece como opcion para agentes
• si quieres desactivar temporalmente un proveedor
• si quieres confirmar que el sistema reconoce un proveedor antes de crear agentes
• si quieres armar un equipo rapido sin recordar /agent y /team

/team-auto — wizard automatico

Si todavia no sabes que dominio asignar a cada proveedor, /team-auto lo decide por ti. Detecta los perfiles ya logueados y arma un team con dominios estandar (frontend, backend, docs, planning):

/team-auto              # crea un team llamado "default-team"
/team-auto core-dev     # crea (o actualiza) un team llamado "core-dev"

Que pasa al ejecutarlo:

1. Detecta los provider profile activos (los que ya tienen credencial).
2. Aplica una heuristica de reparto: Claude -> frontend, OpenAI -> backend, MiniMax/Z.AI -> docs, Ollama/OpenRouter -> planning. Si solo tienes 1 proveedor, ese hace TODOS los dominios en modo autonomo.
3. Te muestra el plan en pantalla (que dominios va a crear, que agentes va a reusar, quien sera el orquestador global).
4. Pulsas Enter y aplica los cambios, o Esc y cancela sin tocar nada.

Cuando un dominio queda sin agente compatible (por ejemplo no tienes ningun proveedor que mapee a docs), se reporta sin asignar en el plan y queda como warning. Despues puedes asignarlo manualmente con /team domain <team> docs <provider>/<agent>.

Si el team ya existe, /team-auto solo lo actualiza: no borra agentes ni miembros que ya tuvieras.

Cuando quieras configurarlo todo a mano, sigue habiendo /workspace setup (wizard guiado, mas detallado) o el formato corto /workspace setup <team> orchestrator=... <provider/profile:dominio>....

/agent

/agent crea nombres de trabajo dentro de cada proveedor. Un agente siempre apunta a un provider profile real.

Ejemplo: si tienes claude/main, puedes crear claude/frontend-lead. Ese agente usara las credenciales y modelo del perfil main, salvo que le pongas un modelo propio.

Comandos:

/agent
/agent list
/agent list claude
/agent create claude frontend-lead main
/agent show claude frontend-lead
/agent set-role claude frontend-lead frontend
/agent set-orchestrator claude frontend-lead true
/agent set-model claude frontend-lead claude-sonnet-4-6

Uso practico:

• /agent create claude frontend-lead main crea un agente llamado frontend-lead dentro de Claude usando el perfil main.
• /agent set-role claude frontend-lead frontend indica que ese agente se especializa en frontend.
• /agent set-orchestrator claude frontend-lead true permite que ese agente coordine trabajo.
• /agent set-model claude frontend-lead <modelo> fuerza un modelo solo para ese agente.

Formato para referirse a un agente:

provider/agent

Ejemplos:

claude/frontend-lead
openai/backend-lead
minimax/docs-runner
ollama/local-coder

/team

/team arma un equipo usando agentes. El team tiene un coordinador principal y puede dividir el trabajo por areas.

En esta documentacion llamamos dominio a cada area de trabajo. Ejemplos de dominios: frontend, backend, docs, review, tests, database.

Comandos:

/team
/team list
/team create core-dev
/team orchestrator
/team orchestrator core-dev claude/frontend-lead
/team domain core-dev frontend claude/frontend-lead
/team domain core-dev backend openai/backend-lead
/team add-member core-dev frontend claude/ui-reviewer reviewer
/team show core-dev

Uso practico:

• /team create core-dev crea un equipo llamado core-dev.
• /team orchestrator abre un selector para escoger equipo y luego orquestador principal.
• /team orchestrator core-dev claude/frontend-lead define quien coordina todo el equipo.
• /team domain core-dev frontend claude/frontend-lead dice que el area frontend la lidera claude/frontend-lead.
• /team domain core-dev backend openai/backend-lead dice que backend lo lidera openai/backend-lead.
• /team add-member core-dev frontend claude/ui-reviewer reviewer agrega un miembro extra al area frontend.
• /team show core-dev muestra como quedo armado el equipo.

Cuando usas /team domain, ese agente queda como orquestador local y lead del dominio al mismo tiempo. Eso significa que usa el perfil/modelo vinculado a ese agente para coordinar su propia area. Por ejemplo, openai/backend-lead puede ser el equipo autonomo de backend aunque no tenga miembros extra.

Si un dominio no tiene miembros extra, no esta roto. En ese caso opera en modo autonomo: el orquestador local divide internamente el trabajo segun su funcion principal. Backend puede asumir roles temporales como API, base de datos, validaciones y pruebas; frontend puede asumir UI, componentes, estado y pruebas; docs puede asumir guia tecnica y README. Los miembros extra son opcionales cuando quieres dividir mas el trabajo.

Ejemplo mental simple:

• Claude puede coordinar frontend.
• OpenAI puede coordinar backend.
• MiniMax puede hacer documentacion o tareas rapidas.
• Ollama puede actuar como ejecutor local.
• El coordinador principal mira el objetivo completo y recibe reportes de cada area.

Crear y ejecutar una corrida

Una run es una ejecucion guardada de un objetivo. Por ejemplo: "crear login con UI y API". La run vive en SQLite, por eso puedes cerrar la app y luego volver a revisarla.

/orchestrate

/orchestrate toma un team y un objetivo, planifica el trabajo, te muestra el plan en pantalla y te pregunta si quieres ejecutarlo ya:

/orchestrate core-dev crear endpoint de login y UI de acceso

Que pasa cuando lo ejecutas:

1. El sistema valida el team, el orquestador global y los dominios.
2. Crea la run y todas sus tasks en estado ready o blocked segun la configuracion del dominio.
3. Te muestra el plan: tareas por dominio, agentes asignados, advertencias de configuracion.
4. Te ofrece dos teclas:
   • Enter: ejecuta inmediatamente las tareas ready. Veras progreso en vivo (dominio que esta trabajando, agente activo, fase) y al final un reporte consolidado.
   • Esc: deja la run en planned. Puedes revisar con /run show <run-id> o ejecutar mas tarde con /run resume <run-id>.

Cuando confirmas con Enter, el flujo interno es: orquestador global delega a cada orquestador local -> cada orquestador local ejecuta o subdelega en modo autonomo -> cada uno devuelve un domain-report -> el orquestador global consolida y emite el run-report final que ves tu.

Si pulsas Esc o no hay tareas ready (todo quedo bloqueado), la corrida se queda en estado planned y el comando termina mostrando los siguientes pasos sugeridos. En ese caso normalmente sigues con:

/run show <run-id>     # revisar el plan en detalle
/run resume <run-id>   # ejecutar despues

/run

/run sirve para revisar, ejecutar, reintentar, reasignar o cancelar una corrida.

Comandos principales:

/run
/run list
/run show <run-id>
/run messages <run-id>
/run tasks <run-id>
/run task <task-id>
/run domain <run-id> <domain>
/run resume <run-id>
/run cancel <run-id>

Comandos de recuperacion:

/run retry <run-id> [task-id]
/run cancel-task <task-id>
/run reassign <task-id> <provider>/<agent>

Que hace cada comando:

• /run list muestra las corridas guardadas.
• /run show <run-id> muestra resumen, estado, tareas y ultimos mensajes.
• /run tasks <run-id> muestra todas las tareas de la corrida.
• /run task <task-id> muestra una tarea concreta con sus mensajes y resultados.
• /run domain <run-id> frontend muestra solo el area frontend.
• /run messages <run-id> muestra la bitacora completa.
• /run resume <run-id> ejecuta tareas listas.
• /run cancel <run-id> detiene la corrida.
• /run retry <run-id> reintenta tareas fallidas o bloqueadas.
• /run retry <run-id> <task-id> reintenta una tarea concreta.
• /run cancel-task <task-id> bloquea una tarea para que no continue.
• /run reassign <task-id> openai/backend-lead cambia el agente responsable.

Estados de una corrida:

• planned: fue creada pero aun no se ejecuto.
• in_progress: esta en ejecucion.
• completed: termino sin tareas abiertas.
• failed: alguna tarea fallo o quedo bloqueada.
• cancelled: fue cancelada por el usuario.

Estados de una tarea:

• pending: aun no esta lista.
• ready: puede ejecutarse.
• in_progress: esta ejecutandose.
• completed: termino con resultado.
• failed: fallo al ejecutar.
• blocked: falta configuracion, credenciales, modelo, endpoint o agente valido.

Ejemplo completo

# 1. Configurar dos proveedores y sus perfiles
/provider claude profile main
/login
/model

/provider openai profile work
/login
/model

# 2. Crear el team con frontend en Claude y backend en OpenAI
/workspace setup core-dev orchestrator=backend claude/main:frontend openai/work:backend
/team show core-dev

# 3. Pedir el objetivo. /orchestrate planifica, muestra el plan
#    en pantalla y pregunta si ejecutar ya:
#    [Enter] = ejecuta y veras progreso + reporte final
#    [Esc]   = solo planifica, queda en estado 'planned'
/orchestrate core-dev crear login con UI y API

# 4. (Opcional) revisar la bitacora completa de mensajes
/run list
/run messages <run-id>

Notas importantes:

• Si /workspace setup solo asigno agente a frontend y backend, los dominios docs y planning apareceran como blocked con warnings al planear. No es un error: las tareas ready se ejecutan igual al pulsar Enter, y las bloqueadas las puedes asignar despues con /team domain core-dev docs <provider>/<agent> y reintentar con /run retry <run-id>.
• El reporte final que ves al terminar viene del orquestador global. Si quieres ver lo que cada orquestador local respondio, usa /run messages <run-id> o /run domain <run-id> <dominio>.

Seleccion automatica y fallback

La seleccion automatica permite que Context Code recomiende o aplique que agente debe tomar una tarea. El fallback permite cambiar una tarea fallida o bloqueada a otro agente compatible.

/policy

/policy muestra politicas predefinidas. Una politica indica como elegir agentes.

/policy list
/policy show score-with-fallback:quality

Modos disponibles:

• manual: usa el agente que ya estaba asignado.
• score: elige el mejor agente por puntaje.
• score-with-fallback: elige el mejor agente y guarda candidatos alternos.
• fallback-only: mantiene la asignacion inicial y solo cambia si algo falla.

Objetivos disponibles:

• balanced: equilibrio general.
• cost: prioriza costo.
• latency: prioriza velocidad.
• quality: prioriza calidad.
• capability: prioriza especialidad declarada.
• resilience: prioriza estabilidad y opciones de recuperacion.

Formato:

modo:objetivo

Ejemplos:

score-with-fallback:quality
score:capability
score-with-fallback:resilience
manual:balanced

Comandos de Fase 4

/run optimize <run-id> [policy]
/run assign <run-id> [policy]
/run fallback <run-id> [task-id] [policy]
/run explain <run-id>

Que hace cada uno:

• /run optimize <run-id> score-with-fallback:quality simula la seleccion y muestra candidatos. No cambia tareas.
• /run assign <run-id> score:capability aplica la seleccion y asigna tareas abiertas.
• /run fallback <run-id> <task-id> score-with-fallback:resilience busca otro agente para una tarea fallida o bloqueada.
• /run explain <run-id> muestra las decisiones guardadas como mensajes policy.*.

Reglas importantes:

• cada decision automatica queda guardada en SQLite
• /run optimize es seguro porque solo muestra recomendaciones
• /run assign y /run fallback si cambian tareas
• un agente deshabilitado no debe ser elegido
• si falta perfil, modelo o credenciales, la tarea puede quedar blocked
• errores de autenticacion no deben reintentarse agresivamente

Datos guardados en SQLite

La base se crea automaticamente en:

~/.context/provider-state.sqlite3

Ademas de perfiles y credenciales de providers, ahi se guardan:

• provider_workspaces: proveedores disponibles para equipos
• provider_agents: agentes por proveedor/perfil
• provider_agent_capabilities: capacidades declaradas de agentes
• teams: equipos
• team_domains: areas de trabajo dentro de un equipo
• team_domain_members: miembros de cada area
• orchestration_runs: corridas
• orchestration_tasks: tareas
• orchestration_messages: bitacora de decisiones y eventos
• orchestration_task_results: resultados por tarea
• orchestration_domain_reports: reportes por area
• orchestration_run_reports: reporte consolidado de una corrida
• secure_storage: credenciales cifradas y configuracion sensible de providers, Telegram y WhatsApp en Windows/Linux

Limitaciones actuales

• La calidad de la ejecucion depende de que cada agente tenga perfil, modelo y credenciales validas.
• La seleccion automatica ya existe, pero las politicas personalizadas editables todavia no estan persistidas con /policy create.
• El fallback es auditable y controlado, no un sistema de retries infinitos.
• Si varios proveedores producen respuestas incompatibles, el usuario debe revisar el consolidado antes de cerrar la corrida.

Puentes con mensajería móvil

Context Code puede conectarse con Telegram y WhatsApp para que veas y respondas la conversación completa desde tu móvil. Cada mensaje que escribes en la terminal se refleja en el chat, cada respuesta del modelo llega de vuelta, y cada herramienta que ejecuta el asistente (Bash, Read, Edit…) se resume en una línea. También puedes escribir desde el móvil y el texto se inyecta al REPL como si lo hubieras tecleado en la terminal — la conversación es la misma, da igual por dónde entres.

Los dos puentes funcionan de forma independiente: puedes usar solo Telegram, solo WhatsApp, o los dos a la vez.

Qué se sincroniza

• De la terminal al móvil: tus prompts (👤), las respuestas de texto del modelo (🤖) y una línea por cada tool call (🔧 Bash: npm test, 🔧 Read: src/foo.ts, etc.). No se manda el output crudo de las herramientas para no saturar el chat.
• Del móvil a la terminal: cualquier texto que envíes aterriza en la cola de entrada del REPL con la misma prioridad que si lo hubieras escrito en la CLI.
• Antiduplicado: si escribes desde el móvil, ese texto no se reenvía de vuelta al mismo canal. El otro canal sí lo recibe (si está activo).
• Código no sincronizado: mensajes internos del sistema, salidas de slash commands y otros eventos auxiliares no se envían a los canales.

/telegram — Bridge con Telegram

Usa la Bot API oficial de Telegram vía grammy. Requiere crear un bot en @BotFather y darle al wizard el token.

Flujo en 3 pasos:

1. Intro con instrucciones para crear el bot en @BotFather (/newbot, nombre, username, token).
2. Pegar el token — input con validación de formato 123456789:ABC-....
3. Iniciar bot — el bridge queda corriendo.

Desde el móvil, envía /start al bot y ese chat queda registrado como destinatario primario. El bot también responde a /status, /model <nombre> y /provider <nombre> para cambiar proveedor o modelo desde Telegram.

Comandos dentro de la CLI:

/telegram   # abre el wizard (alias: /tele, /bot)

El token queda guardado localmente en la config (~/.context/...) y nunca sale del equipo.

/whatsapp — Bridge con WhatsApp

Usa Baileys (@whiskeysockets/baileys) vía WhatsApp Web para vincular una cuenta como dispositivo enlazado. Baileys es opcional: solo se carga cuando ejecutas /whatsapp por primera vez, así no pesa en la instalación base. El QR se dibuja en la terminal usando el paquete qrcode, ya incluido en el proyecto.

⚠️ Aviso importante. Baileys es una librería no-oficial. Conectarse por esta vía viola los Términos de Servicio de WhatsApp. Para uso personal en un proyecto privado rara vez pasa nada, pero el número que uses podría ser baneado por WhatsApp en casos extremos. Se recomienda usar un número dedicado para el bot (eSIM, número secundario, etc.), no tu WhatsApp personal.

Flujo en 5 pasos:

1. Intro + aviso de riesgo.
2. Escanear QR — el wizard dibuja el QR en la terminal. En el móvil del bot: WhatsApp → Dispositivos Vinculados → Vincular un dispositivo → escaneas.
3. Tu número (destinatario primario) — el número en formato E.164 (+573001234567) donde quieres recibir el espejo. También puedes saltar y el primer número que escriba al bot se auto-registra.
4. Allowlist de números autorizados — agregas los números que pueden escribirle al bot. Los mensajes de números fuera de la lista se ignoran en silencio.
5. Iniciar bridge — el bridge queda corriendo.

Desde el panel de ejecución puedes detener el bridge, gestionar la lista de autorizados o cambiar el destinatario sin reiniciar.

Comandos dentro de la CLI:

/whatsapp   # abre el wizard (alias: /wa, /whats)

Las credenciales de sesión de WhatsApp Web se guardan como archivos en ~/.context/whatsapp-auth/ (respetando CLAUDE_CONFIG_DIR si está definido), porque Baileys necesita manejar ese directorio de auth. La configuracion lógica del bridge, como destinatario primario, allowlist, identidad vinculada y estado running, se guarda en SQLite mediante secure_storage en Windows/Linux.

Configuración guardada

Ambos bridges persisten su configuracion en el storage seguro. En Windows/Linux esto vive cifrado dentro de ~/.context/provider-state.sqlite3; en macOS se mantiene el backend de keychain/fallback disponible.

{
  "telegramBot": {
    "token": "…",
    "allowedUserIds": [123456],
    "primaryChatId": 123456,
    "isRunning": true
  },
  "whatsappBot": {
    "authDir": "~/.context/whatsapp-auth",
    "primaryRecipient": "+573001234567",
    "allowedNumbers": ["+573001234567", "+573109876543"],
    "selfJid": "[email protected]",
    "selfE164": "+573...",
    "running": true
  }
}

Si existe configuracion vieja en el archivo JSON global, se migra automaticamente al leer o actualizar el bridge y se elimina esa clave legacy para evitar dos fuentes de verdad.

Ritmo de envío

Cada canal usa una cola con throttling para no dispararse contra los rate limits de la plataforma:

• Telegram: 150 ms entre mensajes (~6 msg/s, bien por debajo del límite oficial de 30 msg/s por bot).
• WhatsApp: 500 ms entre mensajes (más conservador — Baileys no publica límites formales y enviar demasiado rápido puede disparar shadow-bans).

Si escribes prompts muy rápido la cola se llena hasta 200 items, y a partir de ahí descarta el más viejo para no crecer sin límite.

Ejemplo completo de flujo de trabajo

Este ejemplo muestra un flujo real de principio a fin. Puedes cambiar claude, openai, minimax u ollama por los proveedores que tengas configurados.

1. Preparar el primer proveedor

Activa el proveedor, inicia sesion y elige modelo.

/provider claude profile main
/login
/model

Verifica que quedo activo:

/status

Debes revisar que aparezcan proveedor, perfil activo, modelo guardado y credenciales configuradas.

2. Preparar otro proveedor

Repite el proceso para otro proveedor. En este ejemplo OpenAI sera backend.

/provider openai profile work
/login
/model
/status

Si usas Ollama local, normalmente seria:

/provider ollama profile local
/model
/status

3. Crear el equipo con el wizard

Abre el wizard:

/workspace setup

Desde ahi puedes elegir:

• Preparar proveedor/perfil: seleccionas proveedor, escribes perfil y el sistema lanza /provider. Si faltan credenciales, se abre login/configuracion; despues te lleva a /model.
• Crear equipo y elegir orquestador: escribes el nombre del equipo, eliges si el orquestador sale de un perfil existente, de un perfil nuevo, de un area o de un agente ya creado, y luego el input queda listo para completar proveedores, perfiles y areas con autocompletado.

Si ya sabes los perfiles y areas, puedes saltarte el wizard y crear el equipo base en un solo comando:

/workspace setup core-dev orchestrator=backend claude/main:frontend openai/work:backend
/team show core-dev

En este ejemplo:

• core-dev es el equipo.
• claude/frontend-lead coordina el equipo completo.
• frontend queda asignado a Claude.
• backend queda asignado a OpenAI.

Si quieres hacerlo a mano, todavia puedes usar /workspace enable, /agent create, /agent set-role, /team create, /team orchestrator y /team domain. El wizard solo junta esos pasos para evitar errores.

4. Crear una corrida y revisar el plan en pantalla

/orchestrate core-dev crear login con UI y API

A diferencia de versiones anteriores, /orchestrate no se queda en silencio: te muestra una vista resumen con la run creada, las tareas por dominio, advertencias y un prompt:

Plan listo para core-dev
Run: 1b4fb901-...
Objetivo: crear login con UI y API
Orquestador global: openai/backend-lead

Tareas por dominio
- backend  -> ready   | assigned=openai/backend-lead
- docs     -> blocked | assigned=sin asignar
- frontend -> ready   | assigned=claude/frontend-lead
- planning -> blocked | assigned=sin asignar

Listas: 2 | Bloqueadas: 2

Advertencias
- docs: warning -> No hay agente asignable para este dominio.
- planning: warning -> No hay agente asignable para este dominio.

[Enter] Ejecutar ahora (las bloqueadas se omiten)  |  [Esc] Solo planificar

5. Decidir: ejecutar ya, o revisar y ejecutar despues

• Pulsa Enter y empezara la ejecucion al instante. Solo se disparan las tareas ready. Mientras corren, veras lineas de progreso por dominio. Al final llega el reporte consolidado.
• Pulsa Esc si prefieres revisar antes. La run queda en planned. Despues puedes inspeccionarla con:

/run show <run-id>
/run tasks <run-id>
/run domain <run-id> frontend
/run domain <run-id> backend

Si una tarea aparece blocked, normalmente falta agente, workspace, perfil, modelo o credencial. Asigna lo que falte y vuelve.

6. Ejecutar manualmente cuando hayas pulsado Esc

/run resume <run-id>

Luego revisa resultados:

/run show <run-id>
/run messages <run-id>

Si quieres ver una tarea concreta:

/run task <task-id>

7. Usar seleccion automatica antes de reasignar

Si quieres ver que agente recomienda el sistema sin cambiar nada:

/policy list
/policy show score-with-fallback:quality
/run optimize <run-id> score-with-fallback:quality

Si la recomendacion te parece correcta, puedes aplicarla:

/run assign <run-id> score:capability

Para ver por que se tomaron decisiones:

/run explain <run-id>

8. Recuperar errores o bloqueos

Si una tarea fallo o quedo bloqueada, puedes reintentar:

/run retry <run-id>

O reintentar solo una tarea:

/run retry <run-id> <task-id>

Si quieres cambiarla a otro agente manualmente:

/run reassign <task-id> claude/frontend-lead
/run resume <run-id>

Si quieres que el sistema busque otro agente compatible:

/run fallback <run-id> <task-id> score-with-fallback:resilience
/run resume <run-id>

9. Cerrar o cancelar

Si todo termino bien:

/run show <run-id>

Si necesitas detener la corrida:

/run cancel <run-id>

Resumen corto

/provider claude profile main
/login
/model

/provider openai profile work
/login
/model

/workspace setup core-dev orchestrator=backend claude/main:frontend openai/work:backend
/team show core-dev

/orchestrate core-dev crear login con UI y API
# Aqui ves el plan en pantalla.
# [Enter] ejecuta ya y muestra el reporte final.
# [Esc]   te deja la run en 'planned'; ejecuta despues con /run resume <run-id>.

/run messages <run-id>   # bitacora completa cuando quieras revisarla

Cuando algo no avanza

Sintomas comunes despues de /orchestrate o /run resume, y como salir de cada uno.

"El plan se quedo en planned y no pasa nada"

Pulsaste Esc (o cerraste la vista) en lugar de Enter. La run existe pero no se ejecuto. Reanuda cuando quieras:

/run resume <run-id>

"Aparecen dominios blocked que yo no pedi"

Cuando creas un team con /workspace setup y solo das agente a algunos dominios (por ejemplo frontend y backend), los demas (docs, planning, etc.) se crean igual y quedan sin asignar. Al planear se reportan como blocked con el warning No hay agente asignable para este dominio.. Tienes dos salidas:

• Ignorarlos: pulsas Enter, las tareas ready se ejecutan y las blocked se quedan asi. La run se reporta como failed o completed segun lo que avance.
• Asignar agente y reintentar:

  /team domain <team> docs <provider>/<agent>
  /team domain <team> planning <provider>/<agent>
  /run retry <run-id>

"Mi proveedor devolvio usage_limit_reached o rate_limit"

Pasa cuando un proveedor alcanza el limite de tokens/segundo o de plan. La tarea afectada queda failed. Opciones:

• Cambiar de perfil del mismo proveedor con /profile use <proveedor> <otro-perfil> y reintentar.
• Reasignar la tarea a otro agente:

  /run reassign <task-id> <provider>/<agent>
  /run resume <run-id>

• Pedir al sistema que busque un agente alterno:

  /run fallback <run-id> <task-id> score-with-fallback:resilience
  /run resume <run-id>

"Faltan credenciales o el modelo no esta configurado"

Verifica el estado del perfil:

/status

Si falta token, modelo o base URL, vuelve a /login y /model para ese perfil. La tarea queda blocked hasta que el agente tenga todo lo que necesita.

"Quiero detener una corrida en marcha"

/run cancel <run-id>

"Quiero ver que dijo cada orquestador local antes del reporte final"

/run messages <run-id>
/run domain <run-id> <dominio>
/run task <task-id>

/run messages te lista en orden cronologico todos los global-plan, squad-plan, domain-report, run-report y eventos de policy de la corrida.

Servidores MCP externos

Context Code soporta el Model Context Protocol. Puedes conectar servidores MCP de terceros para dar a los agentes herramientas extra: leer una base de datos, consultar Sentry, hablar con tu wiki interna, etc.

Comandos:

/mcp                                           # abre el panel de servidores configurados
/mcp add <name> -- <command> [args...]         # registra un servidor stdio
/mcp add --transport http <name> <url>         # registra un servidor HTTP
/mcp add --transport sse <name> <url>          # registra un servidor SSE

Tambien puedes registrar servidores con --scope project (escribe en .mcp.json del proyecto) o --scope user (queda solo para tu usuario). El default es project cuando estas dentro de un repo y user cuando no.

Ejemplo: conectar una base de datos SQLite

Existen servidores MCP listos para hablar con bases de datos. El mas conocido es mcp-server-sqlite. Lo instalas y lo registras:

# 1. Instalar el servidor (o usar npx para no instalar)
pip install mcp-server-sqlite

# 2. Registrarlo en Context Code apuntando a tu DB
/mcp add sqlite-local -- mcp-server-sqlite --db-path ./data/app.sqlite

A partir de ese momento, los agentes que ejecuten en este proyecto pueden listar tablas, hacer SELECT y describir el esquema sin que tu tengas que escribir SQL ni copiar/pegar resultados.

Ejemplo: conectar Postgres

# Con uvx (recomendado, sin instalacion previa)
/mcp add postgres-prod --transport stdio -- uvx mcp-server-postgres \
  --connection-string "postgres://user:pass@localhost:5432/mydb"

# O con un servidor HTTP ya desplegado
/mcp add postgres-prod --transport http https://mcp.midominio.com/postgres \
  --header "Authorization: Bearer $TOKEN"

Pasos a tener en cuenta:

• Los servidores MCP corren con tus permisos. Si conectas a una DB de produccion, considera dar al servidor solo credenciales de lectura.
• Variables sensibles: usa -e VAR=valor al registrar el server stdio para inyectar tokens sin que queden en el comando visible.
• Las herramientas MCP aparecen en los agentes con prefijo mcp__<name>__<tool>. Puedes restringir cuales se autorizan con --allowedTools al iniciar la sesion.
• Si un dominio (database, por ejemplo) tendria que usar este MCP, asignale un agente con /team domain <team> database <provider>/<agent> y el orquestador local lo invocara cuando el plan lo requiera.

Diferencia con el storage interno

El archivo ~/.context/provider-state.sqlite3 es persistencia interna del CLI (perfiles, runs, credenciales). No es un MCP y los agentes no lo consultan directamente; solo el runtime lo lee/escribe. Si quieres exponer datos de una base a los agentes, registra un servidor MCP como en los ejemplos de arriba.

Limites y uso por proveedor

/limites (alias /limits) consulta cada proveedor configurado y te muestra cuanto has consumido, cuanto te queda y los limites de tu plan, en una sola vista.

/limites

Que hace:

1. Itera sobre todos los provider profile que tienes guardados.
2. Para cada uno, si hay un adapter implementado, llama a su API real en paralelo (con timeout).
3. Suma a la respuesta el contador local de tokens del CLI: cuantos tokens ha consumido este perfil en la sesion actual y en el historico persistido en SQLite.

Estado de cada proveedor:

| Proveedor | Que se consulta | |----------------|-----------------------------------------------------------------------------------------------------------------------| | Claude (OAuth) | GET /api/oauth/usage -> ventanas (5h/7d/Opus/Sonnet) y extra usage. Reusa el cliente que alimenta a /usage | | Anthropic API | no-data — solo headers anthropic-ratelimit-* por llamada | | OpenAI OAuth | no-data — Codex/ChatGPT solo exponen rate limits dentro del TokenCountEvent de cada respuesta del modelo | | OpenAI API | GET /v1/usage (requiere admin key); si la key no tiene permiso, no-data | | OpenRouter | GET /api/v1/auth/key -> creditos, limite, rate limit | | MiniMax | GET /v1/token_plan/remains -> uso por modelo (endpoint reverse-engineered desde MiniMax-AI/cli mmx quota show) | | Z.AI | GET /api/monitor/usage/quota/limit -> tokens usados/limite del coding plan | | Ollama local | Siempre ok (ilimitado, corre en tu maquina); cuenta modelos disponibles | | Ollama Cloud | no-data salvo localhost |

El contador local de tokens funciona para todos los proveedores por igual: se persiste en ~/.context/provider-state.sqlite3 y te permite saber cuanto has gastado aunque el proveedor no exponga API. La cuenta empieza en cero la primera vez que ejecutas /limites despues de instalar.

Comandos relacionados:

/limites          # vista interactiva por proveedor
/usage            # solo Claude: limites del plan vistos por Settings
/cost             # costo de la sesion actual

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