Ritoko

Ritoko — automatización de navegador reanudable para agentes de IA

Resuelve una tarea una vez. Guarda el procedimiento. Ejecútalo de nuevo con datos nuevos.

Ritoko es una herramienta de automatización de navegador y automatización robótica de procesos (RPA) de código abierto para agentes de IA. Convierte una tarea resuelta en un flujo de trabajo reutilizable de navegador, API HTTP o MCP; ejecuta lotes de CSV o Excel; verifica resultados y reanuda trabajos interrumpidos con un diario local de SQLite.

Úsalo como plugin de Claude Code o Codex, servidor local de Protocolo de Contexto de Modelo (MCP) o CLI independiente. El motor de reproducción directa ejecuta flujos guardados sin llamar a un LLM; una herramienta MCP conectada puede usar IA por sí misma.

Probar localmente · Inicio rápido · Casos de uso · Cómo funciona · Ejemplo de flujo de trabajo · Preguntas frecuentes · Guía avanzada

Mira la demo de 34 segundos — ejecución en tiempo real contra una aplicación de prueba local. Mata el proceso después del quinto envío, reanuda y luego vuelve a ejecutar el mismo CSV: 10 envíos recibidos, 10 únicos, una fila aún pendiente de confirmación. Resultados y entorno grabados.

¿Por qué usar Ritoko?

Un agente puede descubrir cómo ingresar un cliente, descargar un informe o llamar a una herramienta de negocio. Un lote recurrente también necesita un formato de entrada, una regla para identificar cada registro, una verificación de éxito y una forma de recuperarse tras una interrupción.

Ritoko mantiene esas decisiones en un procedimiento reutilizable:

• Reutiliza el trabajo. Guarda parámetros, selectores, llamadas API y reglas de verificación en un flujo de trabajo JSON legible.
• Procesa datos nuevos. Alimenta el procedimiento con otro archivo CSV o Excel en lugar de explicar los mismos pasos para cada fila.
• Recupérate con evidencia. Ve qué elementos terminaron, fallaron o tienen un resultado incierto. Los elementos confirmados se omiten en ejecuciones posteriores; las escrituras inciertas quedan retenidas para revisión.

Con una búsqueda de destino configurada, Ritoko también puede verificar antes de crear un registro (ensure) y resolver un resultado incierto leyéndolo de vuelta (reconcile). Estas funciones de 0.2.0 requieren un GET HTTP directo o una herramienta MCP confiable y explícitamente de solo lectura, con reglas separadas que prueben presencia y ausencia. Una búsqueda fallida bloquea la fila. Configuración y límites.

Por ejemplo: enseña a tu agente a crear un cliente, guarda customer-import, luego pídele que procese la hoja de cálculo de la próxima semana e informe cada resultado.

¿Qué puedes automatizar?

Ritoko se adapta a tareas repetidas con reglas explícitas y resultados verificables. Una tarea nueva aún necesita un agente o un autor de flujo que entienda el sitio y defina el procedimiento.

Inicio rápido

Prueba diez clientes falsos localmente

Con Node.js 24+, en un directorio vacío:

npm install ritoko@0.2.0
node node_modules/ritoko/examples/first-run/demo.mjs

La demo inicia un servicio HTTP de bucle local, crea diez clientes CSV falsos, verifica cada registro leyéndolo de vuelta, luego vuelve a ejecutar y comprueba que las diez filas se omiten sin escrituras adicionales. No necesita cuenta, clave API ni Chrome. El diario está aislado en un directorio temporal que imprime el comando. Esto prueba una simulación local; la interrupción del navegador y la reconciliación de destino son pruebas separadas. Guía en inglés/francés y resultados esperados.

El npm 0.2.0 publicado incluye esta demo y las funciones ensure, reconcile y doctor.

1. Instala en tu agente

Requiere Node.js 24 o más reciente. Los flujos de navegador que usan el ejecutor directo también necesitan Google Chrome. Los flujos HTTP/MCP independientes pueden ejecutarse sin navegador.

ensure, reconcile, doctor y la demo de primer intento requieren 0.2.0 o más reciente. Consulta los lanzamientos versionados y las puertas de lanzamiento antes de actualizar una instalación fijada.

Claude Code

claude plugin marketplace add Swih/ritoko
claude plugin install ritoko@ritoko

Codex CLI

codex plugin marketplace add Swih/ritoko
codex plugin add ritoko@ritoko

Reinicia el cliente después de la instalación. El plugin de Git incluye la habilidad del agente y un servidor MCP local; su lanzador instala dependencias de ejecución fijadas en el primer inicio, con scripts de ciclo de vida de npm deshabilitados.

Para lotes largos de Codex, configura el tiempo de espera de llamada a herramienta antes de ejecutar.

{
  "mcpServers": {
    "ritoko": {
      "command": "npx",
      "args": ["--yes", "--prefer-online", "ritoko@latest", "mcp"]
    }
  }
}

2. Elige el navegador o la integración

