Kit copiable · Claude Code + Codex · con la suscripción

Tus agentes usando las herramientas que ya tienes

Una carpeta runtime/ que enseña a Claude Code y Codex a descubrir, conectar y usar tus sistemas, con reglas claras sobre lo que pueden hacer por su cuenta. Sin servidor ni API de pago.

Empezar la guía Ver en GitHub
Banner de INEMA Agent Runtime: agentes que usan tus herramientas, con la suscripción y una política de permisos
Qué es

Un kit, no una plataforma

Cuatro archivos de reglas, scripts de diagnóstico y verificación, puentes, una protección y 7 recetas probadas. Lo copias en tu proyecto y los agentes empiezan a seguir las mismas reglas. Los archivos de runtime/ están en portugués; tu agente los lee y te responde en tu idioma.

Los bloques del kit: escalera de vías, capacidades, política, enrutamiento, puente MCP y recetas

🪜 Escalera de vías

Antes de decir «imposible», el agente sube la escalera API → MCP → CLI → SDK → uso del ordenador → puente local y usa la vía más estable disponible.

🛡️ Política de permisos

Leer es libre; al modificar un archivo, lo hace y te avisa; para enviar, pregunta antes; si implica gastar dinero o borrar datos, solo lo prepara. .claude/settings.json ya bloquea rm -rf.

💳 Con la suscripción

Usa Claude Code y Codex CLI, donde ya tienes la sesión iniciada. No hace falta ninguna API de pago. Los modelos locales de Ollama son opcionales.

Cómo funciona

El ciclo del runtime

Cada etapa tiene un archivo. Toda acción pasa por POLITICA.md.

Descubrir→ Conectar→ Enrutar→ Ejecutar→ Observar→ Verificar→ Aprender
1

CAPACIDADES.md

Mapa de herramientas: una línea por sistema, con la vía, el nivel y la fecha de la prueba. Los sistemas sin línea no se usan.

2

POLITICA.md

Niveles de autonomía N0 a N4 y el límite de cada tipo de acción. «Permitir siempre» nunca supera el límite.

3

ROTEAMENTO.md

Qué modelo usar para cada tarea (súper, superior, ejecutor, menor). Empieza por el más pequeño que la resuelva.

4

LEIA-ME.md

El ciclo, el orden para empezar y la escalera de vías con ejemplos.

La escalera de vías (usa la más alta disponible)

NivelVíaEjemploEstabilidad
1API oficialAPI del ERPalta
2MCPclaude mcp listalta
3CLIcodex exec, gh, gitalta
4SDK / bibliotecapaquete npm/pipmedia
5Uso del ordenadornavegador automatizado, clics en pantallabaja
6Puente localexportación CSV, carpeta, base de datos SQLite, puerto localmedia
7Ingeniería inversaobservar la app en ejecución para encontrar la víasolo laboratorio: se rompe con la siguiente actualización

Límite por tipo de acción

AcciónLímiteEn Claude CodeEn Codex
Leer archivo, página, hoja de cálculoN4permitido-s read-only
Crear/modificar archivo del proyectoN3acceptEdits-s workspace-write
Comando que modifica el sistemaN2pide confirmaciónsin aprobación automática
Enviar (correo electrónico, mensaje, publicación, push)N2pide confirmaciónsin aprobación automática
Gastar dinero o créditoN1bloqueadono ejecutar
Borrar datos / producciónN1 + copia de seguridadbloqueado (rm -rf)no ejecutar

N0 solo conversa · N1 prepara y la persona ejecuta · N2 ejecuta después de preguntar · N3 ejecuta y avisa · N4 ejecuta sin avisar. El agente no cambia sus propias reglas: propone una línea en la tabla «Aprendizaje» de POLITICA.md y tú la apruebas.

Requisitos previos

Qué debe estar instalado

Linux o Mac. En Windows, usa WSL. El diagnóstico solo lee versiones y estados locales: no llama a ningún modelo ni API.

Node 18+

Ejecuta el diagnóstico, el puente MCP y los scripts para observar y verificar.

node --version

Claude Code y/o Codex

Al menos uno de los dos, con la sesión iniciada mediante la suscripción.

npm i -g @anthropic-ai/claude-code
npm i -g @openai/codex
codex login

Ollama (opcional)

Modelos locales gratuitos para tareas ligeras. El diagnóstico indica si está instalado.

ollama --version
Guía de uso · paso a paso

Del clon al primer equipo de agentes

Cada receta termina con una prueba: un comando y el resultado que debe aparecer. Si la prueba no coincide, el paso no está listo.

1

Copia el kit y ejecuta el diagnóstico

Muestra lo que está instalado y tiene la sesión iniciada: Node, Claude Code, Codex y Ollama.

git clone https://github.com/inematds/inema-agent-runtime meu-projeto
cd meu-projeto
node runtime/scripts/doctor.mjs   # prueba: PRONTO al final
2

Completa el mapa de capacidades con el agente

Abre claude (o codex) en la carpeta y pídele que suba la escalera nivel por nivel. Solo se añade una línea si la prueba se ha hecho.

# dentro de claude o de codex:
Lee runtime/LEIA-ME.md y ayúdame a completar el CAPACIDADES.md para mi trabajo.
3

R1 · Claude usa Codex

Puente por CLI (nivel 3). Por defecto, Codex solo lee; para modificar archivos (N3), debes pasar workspace-write.

chmod +x runtime/pontes/codex-exec.sh
runtime/pontes/codex-exec.sh "Responde solo PONG"   # prueba: PONG
runtime/pontes/codex-exec.sh "Crea notas.txt con la palabra OK" "$PWD" workspace-write
4

