Mythos Router checks every file an agent claims to have written, and rolls back the batch when it did not happen

A whole batch rolls back when a claimed write is missing from disk

The core mechanism is Strict Write Discipline, a verification layer built on SHA-256 snapshots taken before and after the agent runs. Every file operation the model claims to perform is checked against the actual filesystem, and when a claim does not match reality the batch is rolled back rather than left half applied. The stated principle behind it is that the trust boundary is the filesystem and not the model, which is what makes the layer usable by more than one vendor.

Each successful run leaves a per run trust receipt recording the files touched, their hashes, the provider or external agent id, the budget, the git state, and the verification result. Receipts are hash chained and serialized under a repository lock, and the receipt plus HEAD writes are atomic so that local gaps, reordering, forks, partial edits, and unsynchronized writers are all detected. The scope of that guarantee is stated precisely too: the chain is tamper evident on your machine, not an external authenticity proof, so it tells you your own copy was edited, not that a third party vouched for the run.

Verification rides on FILE_ACTION text blocks, not only on native tool calls

There are two transports for the same verification. By default the agent emits text FILE_ACTION blocks, which the engine parses and then checks. With `--tools`, Mythos uses native provider tool calling for Anthropic and OpenAI instead, and the verification layer behaves the same way. If the native path does not hold up, it falls back to text automatically, so a provider that drops tool support degrades into a slower mode rather than an unverified one.

When the model gets something wrong about the filesystem, it gets a bounded number of chances to fix it. Correction Turns give the model 2 retries to match filesystem reality, and then it yields. That bound is deliberate, since an agent that can retry indefinitely will keep rewriting files to satisfy its own earlier claims.

Two inspection modes sit alongside this. Dry run mode previews every file operation before it executes, and verbose tracing shows what the AI is parsing, thinking, and verifying, which is the difference between debugging a failed verification and guessing at it.

The router raises the model tier only after verification fails

Cost is handled by a verified cost router rather than by picking an expensive model up front. With `--escalate`, a run starts at a cheap `--effort` and climbs one model tier per Correction Turn, and only when SWD verification actually failed, capped by `--escalate-to`. The premise is that you should pay for the expensive model only when the cheap one is provably wrong.

The effort levels map to concrete models. `high` is the default and selects Claude Opus 5 for architecture, deep reasoning, and complex refactors. `medium` selects Claude Sonnet 5 for balanced code generation and everyday tasks. `low` selects Claude Haiku 4.5 for quick answers, memory compression, and verification. The `dream` command always uses `low` for memory compression, and `verify` uses lightweight scanning, so neither spends Opus budget on housekeeping.

Providers are configurable rather than fixed. Routing happens across configured Anthropic, DeepSeek, OpenAI, and Surplus keys with circuit breakers, and Anthropic is no longer required once another provider is configured. Keys come from the environment, and the sample file names all four:

ANTHROPIC_API_KEY=
OPENAI_API_KEY=
DEEPSEEK_API_KEY=
SURPLUS_API_KEY=

A token limiter caps spend and saves gracefully, writing progress to MEMORY.md so a capped run does not lose work.

`receipts undo` previews first and refuses to overwrite newer edits

Undo here is not a git revert, it is a replay of a verified receipt in reverse. `receipts undo <id|latest>` walks a stored run backwards, previews by default, and only writes when you pass `--yes`. The important guard is that the undo is drift gated: if the files on disk have changed since the receipt was written, the replay stops rather than clobbering newer edits. A successful undo produces its own receipt, so the reversal enters the same hash chained history instead of leaving an unaccounted for gap.

Because receipts carry the budget and the provider id as well as the file hashes, the same record answers more than a can I revert question. Reading a receipt tells you which model produced the change, what it cost, what git state the tree was in, and whether verification passed at the time, which is the input you need when you are trying to work out why a batch was rejected.

Project level policy lives in `.mythos/policy.json`, a repo local file that adds enforced SWD guardrails for sensitive project surfaces. It is the place to declare which paths must not be touched by an agent at all, and its schema is published from the package as `policy-schema` alongside the external agent action schema.

Skills are mined from failing receipts and stay read-only until you pass --write

The self improving part of the system is driven by its own failure data. `mythos skills suggest` mines past SWD receipts for file actions that keep failing verification, then proposes SKILL.md rules aimed at preventing those specific failures. It is read-only by default, and `--write` is what persists the suggestions, so you see the proposed rule before it becomes project policy.