Dile al agente qué navegador quieres que use. El ejecutor directo se conecta a Chrome personal después de habilitar la depuración remota en chrome://inspect/#remote-debugging y permitir la conexión. Elige RITOKO_BROWSER=clean explícitamente para un perfil separado.

Un navegador de agente compatible puede ejecutar flujos de host cuando permite la ejecución de scripts de página. El uso de computadora actual de Codex evaluate es de solo lectura, por lo que no puede ejecutar la reproducción del navegador host. Los lotes de solo API de host y de herramientas MCP conectadas siguen disponibles. Consulta selección de navegador y límites de confianza.

3. Enseña una tarea, luego reutilízala

Pregunta a tu agente:

Registra una importación de clientes con Ritoko en este back office. Usa el navegador que seleccioné. Guárdalo como customer-import con un parámetro de hoja de cálculo input. Usa Email como clave de negocio y verifica el email del cliente creado.

Si la demostración creó un registro real, el agente debe adoptar esa fila ya enviada con run_adopt y evidencia antes de reproducir el lote.

Luego:

Ejecuta customer-import en el mismo back office con input establecido en la ruta absoluta de customers.csv. Muéstrame los elementos confirmados, fallidos y en revisión, más cualquier archivo guardado.

Después:

Reanuda mi última ejecución de Ritoko.

Muestra el informe de mi última ejecución y explica qué elementos aún necesitan revisión.

Cómo funciona

flowchart LR
    A["Describe a task"] --> B["Agent records or authors it"]
    B --> C["Save a JSON workflow"]
    C --> D["Replay with new data"]
    D --> E["Journal and verify each item"]
    E --> F["Report results and review holds"]

1. Define. El agente graba acciones del navegador o escribe pasos compatibles de API/MCP. El grabador prefiere etiquetas únicas, roles y otros selectores significativos; los selectores posicionales frágiles se marcan.
2. Guarda. El flujo declara sus parámetros, entrada, clave de negocio, límite de envío (commit) y verificaciones de resultado (expect).
3. Reproduce. El motor directo ejecuta los pasos guardados. El modo host permite que un agente compatible ejecute acciones de navegador compatibles o herramientas conectadas.
4. Diario y recuperación. SQLite mantiene el flujo y las filas de entrada de cada ejecución. Un lote reanudado usa esa instantánea, incluso si la hoja de cálculo original cambia. Una página modificada puede pausar para reparación; un envío incierto queda retenido para revisión.

¿Qué sucede después de un fallo?

Una ejecución está completa solo cuando sus elementos están confirmados u omitidos y sus verificaciones finales pasan. Un resultado parcial o una pausa de reparación es visible en el informe y devuelve el código de salida CLI 2.

La calidad de la verificación importa. Un recibo, ID de registro o email de cliente coincidente puede probar el resultado deseado. Un banner genérico de “Éxito” generalmente no puede. El diario rastrea esta instalación de Ritoko; no puede prevenir envíos independientes ni garantizar que un sitio remoto sea idempotente.

¿Cómo se ve un flujo de trabajo?

Este flujo de navegador ilustrativo crea un cliente por fila de hoja de cálculo. Adapta la URL, etiquetas y selector de resultado a tu aplicación antes de guardarlo.

{
  "name": "customer-import",
  "version": 1,
  "description": "Create customers and verify their email.",
  "params": {
    "base": { "description": "Back-office base URL" },
    "input": { "description": "Absolute CSV or XLSX path" }
  },
  "items": {
    "from": "{{param.input}}",
    "key": "{{item.Email}}",
    "scope": "{{param.base}}"
  },
  "item": [
    {
      "do": "goto",
      "url": "{{param.base}}/customers/new"
    },
    {
      "do": "fill",
      "target": { "primary": { "by": "label", "text": "Email" } },
      "value": "{{item.Email}}"
    },
    {
      "do": "click",
      "target": {
        "primary": { "by": "role", "role": "button", "name": "Create customer" }
      },
      "commit": true
    },
    {
      "do": "expect",
      "target": { "primary": { "by": "testid", "id": "customer-email" } },
      "text": "{{item.Email}}"
    }
  ]
}

key identifica el registro comercial; el scope de este ejemplo separa las URLs de destino. Incluye el identificador de cuenta en el alcance si varias cuentas comparten una URL. El commit marca la acción irreversible, y el siguiente expect verifica esa fila específica. Los lotes de solo lectura declaran readOnly: true.

Consulta ejemplos completos de flujos de trabajo, el esquema de flujo y la referencia HTTP/MCP.

Usa la CLI sin un agente

Desde un checkout de Git, el lanzador puede importar y ejecutar un flujo existente sin un agente ni una clave API de LLM:

git clone https://github.com/Swih/ritoko.git
cd ritoko
node bin/ritoko.mjs import examples/rpa-challenge.json
node bin/ritoko.mjs run rpa-challenge
node bin/ritoko.mjs report

El ejemplo de RPA Challenge descarga su propia entrada de Excel. Elige el navegador directo como se describió antes de ejecutarlo. Para ejecutar intencionalmente este mismo desafío de nuevo, agrega --repeat; las retenciones de revisión siguen bloqueadas.

