Quickstart

Journal an agent’s tool calls, then roll them back, in about five minutes.

1. Run the demo

git clone https://github.com/multimindlab/reversi && cd reversi
npm install
npm run example

An agent creates an order, charges a card, sends an email and tries a tool outside its scope. An operator reviews the plan and rolls the run back. The email stays in the report as cannot be undone.

2. Look at the evidence

node packages/cli/dist/main.js verify examples/order-agent/out/ledger.jsonl

Open viewer/index.html in a browser and choose that file. The chain is verified in your browser.

3. Describe your own tools

tools.yaml

- tool: create_order
  effect: reversible
  permission: orders:write
  compensation:
    tool: cancel_order
    argument_map: { order_id: $result.order_id }
- tool: cancel_order
  effect: idempotent
  permission: orders:write
- tool: send_email
  effect: irreversible        # forces human approval
  permission: mail:send

reversi validate tools.yaml

Or start from a project: reversi init my-project writes a config, example manifests, a starter policy and tests, then reversi doctor checks the setup and reversi test runs the contract tests and the policy’s own tests without touching any system. reversi lint flags unsafe or incomplete manifests (a missing owner, no timeout, a mutating tool with no undo).

4. Wrap calls

TypeScript

import { SealedScope, loadRegistry, openLocal } from "@multimindlab/reversi";

const reversi = openLocal("./reversi-data", loadRegistry("./tools.yaml"));
const run = reversi.startRun({
  actor: "support-agent",
  scope: SealedScope.seal(["orders:write"]),
});

const r = await run.call({
  tool: "create_order",
  args: { sku: "BOOK-1" },
  reason: "customer asked to order BOOK-1",
  execute: (args) => shop.createOrder(args),
});
if (r.status === "blocked") console.log(r.reasons);

5. Plan and roll back (operator)

reversi plan  <run_id> -m tools.yaml -d ./reversi-data
reversi rollback <run_id> -m tools.yaml -d ./reversi-data --compensator-cmd "./undo.sh"

undo.sh receives the compensation call as JSON on stdin; exit code 0 means it was undone.

6. Or put the gateway in front of an MCP server

No code changes in the agent: point its MCP client at reversi-gateway. You do not need manifests to begin. With none, the gateway starts in observe mode: everything runs and is journaled, nothing is blocked, and a banner on stderr lists which upstream tools are unclassified.

reversi gateway --upstream-cmd npx --upstream-arg -y --upstream-arg my-mcp-server

Draft manifests from what the server actually offers, review them, approve them, then enforce:

reversi suggest-manifest --upstream-cmd npx --upstream-arg -y --upstream-arg my-mcp-server -o drafts
reversi manifests publish drafts --registry ./registry --by bob          # drafts are not enforceable yet
reversi manifests approve my.tool --registry ./registry --by alice --four-eyes
reversi gateway --manifests ./registry --upstream-cmd npx --upstream-arg -y --upstream-arg my-mcp-server

Look at what happened in a browser with reversi console (open mode, your machine only). The gateway guide covers modes, schema checks, approvals and rollback; GitOps covers keeping all of this in git.