Ritoko

Ritoko — automação de navegador retomável para agentes de IA

Resolva uma tarefa uma vez. Salve o procedimento. Execute-o novamente com novos dados.

Ritoko é uma ferramenta de código aberto de automação de navegador e automação robótica de processos (RPA) para agentes de IA. Transforme uma tarefa resolvida em um fluxo de trabalho reutilizável de navegador, API HTTP ou MCP, execute lotes de CSV ou Excel, verifique resultados e retome trabalhos interrompidos com um diário local SQLite.

Use-o como um plugin do Claude Code ou Codex, um servidor local de Model Context Protocol (MCP), ou uma CLI independente. O mecanismo de reprodução direta executa fluxos de trabalho salvos sem chamar um LLM; uma ferramenta MCP conectada pode, ela própria, usar IA.

Experimente localmente · Início rápido · Casos de uso · Como funciona · Exemplo de fluxo de trabalho · Perguntas frequentes · Guia avançado

Assista à demonstração de 34 segundos — execução em tempo real contra um aplicativo de teste local. Encerre o processo após o quinto envio, retome e execute novamente o mesmo CSV: 10 envios recebidos, 10 únicos, uma linha ainda aguardando confirmação. Resultados e ambiente gravados.

Por que usar o Ritoko?

Um agente pode descobrir como cadastrar um cliente, baixar um relatório ou chamar uma ferramenta de negócios. Um lote recorrente também precisa de um formato de entrada, uma regra para identificar cada registro, uma verificação de sucesso e uma forma de recuperação após interrupção.

O Ritoko mantém essas decisões em um procedimento reutilizável:

• Reutilize o trabalho. Salve parâmetros, seletores, chamadas de API e regras de verificação em um fluxo de trabalho JSON legível.
• Processe novos dados. Alimente o procedimento com outro arquivo CSV ou Excel em vez de explicar os mesmos passos para cada linha.
• Recupere com evidências. Veja quais itens foram concluídos, falharam ou têm resultado incerto. Itens confirmados são ignorados em execuções posteriores; escritas incertas ficam retidas para revisão.

Com uma consulta de destino configurada, o Ritoko também pode verificar antes de criar um registro (ensure) e resolver um resultado incerto lendo-o de volta (reconcile). Esses recursos da versão 0.2.0 exigem um GET HTTP direto ou uma ferramenta MCP confiável e explicitamente somente leitura, com regras separadas que comprovam presença e ausência. Uma consulta com falha bloqueia a linha. Configuração e limites.

Por exemplo: ensine seu agente a criar um cliente, salve customer-import, e depois peça para processar a planilha da próxima semana e relatar cada resultado.

O que você pode automatizar?

O Ritoko atende a tarefas repetidas com regras explícitas e resultados verificáveis. Uma nova tarefa ainda exige que um agente ou autor de fluxo de trabalho entenda o site e defina o procedimento.

Início rápido

Experimente dez clientes fictícios localmente

Com Node.js 24+, em um diretório vazio:

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

A demonstração inicia um serviço HTTP de loopback, cria dez clientes CSV fictícios, verifica cada registro lendo-o de volta, e então executa novamente e confirma que todas as dez linhas são ignoradas sem escritas extras. Não precisa de conta, chave de API ou Chrome. O diário fica isolado em um diretório temporário impresso pelo comando. Isso testa uma simulação local; interrupção de navegador e reconciliação de destino são testes separados. Guia em inglês/francês e resultados esperados.

O npm 0.2.0 publicado inclui esta demonstração e os recursos ensure, reconcile e doctor.

1. Instale no seu agente

Requer Node.js 24 ou mais recente. Fluxos de trabalho de navegador usando o executor direto também precisam do Google Chrome. Fluxos de trabalho HTTP/MCP independentes podem ser executados sem navegador.

ensure, reconcile, doctor e a demonstração de primeira tentativa exigem 0.2.0 ou mais recente. Verifique os lançamentos versionados e os portões de lançamento antes de atualizar uma instalação fixada.

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

Reinicie o cliente após a instalação. O plugin Git inclui a habilidade do agente e um servidor MCP local; seu inicializador instala dependências de runtime fixadas na primeira inicialização, com scripts de ciclo de vida do npm desativados.

Para lotes longos do Codex, configure o tempo limite de chamada de ferramenta antes de executar.

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

