Ritoko

Ritoko — resumable browser automation for AI agents

Solve a task once. Save the procedure. Run it again with new data.

Ritoko is an open-source browser automation and robotic process automation (RPA) tool for AI agents. Turn a solved task into a reusable browser, HTTP API or MCP workflow, run CSV or Excel batches, verify results and resume interrupted work with a local SQLite journal.

Use it as a Claude Code or Codex plugin, a local Model Context Protocol (MCP) server, or a standalone CLI. The direct replay engine runs saved workflows without calling an LLM; a connected MCP tool may itself use AI.

Try locally · Quick start · Use cases · How it works · Workflow example · FAQ · Advanced guide

[Watch the 34-second demo](https://github.com/Swih/ritoko/raw/refs/heads/main/site/assets/media/demo.mp4) — real-time execution against a local test application. Kill the process after the fifth submission, resume, then rerun the same CSV: 10 submissions received, 10 unique, one row still awaiting confirmation. Recorded results and environment.

Why use Ritoko?

An agent can figure out how to enter a customer, download a report or call a business tool. A recurring batch also needs an input format, a rule for identifying each record, a success check and a way to recover after interruption.

Ritoko keeps those decisions in a reusable procedure:

• Reuse the work. Save parameters, selectors, API calls and verification rules in a readable JSON workflow.
• Process new data. Feed the procedure another CSV or Excel file instead of explaining the same steps for every row.
• Recover with evidence. See which items finished, failed or have an uncertain outcome. Confirmed items are skipped on later runs; uncertain writes are held for review.

With a configured destination lookup, Ritoko can also check before creating a record (ensure) and settle an uncertain result by reading it back (reconcile). These 0.2.0 features require a direct HTTP GET or a trusted, explicitly read-only MCP tool, with separate rules proving presence and absence. A failed lookup blocks the row. Configuration and limits.

For example: teach your agent to create one customer, save customer-import, then ask it to process next week's spreadsheet and report each result.

What can you automate?

Ritoko fits repeated tasks with explicit rules and verifiable outcomes. A new task still needs an agent or a workflow author to understand the site and define the procedure.

Quick start

Try ten fake customers locally

With Node.js 24+, in an empty directory:

npm install ritoko@0.2.0

node node_modules/ritoko/examples/first-run/demo.mjs

The demo starts a loopback HTTP service, creates ten fake CSV customers, verifies each record by reading it back, then reruns and checks that all ten rows are skipped with no extra writes. It needs no account, API key or Chrome. The journal is isolated in a temporary directory printed by the command. This tests a local simulation; browser interruption and destination reconciliation are separate tests. English/French guide and expected results.

The published npm 0.2.0 includes this demo and the ensure, reconcile and doctor features.

1. Install in your agent

Requires Node.js 24 or newer. Browser workflows using the direct runner also need Google Chrome. Standalone HTTP/MCP workflows can run without a browser.

ensure, reconcile, doctor and the first-try demo require 0.2.0 or newer. Check the versioned releases and release gates before upgrading a pinned installation.

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

Restart the client after installation. The Git plugin includes the agent skill and a local MCP server; its launcher installs pinned runtime dependencies on first start, with npm lifecycle scripts disabled.

For long Codex batches, configure the tool-call timeout before running.

Other local MCP clients

Add this stdio server configuration to a client that supports local MCP processes:

{

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

This uses the latest published npm release. Git marketplace installs use their Git revision, which may be newer. For repeatable production runs, pin a published version and test upgrades on a small batch.

Also load the Ritoko agent skill if your client supports skills. Claude Code and Codex CLI are the tested plugin clients; other clients need their own compatibility checks. See client setup.

2. Choose the browser or integration

Tell the agent which browser you want it to use. The direct runner connects to personal Chrome after you enable remote debugging at chrome://inspect/#remote-debugging and allow the connection. Choose RITOKO_BROWSER=clean explicitly for a separate profile.

A compatible agent browser can execute host workflows when it permits page-script execution. Codex's current computer-use `evaluate` is read-only, so it cannot execute host browser replay. Host API-only and connected MCP-tool batches remain available. See browser selection and trust boundaries.

3. Teach one task, then reuse it

Ask your agent:

Record a customer import with Ritoko on this back office. Use the browser I selected. Save it as customer-import with an input spreadsheet parameter. Use Email as the business key and verify the created customer's email.

If the demonstration created a real record, the agent should adopt that already submitted row with run_adopt and evidence before replaying the batch.

Then:

Run customer-import on the same back office with input set to the absolute path of customers.csv. Show me the confirmed, failed and review items, plus any saved files.

Later:

Resume my last Ritoko run.

Show the report for my last run and explain which items still need review.

How it works

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. The agent records browser actions or writes supported API/MCP steps. The recorder prefers unique labels, roles and other meaningful selectors; fragile positional selectors are flagged.
2. Save. The workflow declares its parameters, input, business key, submission boundary (commit) and result checks (expect).
3. Replay. The direct engine executes the saved steps. Host mode lets a compatible agent execute supported browser actions or connected tools.
4. Journal and recover. SQLite keeps each run's workflow and input rows. A resumed batch uses that snapshot, even if the original spreadsheet changes. A changed page can pause for repair; an uncertain submission stays held for review.

What happens after a failure?

A run is complete only when its items are confirmed or skipped and its final checks pass. A partial result or repair pause is visible in the report and returns CLI exit code 2.

Verification quality matters. A receipt, record ID or matching customer email can prove the intended result. A generic “Success” banner usually cannot. The journal tracks this Ritoko installation; it cannot prevent independent submissions or guarantee that a remote site is idempotent.

What does a workflow look like?

This illustrative browser workflow creates one customer per spreadsheet row. Adapt the URL, labels and result selector to your application before saving it.

{

"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 identifies the business record; this example's scope separates destination URLs. Include the account identifier in the scope if several accounts share a URL. The commit marks the irreversible action, and the following expect checks that specific row. Read-only batches declare readOnly: true.

See complete example workflows, the workflow schema and the HTTP/MCP reference.

Use the CLI without an agent

From a Git checkout, the launcher can import and run an existing workflow without an agent or an LLM API key:

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 `