OPENMOD / ENGINEERING NOTES / 001

A small runtime.
An explicit contract.

OpenMod lets you reason about a mod before installing it. It evaluates the JavaScript you see, dispatches synthetic events through the registered hooks, and records what the hook passes to next() and returns. The source is real. The session is simulated.

What actually runs

Each replay creates a fresh module instance. We dispatch session.start, then the selected fixture’s tool.call events in order. The simulated tool returns a fixture result and advances a virtual clock. After each call we dispatch two UI events. Finally, if present, we call the selected mod’s command with json.

Surface	Implemented subset
Events	session.start, tool.call, command.run, ui.render
Matchers	Exact field equality, including component and command
Clock	$.clock.now(), fixture-based milliseconds
UI	$.ui.invalidate(); $.ui.resolve() with Box and Text; AbovePrompt and Spinner
Commands	$.command.register(); selected mod command invoked with “json”
Middleware	Ordered hooks, bounded repeated next() calls (up to 16 per handler), flat tool arguments, results, denials and errors

Unknown API calls and event registrations fail explicitly. Imports, TypeScript, real model calls, terminal layout, full cancellation, concurrency, persistent state and Claude Code’s permission system are outside this replay’s scope. Rendering flattens Box/Text into readable text; it does not reproduce the native terminal renderer. Fixture results remain fixed even if your hook rewrites a command.

Isolation, with boundaries

Edited code runs in a disposable Web Worker inside an iframe with sandbox="allow-scripts", without same-origin privileges. The separate frame document sets a restrictive Content Security Policy inherited by its blob worker. Network connections are blocked. The host accepts messages only from that frame and the current random channel token, removes it after two seconds, caps accepted output, and renders output as text.

This is a browser execution boundary, not a security certification. The deadline is a wall-clock timeout, not a memory quota, and the browser remains part of the trusted platform. Downloaded mods do not carry this browser sandbox: in Claude Code they run with your user permissions. Review the source before installing.

A capability lens, not a “safe” badge

We parse the source with Acorn and identify literal on(...) registrations and direct $.namespace.method(...) calls. Computed property access, aliases, imported files and dynamic behavior can escape this view. The runtime report adds the API calls observed on the selected fixtures; another session can take different branches. Neither report proves safety.

Flight Recorder’s data contract

The bundled recorder retains at most 300 records in module memory. A record contains a sequence number, tool name, start time, elapsed milliseconds and status. It deliberately omits tool arguments, paths, result text and exception messages. /flight-recorder json returns this metadata; /flight-recorder clear clears retained rows. Reloading the mod or restarting the session also clears it.

Elapsed time includes permission waits and downstream mods. Earlier mods may answer an event before this recorder sees it; checks before mods are not observable here. A repeated tool call is not necessarily a retry. The browser’s inspection report contains synthetic input and output for teaching; it is separate from the native recorder’s metadata export. Modified source can change these behaviors.

Reproduce the result

git clone https://github.com/jerrywang33/openmod.git
cd openmod
npm ci
npm test
npm run check

# Claude Code 2.1.287+
claude plugin validate ./plugins/flight-recorder
claude plugin test ./plugins/flight-recorder
claude --plugin-dir ./plugins/flight-recorder

All three bundled plugins passed the official Claude Code 2.1.287 validator. Flight Recorder passed four native tests covering metadata privacy, unchanged results, failure status and clearing records. The workbench also passes 32 Node checks. Native interactive terminal rendering and browser visual QA were not manually exercised. Claude Code’s generated plugin types remain the authority for your installed version.

Sources and attribution

Flight Recorder and Latency Lens are OpenMod examples. Tool Counter is a small learning example based on the counting pattern in Anthropic’s tutorial. This independent project is not affiliated with or endorsed by Anthropic.

A small runtime.An explicit contract.