2. Escolha o navegador ou a integração

Diga ao agente qual navegador você quer que ele use. O executor direto conecta-se ao Chrome pessoal depois que você habilita a depuração remota em chrome://inspect/#remote-debugging e permite a conexão. Escolha RITOKO_BROWSER=clean explicitamente para um perfil separado.

Um navegador de agente compatível pode executar fluxos de trabalho do host quando permite a execução de scripts de página. O evaluate atual de computer-use do Codex é somente leitura, então ele não pode executar a reprodução de navegador do host. Lotes somente de API do host e de ferramentas MCP conectadas permanecem disponíveis. Veja seleção de navegador e limites de confiança.

3. Ensine uma tarefa e reutilize-a

Pergunte ao seu agente:

Registre uma importação de clientes com o Ritoko neste back office. Use o navegador que selecionei. Salve como customer-import com um parâmetro de planilha input. Use Email como chave de negócio e verifique o email do cliente criado.

Se a demonstração criou um registro real, o agente deve adotar essa linha já enviada com run_adopt e evidências antes de reproduzir o lote.

Depois:

Execute customer-import no mesmo back office com input definido para o caminho absoluto de customers.csv. Mostre os itens confirmados, com falha e em revisão, além de quaisquer arquivos salvos.

Mais tarde:

Retome minha última execução do Ritoko.

Mostre o relatório da minha última execução e explique quais itens ainda precisam de revisão.

Como 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. Defina. O agente grava ações do navegador ou escreve etapas suportadas de API/MCP. O gravador prefere rótulos únicos, papéis e outros seletores significativos; seletores posicionais frágeis são sinalizados.
2. Salve. O fluxo de trabalho declara seus parâmetros, entrada, chave de negócio, limite de envio (commit) e verificações de resultado (expect).
3. Reproduza. O mecanismo direto executa as etapas salvas. O modo host permite que um agente compatível execute ações de navegador suportadas ou ferramentas conectadas.
4. Diário e recuperação. O SQLite mantém o fluxo de trabalho e as linhas de entrada de cada execução. Um lote retomado usa esse instantâneo, mesmo que a planilha original mude. Uma página alterada pode pausar para reparo; um envio incerto permanece retido para revisão.

O que acontece após uma falha?

Uma execução está completa somente quando seus itens estão confirmados ou ignorados e suas verificações finais passam. Um resultado parcial ou pausa de reparo é visível no relatório e retorna o código de saída da CLI 2.

A qualidade da verificação importa. Um recibo, ID de registro ou email de cliente correspondente pode comprovar o resultado pretendido. Um banner genérico de “Sucesso” geralmente não pode. O diário rastreia esta instalação do Ritoko; ele não pode impedir envios independentes nem garantir que um site remoto seja idempotente.

Como é um fluxo de trabalho?

Este fluxo de trabalho de navegador ilustrativo cria um cliente por linha de planilha. Adapte a URL, os rótulos e o seletor de resultado ao seu aplicativo antes de salvá-lo.

