FAQ
Ritoko FAQ
Short answer
Ritoko saves verifiable browser, HTTP and MCP procedures and replays them with a local journal. These answers explain setup, model usage, spreadsheet inputs and the checks needed to recover uncertain writes.
Updated
Fit and setup
What is Ritoko?
Ritoko saves a task an agent solved as a reusable JSON workflow, then runs it with new parameters or CSV/XLSX rows. Supported steps include browser actions, HTTP requests and MCP tools. Its local journal keeps each item’s outcome. Start with the quick start.
When should I use a saved workflow instead of an agent?
Use a workflow when the task recurs, its inputs are structured and its result can be checked. Use an agent when the task needs exploration or judgment on each run. The agent can discover a procedure and Ritoko can replay the repeated part.
What do I need to run Ritoko?
The local runtime requires Node.js 24 or newer. Direct browser workflows also need Google Chrome; standalone HTTP/MCP workflows can run without it. Ritoko is available as a CLI, local stdio MCP server and Claude Code or Codex plugin.
Can any MCP client connect to Ritoko?
A local client that can launch a stdio process can connect, subject to its own capabilities. Claude Code and Codex CLI are the tested plugin clients. An isolated cloud client cannot reach your local process or files without a separate connection mechanism.
Can Ritoko use my logged-in browser?
The direct runner can attach to personal Chrome with your remote-debugging permission, or use an explicitly selected clean profile. Complete login or MFA in that browser. Host browser replay needs permission to execute page scripts; current Codex computer-use evaluation is read-only and cannot execute it. See driver choices.
Model usage and services
Does Ritoko replay without calling an LLM?
Its direct replay engine makes no LLM calls. Recording, repair and host orchestration can use your client agent’s model. An external MCP tool, OCR provider or generation endpoint may also invoke models and charge separately. See recurring task costs.
Do I need a separate LLM API key?
The direct runner does not need one. Your client agent supplies reasoning through its existing subscription or API configuration when recording, repairing or orchestrating host runs. External services require their own configured access.
Does Ritoko include OCR or an invoice parser?
No. Optional document_image returns a downloaded JPEG/PNG for your client model to read. An external OCR service is another choice. Each new document still needs interpretation and verification before its extracted values are submitted.
Can I schedule recurring runs inside Ritoko?
Ritoko currently has no built-in scheduler. A separate scheduler can invoke an existing CLI workflow. Arrange login, credentials, timeouts and review follow-up before running unattended, and inspect each run’s report.
Inputs and results
Which spreadsheet formats does Ritoko accept?
It reads .xlsx with a selectable sheet, and comma- or semicolon-separated CSV in UTF-8 or Windows-1252. Required values and duplicate or empty business keys are checked before processing. See input preparation.
Are hidden Excel rows and formatted identifiers imported?
Hidden and filtered-out XLSX rows are read too. Excel number formatting is not applied, so keep identifiers with leading zeros as Text. Formulas use their saved results; referenced formula errors or missing saved results are treated as empty.
Does editing the input file change a resumed run?
No. A run uses the workflow and rows frozen in its journal. Start a new batch deliberately for new or corrected data, after inspecting previous outcomes.
What does the run report contain?
The JSON report includes the run status, counts and per-item outcomes, causes, messages and available evidence or files. It does not currently generate an HTML or CSV audit report. A partial result still needs attention; it is not a completed batch.
Writes and recovery
Does Ritoko guarantee no duplicate writes?
No. It normally skips confirmed items and holds uncertain writes within this installation’s journal. Correct business keys, destination scopes, commit boundaries and row-specific checks are essential. Independent submissions remain outside that journal. See duplicate import prevention.
What does review mean after a crash or timeout?
The write may have succeeded without a usable confirmation. Check that exact record at the destination before resolving it. An inconclusive result should remain in review, including across later runs. See uncertain-write recovery.
How do I resolve a review item?
After someone checks the destination, resolve done if the effect exists or failed if it did not occur. Failed resolution permits a later submission. Both require an evidence note and explicit check confirmation; manual resolutions are recorded as unverified decisions. An agent must obtain the user’s confirmation of the destination check.
How do I resume an interrupted run?
Use run_resume or CLI ritoko resume for a direct run, and host_next for a host run. Confirmed rows stay confirmed; eligible failures can retry; uncertain writes remain held. Resolve an original uncertain run before a later duplicate-held run.
What if my demonstration already created the first record?
After saving the workflow, use run_adopt with that exact full row and an evidence note. It runs confirmation steps and journals the already submitted record so replay can skip it. Do not replay that row while its outcome remains unresolved.
Can Ritoko check the destination before writing or settle review automatically?
The 0.2.0 Git release candidate adds optional ensure lookup before a write and run_reconcile lookup to settle an uncertain result; npm 0.1.1 does not include them. They require direct HTTP GET or a trusted MCP read tool advertising readOnlyHint: true, explicit scope and predicates proving presence or absence. Inconclusive reconciliation leaves the item unchanged; it never resubmits. Browser checks, host runs and agent-managed tools are unsupported, and the lookup must exist in the frozen run. See configuration and limits.
What happens when a recorded selector changes?
A supported direct run can pause for step_repair. Check that a new target identifies the intended control; repairing the commit target requires explicit confirmation. Failures after submission can instead become review. Host mode currently has no selector repair. See selector recording and repair.
Can I intentionally repeat completed rows?
Yes, an explicit repeat: true or CLI --repeat reruns completed rows. Review holds remain blocked. Use repeat only when the repeated business effect is intended.
Integrations and local data
Can a browser recording automatically become an API workflow?
No. Optional network capture gives fetch/XHR metadata for investigation. Verify the authorized API contract and authentication, test a row and explicitly save supported HTTP steps. An uncertain API write must not automatically fall back to another browser submission.
Can a workflow call an existing MCP tool?
Yes, supported configured servers can supply mcp steps, and host {ref: "agent"} references reuse an existing agent connection. Verify schemas, side effects, protocol compatibility and service charges. Tool calls are not automatically retried. See integration choices.
Where are workflows, the journal and output files stored?
They live under ~/.ritoko by default; RITOKO_HOME changes that location. The journal contains business rows and ordinary saved values. Saved files keep their original bytes and can contain sensitive data. Treat the installation’s files as business records.
How should I store credentials?
Declare secret parameters backed by environment variables. Do not put credentials in workflow JSON or spreadsheets. Runtime credentials are excluded from the journal, while saved response files preserve their bytes and need their own care. Read the integration reference.