R2 · Equipo de tres roles

Planificador (opus), ejecutor (sonnet) y revisor (haiku), definidos en .claude/agents/. Cada uno usa el modelo que necesita y el cupo rinde más.

claude -p "Usa el equipo (planificador, ejecutor, revisor). Tarea: crea saudacao.txt con la frase 'Olá, comunidade INEMA'. Termina con la respuesta del revisor."
# prueba: saudacao.txt tiene la frase y la respuesta termina con APROVADO
5

R3 · Puente MCP para un sistema sin API

El ERP o la agenda exportan un archivo; el puente lo lee y lo entrega al agente como herramienta de solo lectura. Servidor MCP sin dependencias, ya registrado en .mcp.json.

node runtime/pontes/mcp-modelo/server.mjs --selftest   # prueba: tools: 2 y TOTAL: R$ 856.00
claude mcp list                                         # ponte-modelo … Connected
codex mcp add ponte-modelo -- node "$PWD/runtime/pontes/mcp-modelo/server.mjs"
6

R4 · Equipo en segundo plano

Varias sesiones de Claude al mismo tiempo, cada una con nombre, rol y modelo. Marca la carpeta como confiable una vez. Cada sesión consume el cupo.

claude --bg --permission-mode plan --name revisor "Lee runtime/POLITICA.md y responde en una línea cuál es el límite de 'Enviar'."
claude --bg --model sonnet --name executor "Crea resumo.md con 3 líneas sobre qué es este kit."
node runtime/scripts/observar.mjs   # tabla con id, tipo, nombre y estado
7

R5 · Navegador con política

Para sistemas que solo existen como sitio web. Leer una página es N4; rellenar o enviar requiere preguntar antes; pagar, nunca.

npm i -g agent-browser
agent-browser install
agent-browser open https://example.com
agent-browser get title   # prueba: Example Domain
agent-browser close
8

R6 · Agente de larga duración con verificación

El agente solo termina cuando se cumplen los criterios comando → saída esperada del goal, y no cuando cree que ha terminado.

node runtime/scripts/verificar.mjs runtime/exemplos/goal-exemplo.md
# prueba: 4/4 critérios OK y salida 0; rompe un criterio y la línea pasa a FALHA
9

R7 · Protección y panel

Con varios agentes al mismo tiempo, la protección detecta dos riesgos antes de que ocurran y nunca decide por su cuenta: pregunta (N2). Colisión: antes de editar un archivo que otra sesión haya editado, o que haya cambiado por fuera (Codex, editor, otra persona) en los últimos 30 min. Radio: antes de rm o git clean, muestra cuántos archivos se borrarían, su tamaño y las primeras rutas. En este kit ya está activada mediante .claude/settings.json; para llevarla a otro proyecto, usa una de estas opciones: el comando de abajo o copiar el bloque hooks de .claude/settings.json y cambiar la ruta.

# protección en otro proyecto (solo en esta sesión)
claude --plugin-dir /caminho/do/kit/runtime/mods/runtime-guarda
# panel opcional: en la sesión, escribe /painel
claude --plugin-dir runtime/mods/runtime-painel
claude plugin test runtime/mods/runtime-painel   # prueba: 1 pass

El panel muestra las sesiones de claude --bg (nombre, estado, minutos), con Actualizar y Parar: solo tu clic detiene una sesión. INEMA_COLISAO_MIN=60 cambia el intervalo de colisión. Codex todavía no tiene un gancho equivalente de «antes de editar»: la protección cubre las sesiones de Claude y detecta las ediciones hechas por Codex mediante la fecha del archivo.

Ejemplos

De la oficina a la consulta

Los archivos de ejemplo en runtime/exemplos/ simulan los dos casos más comunes de la comunidad: un sistema sin API que exporta una hoja de cálculo.

🧾 Contable con ERP sin API

El ERP exporta un CSV de ventas. El puente expone la herramienta resumo_vendas; el equipo de R2 prepara el resumen y el revisor comprueba los totales.

# runtime/exemplos/erp-vendas.csv
data,cliente,produto,quantidade,valor_unitario
2026-10-01,Mercado Sol,Café 500g,10,18.50
# prueba del puente → TOTAL: R$ 856.00

🩺 Clínica con agenda en una hoja de cálculo

La agenda está en una hoja de cálculo. La herramienta listar_horarios_livres devuelve solo las filas livre, filtradas por fecha y profesional.

claude -p "Usa la tool listar_horarios_livres de la ponte-modelo y dime los horarios libres de 2026-10-07."
# prueba: 08:00 (Dra. Ana) y 16:00 (Dr. Bruno)

Para usarlo con tu sistema: indica PONTE_DADOS=/caminho/da/exportacao en el campo env de .mcp.json, cambia las columnas utilizadas en run(), mantén las herramientas en modo de solo lectura y anota el puente en CAPACIDADES.md con la fecha de la prueba.

Roadmap

Por fases, cada una con pruebas

Cada fase se cierra solo cuando se ejecutan las pruebas. Las pruebas realizadas de cada versión están en CHANGELOG.md.

Fase 1
Kit mínimo · 0.1.0 · listaCuatro archivos de convenciones, diagnóstico, puente codex-exec.sh, recetas R1 y R2 y bloqueos en .claude/settings.json. Pruebas ejecutadas en Linux con la suscripción.
Fase 2
Puentes, observar y verificar · 0.2.0 · listaPuente MCP sin dependencias, observar.mjs, verificar.mjs y recetas R3 a R6.
Fase 3
Protección y panel · 0.3.0 · listaMod runtime-guarda (colisión y radio, ya activado en el kit), mod opcional runtime-painel con /painel y receta R7.