Two other paths feed the same mechanism. Verified Skill Packs load project local or user global SKILL.md rules by name with `-s <name>`, and whichever skills were active get recorded in the SWD receipt, which is what makes the suggestion loop possible later. `mythos learn` takes a different path and generates a repo local SKILL.md from detected project structure, scripts, docs, CI, and risk surfaces, so onboarding a new repository is one command rather than a manual write up.

The memory layer follows the same authority first idea. MEMORY.md is treated as the sole authority with authority based logging, and the search index over it is disposable: a SQLite FTS5 index can be rebuilt from the markdown, so losing the index costs time rather than history. Both that index and the SQLite backed reasoning cache in the SDK need Node 22 or newer, and development runs straight through tsx with no compile step.

`mythos doctor --repair` only touches inactive transaction journals

Health checking is split so that the safe part stays safe. `mythos doctor` runs read-only checks across policies, receipts, sessions, telemetry, filesystem safety, and interrupted SWD transactions. Its `--repair` flag is narrow on purpose: it only recovers inactive transaction journals, so a repair run cannot sweep away evidence from a transaction that is still open or was abandoned mid flight.

`mythos init` follows the same shape. It is a single command onboarding path with environment validation and scaffolding, and its `--check` variant is read-only, which makes it usable in a pre-commit hook or a CI job where you want to know the workspace is sane without changing it.

There is a matching read-only entry point for pull requests. `verify --ci` runs command-surface, sensitive-file, and receipt risk checks without needing an API key, and the separate `verify` command has an integrity gate that ensures referenced memory files still exist, since a memory file that has been moved out from under a receipt is a stale fact rather than a small error.

Isolated runs test a batch in a throwaway copy before the real tree changes

The strongest guarantee in the tool is the one that avoids writing at all. `swd apply --check <cmd>` and the companion `--run-checks` flag test a batch in a throwaway copy of the tree and apply it to the real tree only if the checks pass. In other words the failing case never reaches your working copy, which is a different and stronger claim than rollback after the fact.

The apply path also carries the other safety surfaces. A batch can be written to a namespaced `mythos/` git branch with session branching, so agent work can be isolated from your current branch and inspected before it merges. Session resume with `--resume` picks up exactly where you left off after a crash or exit, which matters when a run is long enough to hit a token cap or a provider failure mid batch.

Budget analytics are persistent across sessions and projects through `stats`, and `runs` lists past runs. The pairing of those two commands with receipts is what lets you ask which model, which prompt shape, and which skill pack produced a given set of hashes instead of reconstructing it from shell history.

An external agent can route writes through stdin/JSON or MCP with no Mythos key

Mythos ships a built in agent, but the verification engine is not tied to it. The same layer accepts file actions from GPT, DeepSeek, a local model, or your own script, and the paths are stdin and JSON, the SDK, or MCP. No Mythos model key is needed on any of them, because the work being verified is the file action, not the inference behind it.

The MCP route exposes SWD, receipt, and skill tools over stdio, and `mythos mcp config` prints the client setup snippets rather than asking you to hand write them. The contract for external agents is published as a JSON schema from the package itself, exported as `schemas/external-agent-actions.schema.json`, alongside the project policy schema, so an agent integration can be written against a file rather than against prose.

The fastest way to see the failure case is the bundled example, `examples/verified-writes`, which is a runnable demo of an agent hallucinating a write and SWD catching it. The examples directory also carries external-agent JSON, GitHub Action, MCP stdio, and project policy setups, and the repository ships an `action.yml` for CI use.

Editorial conclusion

Mythos Router earns a place in a workflow where agents touch real files and a hallucinated edit has to be caught before it reaches a commit, especially since the verification path works for external agents over stdin or MCP with no Mythos key. It is a poor fit if you want a chat client with no filesystem contract, if you are on Node below 22 and need the SQLite cache or the memory index, or if you expect the local receipt chain to prove anything to a third party, because the project itself calls it tamper-evident rather than an authenticity proof. Before adopting it, decide which isolation mode you want for test runs, read the `.mythos/policy.json` schema for the surfaces you must protect, and pin the version, since the CLI ships under two names and its behaviour has changed across 1.x releases.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. thewaltero/mythos-router on GitHub