Skip to content
rematch

Architecture

rematch is an omp plugin: a TypeScript extension that omp loads, and a Rust binary the extension calls with a JSON envelope. The two-language split keeps one rule: the schema lives in Rust, and the extension forwards raw events.

Architecture. omp (stock or a fork) emits events to the extension, which writes traces and has the binary sync the shared skills directory before discovery. The Rust binary owns rematch-core, reflect and count, create and improve, batch and scope, and calls omp -p non-interactively for the editor, the classifier and batch rollouts. State lives under ~/.rematch; kept entries are copied into ~/.omp/agent/skills.Architecture. omp (stock or a fork) emits events to the extension, which writes traces and has the binary sync the shared skills directory before discovery. The Rust binary owns rematch-core, reflect and count, create and improve, batch and scope, and calls omp -p non-interactively for the editor, the classifier and batch rollouts. State lives under ~/.rematch; kept entries are copied into ~/.omp/agent/skills.

Units

Section titled “Units”
Unit Holds Rule
extension/ index.ts: trace writer, pre-labels, the skill-path override, the hook runtime (block and stuck on tool_call, truncate and retrieve on context), the rematch tool and /rematch command, the digest; agents/ → ~/.rematch/agents/ forwards raw events; no model calls; every handler fails open except block/stuck hooks
adapters/ claude-code/: a plugin (hooks → scripts/hook.sh, eight /rematch:rematch-* commands); codex/: the $rematch-status skill and setup notes forward hook payloads unchanged to the binary; never fail a hook except by an intentional block; no model call inside the session
crates/rematch-core trace model and parsers, redirect heuristics, predicates, lint, library and counters, SQLite ledger with content-addressed blobs, mechanical split, simhash dedup, EXPERIENCE.md, rate limits, outcome records pure functions over paths; no process spawning, no network
crates/rematch the CLI: bounded processes, omp argv builders with per-event provider/model verification, detached jobs, reflect/count, create/improve, import, digest, skills sync, doctor, uninstall, retrieve, built-ins, batch/, scope/ one JSON envelope per invocation; never holds credentials
crates/rematch-lake (cargo feature lake, default on) per-table Arrow schemas, journal and trace writers, export/import/rebuild/doctor, index/query over an external Bellwether binary read only by historical commands; --no-default-features drops it and arrow with it
improver/ editor.md and composer.md (derived from Harness² Appendix H Prompts 1–3), reflector.md, classifier.md, lint.toml, omp-no-tools.yml copied to ~/.rematch/improver/; refreshed only when you have not edited them; never amended by the system (D25)
~/.rematch/ traces, pending, ledger, staging, shared skills, agents, drafts, archive, predecessors, jobs, runs, tasks, branches, export, profile, off one root per environment (REMATCH_ROOT); home and work are separate libraries
~/.rematch/lake/ the journal as Parquet, one Bellwether root per table, one events file per closed session; lake-index/ per machine history as a backend; never on the in-session path

Every path: file locations.

The omp extension

Section titled “The omp extension”

Plain TypeScript; omp loads index.ts with no build step (package.json#omp.extensions).

Part What it does
Factory resolves the binary ($REMATCH_BIN → ../target/release/rematch → ../target/debug/rematch → PATH); runs match and skills sync in parallel (5 s each); adds the shared skills dir to skills.customDirectories; imports the hook modules match returns. A failure is logged and the session continues without that part.
Trace main sessions only append to <root>/traces/<session_id>.jsonl; a flagged session gets <root>/pending/<session_id>.json at shutdown; session_switch/session_branch rotate the trace
Session start spawns rematch reflect --pending detached, then shows the digest (≤ 5 lines, then +N more) and one confirm per approval; alt+e shows the digest on demand
Hooks modules are data ({id, mode, tool, field, regex, message, pass_condition, params}); block and stuck fail closed, truncate and retrieve fail open. Approving, activate, disable and rollback swap the live hook sets at once.
Entry points the tool rematch {operation, arguments[]} and /rematch <sub> [args]; approving entries and uninstalling are reserved to you
Kill switch REMATCH=0 (only the tool and /rematch register) or <root>/off (handlers stay registered but inert, so /rematch on resumes tracing at once; skills apply from the next omp start)

Deviations from the spec

Section titled “Deviations from the spec”

The verified omp facts force four deviations from the spec: no resources_discover callsite in omp, auth living in the agent dir, no registry publish, and no embeddings without credentials. Details: design contract §0 and §11.

Further reading

Section titled “Further reading”
  • The product spec, docs/SPEC.md, written under the working name omp-evolve. Where SPEC and DESIGN disagree, DESIGN wins.
  • The extension: extension/README.md.