Para una ejecución directa interrumpida, usa node bin/ritoko.mjs resume <runId>. Los flujos, diarios, evidencia y archivos de salida viven en ~/.ritoko por defecto; anula con RITOKO_HOME.

Usa node bin/ritoko.mjs doctor para inspeccionar la configuración local antes de solucionar un lote. Para una fila en revisión con una búsqueda de destino configurada, node bin/ritoko.mjs reconcile <runId> <key> lee el resultado sin enviarlo de nuevo. El resolve manual requiere una nota y --confirm-checked después de que inspecciones el destino tú mismo.

Evidencia y alcance actual

Las demos grabadas usaron Ritoko 0.1.0 en Windows con Chrome sin interfaz. El temporizador del sitio RPA excluye instalación y configuración; el tiempo de pared CLI grabado fue 3.559 s. RPA Challenge no tiene recibo por fila, por lo que su ejemplo depende de la puntuación final. Estas demostraciones y pruebas controladas no establecen una tasa de confiabilidad o rendimiento para cada sitio web.

Preguntas frecuentes

¿Necesito una clave API de LLM separada?

El runner determinista de Ritoko no requiere uno. Cuando usas el plugin, tu agente cliente proporciona el razonamiento a través de su suscripción existente o configuración de API. La grabación, reparación y orquestación del host siguen usando ese cliente, y las herramientas conectadas pueden llamar a modelos por sí mismas. Las API externas, proveedores de OCR o servicios de generación de pago requieren su propio acceso y pueden cobrar por separado.

¿Ritoko lee facturas o realiza OCR?

La lectura de documentos es opcional. document_image devuelve un JPEG/PNG descargado al agente cliente para que su modelo lo lea. Ritoko no incluye un motor OCR local ni un analizador de facturas. Un servicio OCR externo elegido utiliza credenciales configuradas por el usuario. Cada nueva imagen aún necesita al agente o a ese servicio; la reproducción ordinaria de navegador y API no lo hace.

¿Puede Ritoko usar mi navegador con sesión iniciada?

El runner directo puede conectarse a Chrome personal con tu permiso de depuración remota. Puedes elegir explícitamente un perfil limpio separado. El soporte integrado del navegador depende de las acciones permitidas del cliente; consulta límites del driver. Completa el inicio de sesión o MFA en el navegador seleccionado cuando sea necesario.

¿Puedo usar Ritoko con cualquier cliente MCP?

Un cliente local que pueda lanzar un proceso stdio puede conectarse al servidor. Claude Code y Codex CLI son los clientes plugin probados. Otros clientes necesitan configuración y verificaciones de capacidades. Un cliente en la nube aislado no puede acceder a tu proceso MCP local ni a tus archivos sin un mecanismo de conexión separado.

¿Ritoko garantiza que no haya escrituras duplicadas?

No. Omite elementos confirmados y bloquea escrituras inciertas dentro de su diario, incluso en ejecuciones futuras. El flujo de trabajo necesita la clave de negocio correcta, el alcance de destino y las verificaciones de resultados. Las presentaciones independientes y el comportamiento del sistema remoto quedan fuera de ese diario. Resolver un elemento de revisión requiere evidencia sobre lo que realmente sucedió.

¿Puede una grabación de navegador convertirse en un flujo de trabajo de API?

La captura de red opcional proporciona metadatos fetch/XHR para ayudar al agente a investigar una API. No convierte grabaciones en pasos de API ejecutables automáticamente. Verifica el contrato de la API y la autenticación, prueba una fila autorizada y luego guarda explícitamente el reemplazo. Consulta sugerencias de red.

Documentación y contribuciones

• Uso avanzado: configuración del cliente, CLI, opciones de navegador, lotes de host, recuperación y reglas de flujo de trabajo.
• Habilidad del agente: instrucciones para grabar, ejecutar, adoptar y reparar flujos de trabajo.
• Referencia de integración: formatos de entrada, formas de pasos HTTP/MCP y límites del driver.
• Guías de problemas y comparaciones de herramientas: elige un flujo de trabajo y comprende sus compensaciones.
• Medición de visibilidad en búsquedas: indicaciones fijas en inglés/francés e informes basados en respuestas capturadas.
• Puertas de lanzamiento: verificaciones requeridas, hoja de ruta de validación, publicación y políticas de actualización.
• Privacidad del software local: datos de ejecución almacenados, destinos configurados, credenciales y retención.
• Reportar un error o solicitar una función: incluye el cliente, versiones de Node/navegador/SO y una reproducción redactada. Mantén privadas las credenciales y los datos comerciales.

Para desarrollo, usa Node.js 24+ y pnpm:

pnpm install
pnpm check
pnpm test
pnpm build
pnpm test:e2e

Ritoko automatiza servicios que estás autorizado a usar. No evade CAPTCHAs ni protecciones anti-bots. Los flujos de trabajo y comandos API/MCP son configuración ejecutable y requieren un autor de confianza.

Creado por Swih con Claude (Anthropic) y Codex (OpenAI), acreditados como contribuyentes en el historial de Git. Publicado bajo la licencia MIT.