{
  "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 o registro de negócio; o scope deste exemplo separa URLs de destino. Inclua o identificador da conta no escopo se várias contas compartilharem uma URL. O commit marca a ação irreversível, e o seguinte expect verifica essa linha específica. Lotes somente leitura declaram readOnly: true.

Veja exemplos completos de fluxos de trabalho, o esquema de fluxo de trabalho e a referência HTTP/MCP.

Use a CLI sem um agente

A partir de um checkout Git, o inicializador pode importar e executar um fluxo de trabalho existente sem um agente ou chave de API 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

O exemplo do RPA Challenge baixa sua própria entrada Excel. Escolha o navegador direto conforme descrito acima antes de executá-lo. Para executar intencionalmente este mesmo desafio novamente, adicione --repeat; retenções de revisão permanecem bloqueadas.

Para uma execução direta interrompida, use node bin/ritoko.mjs resume <runId>. Fluxos de trabalho, diários, evidências e arquivos de saída ficam em ~/.ritoko por padrão; substitua com RITOKO_HOME.

Use node bin/ritoko.mjs doctor para inspecionar a configuração local antes de solucionar problemas de um lote. Para uma linha em revisão com uma consulta de destino configurada, node bin/ritoko.mjs reconcile <runId> <key> lê o resultado sem enviá-lo novamente. resolve manual requer uma nota e --confirm-checked depois que você inspeciona o destino pessoalmente.

Evidências e escopo atual

As demonstrações gravadas usaram Ritoko 0.1.0 no Windows com Chrome headless. O cronômetro do site RPA exclui instalação e configuração; o tempo de parede da CLI gravado foi de 3,559 s. O RPA Challenge não tem recibo por linha, então seu exemplo depende da pontuação final. Essas demonstrações e testes controlados não estabelecem uma taxa de confiabilidade ou throughput para todos os sites.

Perguntas frequentes

Preciso de uma chave de API LLM separada?

O executor determinístico do Ritoko não exige um. Quando você usa o plugin, seu agente cliente fornece o raciocínio por meio da assinatura existente ou da configuração de API. Gravação, reparo e orquestração de host ainda usam esse cliente, e as ferramentas conectadas podem chamar modelos por conta própria. APIs externas, provedores de OCR ou serviços de geração pagos exigem acesso próprio e podem cobrar separadamente.

O Ritoko lê notas fiscais ou realiza OCR?

A leitura de documentos é opcional. document_image retorna um JPEG/PNG baixado ao agente cliente para que seu modelo leia. O Ritoko não inclui mecanismo de OCR local nem analisador de notas fiscais. Um serviço externo de OCR escolhido usa credenciais configuradas pelo usuário. Cada nova imagem ainda precisa do agente ou desse serviço; a reprodução comum de navegador e API não precisa.

O Ritoko pode usar meu navegador com sessão iniciada?

O executor direto pode se conectar ao Chrome pessoal com sua permissão de depuração remota. Você pode escolher explicitamente um perfil limpo separado. O suporte integrado ao navegador depende das ações permitidas pelo cliente; consulte limites do driver. Conclua o login ou o MFA no navegador selecionado quando necessário.

Posso usar o Ritoko com qualquer cliente MCP?

Um cliente local que possa iniciar um processo stdio pode se conectar ao servidor. Claude Code e Codex CLI são os clientes de plugin testados. Outros clientes precisam de configuração e verificação de capacidade. Um cliente em nuvem isolado não pode acessar seu processo MCP local ou arquivos sem um mecanismo de conexão separado.

O Ritoko garante que não haverá gravações duplicadas?

Não. Ele ignora itens confirmados e bloqueia gravações incertas dentro do diário, inclusive em execuções futuras. O fluxo de trabalho precisa da chave de negócio correta, do escopo de destino e das verificações de resultado. Submissões independentes e o comportamento de sistemas remotos permanecem fora desse diário. Resolver um item de revisão exige evidências sobre o que realmente aconteceu.

Uma gravação de navegador pode se tornar um fluxo de trabalho de API?

A captura opcional de rede fornece metadados de fetch/XHR para ajudar o agente a investigar uma API. Ela não converte gravações em etapas de API executáveis automaticamente. Verifique o contrato da API e a autenticação, teste uma linha autorizada e salve explicitamente a substituição. Consulte dicas de rede.

Documentação e contribuição

• Uso avançado: configuração do cliente, CLI, opções de navegador, lotes de host, recuperação e regras de fluxo de trabalho.
• Habilidade do agente: instruções para gravar, executar, adotar e reparar fluxos de trabalho.
• Referência de integração: formatos de entrada, formatos de etapas HTTP/MCP e limites do driver.
• Guias de problemas e comparações de ferramentas: escolha um fluxo de trabalho e entenda suas compensações.
• Medição de visibilidade em buscas: prompts fixos em inglês/francês e relatórios baseados nas respostas capturadas.
• Portões de lançamento: verificações obrigatórias, roteiro de validação, políticas de publicação e atualização.
• Privacidade do software local: dados de execução armazenados, destinos configurados, credenciais e retenção.
• Relatar um bug ou solicitar um recurso: inclua o cliente, as versões de Node/navegador/SO e uma reprodução com dados removidos. Mantenha credenciais e dados comerciais privados.

Para desenvolvimento, use Node.js 24+ e pnpm:

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

O Ritoko automatiza serviços que você está autorizado a usar. Ele não contorna CAPTCHAs nem proteções antibot. Fluxos de trabalho e comandos de API/MCP são configuração executável e exigem um autor confiável.

Construído por Swih com Claude (Anthropic) e Codex (OpenAI), creditados como contribuidores no histórico do Git. Lançado sob a licença MIT.