hermes-rehearsal

Hermes Rehearsal

Let your agent make the mistake in rehearsal.

A Hermes plugin that rehearses SQLite customer merges, measures exact row changes,
flags conflicting identities, and applies only a human-approved, verified proposal.

Ask Hermes:

Inspect the sample shop. Propose merging duplicate customers while preserving every
order and total revenue. Flag identity conflicts for me to review.

Rehearsal makes a consistent copy of the database. Hermes proposes structured merges;
Python checks the consequences. A person resolves ambiguous identities and approves
an exact proposal digest. Application locks the source, rejects changes since rehearsal,
replays the operations, verifies the expected result and commits in one transaction.

Try the local review app

Python 3.11+; no external Python packages required:

python -m rehearsal serve

Open http://127.0.0.1:8765 and choose Open sample shop. The sample is synthetic.
The page's walkthrough buttons generate deterministic proposals, not AI responses.
The native Hermes integration lets your configured model propose and revise operations.

Try a deletion-only proposal: real checks detect orphaned orders.
Rehearse with order reassignment: order checks pass, but the two Alex Kumars have
different emails and phone numbers.
Record why they are different and keep them separate.
Review the exact changes and apply. Every order and cent of revenue survives.
Alternatively, simulate a new order before applying: the source-version check
refuses the stale plan without changing the original.

Dark Rehearsal review showing failed order checks and an identity conflict

Screenshot: standalone local review app, synthetic data; not a Hermes Desktop capture.

See the demo script for a 90-second recording outline.

Install in Hermes

Target: Hermes >=0.23.0, Python >=3.11. Native host validation is still required before
catalog submission; the adapter is implemented against the documented public API.

From this repository:

hermes plugins validate . --install-deps
hermes plugins doctor . --ci

Once published, install the repository using hermes plugins install OWNER/hermes-rehearsal
and enable hermes-rehearsal. Enable the Desktop half under Capabilities → Plugins.
Open Rehearsal in the sidebar. The Python and Desktop halves have separate enable
switches. Both must be enabled for the native page to work.

The native page uses SDK routes and ctx.rest only. Its backend lives under
/api/plugins/hermes-rehearsal/, authenticated by Hermes. It does not start a server.

Agent tools

| Tool | Purpose |
|---|---|
| rehearsal_demo | Create a fresh synthetic database, without replacing an existing one |
| rehearsal_databases | List databases connected by the human |
| rehearsal_inspect | Inspect source data and candidate identity conflicts |
| rehearsal_propose | Execute a structured proposal on an isolated copy |
| rehearsal_report | Read evidence, status and application receipt |

There are no model tools for identity confirmation, approval, source registration or
application. Unexpected tool fields such as approved are refused.

Human commands

/rehearsal list
/rehearsal add C:\data\shop.sqlite
/rehearsal review PLAN_ID
/rehearsal resolve PLAN_ID 3:4
/rehearsal apply PLAN_ID

Sensitive commands use Hermes's choice picker. Cancellation or an unavailable picker
causes no write. This release limits administrative slash commands to local CLI/TUI/
Desktop surfaces; messaging-platform commands are refused. The standalone CLI's
apply also requires an interactive confirmation.

Supported data

The first release deliberately supports one customer/order workflow:

CREATE TABLE customers (
  id INTEGER PRIMARY KEY,
  name TEXT NOT NULL,
  email TEXT NOT NULL,
  phone TEXT NOT NULL
);
CREATE TABLE orders (
  id INTEGER PRIMARY KEY,
  customer_id INTEGER NOT NULL REFERENCES customers(id),
  total_cents INTEGER NOT NULL CHECK(total_cents >= 0)
);

Additional ordinary tables and columns are included in the source fingerprint. Extra
customer fields that differ trigger human review. The kept customer row retains its
original values; this release does not combine contact fields or loyalty balances.
A merge redirects orders then removes the other customer record. Triggers, views,
virtual tables and generated customer/order columns are refused. No arbitrary SQL.

Limits: 50 MiB source plus WAL, 50,000 total rows, 100 disjoint merges per proposal,
500 retained plans. UI previews show at most 500 changes and 200 customers. Plan
fingerprints cover the full supported database, not only the preview.

Guarantees and limits

Rehearsal never writes the source; SQLite's backup API captures committed WAL data.
Order IDs and non-ownership fields survive; total revenue stays unchanged; declared
foreign keys and customer references are checked.
Human decisions produce a new immutable plan, preserving the original proposal.
Approval names the exact plan digest. Source fingerprint verification and writes
occur inside one BEGIN IMMEDIATE transaction.
Post-write checks must match the rehearsal fingerprint before commit.
Repeat or concurrent applications cannot reuse the same ready plan.
Matching names, emails or phones do not prove identity. The deterministic rules
flag defined conflicts; reviewers still inspect proposed merges.
This is a workflow boundary, not an OS sandbox. A person or another tool with file
access can modify the database or ledger. It does not intercept arbitrary shell SQL.
The source commit and plugin receipt are in separate databases. If the process dies
between them, a plan can remain applying (or uncertain on a caught receipt failure).
Do not retry it automatically. Inspect the original against its result fingerprint;
no recovery tool is provided in this first release.
There is no automatic undo. Take a normal application backup before real-data use.

Disclosure

The plugin reads explicitly connected local application databases, including their
SQLite WAL files. It writes the source only after the review action/choice picker
approves the exact plan. It stores paths, customer details, diffs, identity decisions,
plan digests and receipts in profile-scoped plugin_data_dir("hermes-rehearsal").
Synthetic fixture databases live there too. State survives plugin updates/removal.
Tool results become part of the Hermes conversation and may be sent to the user's
configured model provider. The plugin itself makes no external network calls, reads
no credentials, sends no telemetry and runs no shell commands. The optional standalone
review server listens only on 127.0.0.1 when explicitly started and runs until stopped.
It has Host/Origin checks and a session CSRF token; it is intended for a single trusted
local user, not public hosting. Native routes rely on Hermes authentication.

Development and checks

python -m unittest discover -s tests -v
node --check desktop/plugin.js
node --check rehearsal/web/app.js

Tests cover unsafe proposals, identity ambiguity, WAL drift, transactional rollback,
concurrent apply, tampered plans, persistence, HTTP protections and a mocked Hermes
registration/choice-picker contract. Mocked adapter tests do not establish compatibility
with an installed Hermes host. Browser smoke test: start the local server, install
Playwright in your development environment, then node scripts/browser-smoke.cjs.

See validation status, submission instructions
and design scope.

MIT licensed.
This UI takes visual inspiration from Aceternity UI. Its
layout, gradients, grid, lights and animations are original CSS; it does not bundle
Aceternity components or depend on the site. The standalone app bundles Inter Variable
from Google Fonts, under the
SIL Open Font License in rehearsal/web/assets/Inter-OFL.txt.

README from the reviewed commit 0abffaa; it updates when the author re-pins.

About