mythos-router

---

What is this?

mythos-router is a local CLI power tool built around Strict Write Discipline (SWD): a verification layer that checks every file operation an AI agent claims to perform against the actual filesystem using SHA-256 snapshots. If a claim doesn’t match reality, the batch is rolled back so a bad write never half-lands, and successful runs leave a hash-chained, locally tamper-evident receipt.

The key idea is that the trust boundary is the filesystem, not the model. That makes SWD model-agnostic: it ships with a built-in Claude Opus 5 agent (mythos chat / mythos run), but the same engine verifies file actions from any agent — GPT, DeepSeek, a local model, or your own script — with no Mythos model key, over stdin/JSON, the SDK, or MCP. See examples/verified-writes for a runnable “the agent hallucinated a write, SWD caught it” demo.

Zero slop. Zero hallucinated state. Every write verified.

---

Features

Feature	Description
mythos init	Single-command project onboarding with environment validation, read-only --check, and scaffolding
mythos doctor	Read-only workspace health checks for policies, receipts, sessions, telemetry, filesystem safety, and interrupted SWD transactions; --repair only recovers inactive transaction journals
mythos learn	Generate a repo-local SKILL.md from detected project structure, scripts, docs, CI, and risk surfaces
mythos run	One-shot prompt mode with inline, file, stdin input, and optional --provider BYOK selection: same SWD, budget, skills, branch, and optional test-healing pipeline as chat
Multi-Provider BYOK	Auto-routes between configured Anthropic, DeepSeek, OpenAI, and Surplus keys with circuit breakers; Anthropic is no longer required when another provider is configured
Verified Cost-Router	--escalate runs at a cheap --effort and climbs one model tier per Correction Turn only when SWD verification fails — pay for the expensive model only when the cheap one is provably wrong (capped by --escalate-to)
Verified Skill Packs	Load project-local or user-global SKILL.md rules with -s <name>; active skills are recorded in SWD receipts
Self-Improving Skills	mythos skills suggest mines past SWD receipts for file actions that keep failing verification and proposes SKILL.md rules to prevent them; read-only by default, --write to persist
Deterministic Caching	SQLite-backed caching for reasoning (SDK only) (Node 22+)
Adaptive Thinking	Claude Opus 5 with configurable effort levels (high/medium/low)
Strict Write Discipline	Pre/post filesystem snapshots verify every model or external-agent file claim. Works over text FILE_ACTION blocks by default, or native provider tool-calling with --tools (Anthropic/OpenAI) — same verification either way, auto-falls back to text
Isolated Runs	swd apply --check <cmd> / --run-checks test a batch in a throwaway copy and apply it to the real tree only if checks pass — the real tree is never left broken
SWD Receipts	Per-run trust receipts record touched files, hashes, provider/external-agent id, budget, git state, and verification result. Receipts are hash-chained and serialized under a repository lock. Atomic receipt/HEAD writes detect local gaps, reordering, forks, partial edits, and unsynchronized writers; the local chain is tamper-evident, not an external authenticity proof
Receipt Undo	receipts undo <id|latest> replays a verified receipt in reverse — previews by default, --yes to apply, drift-gated so it never overwrites newer edits, and produces its own receipt
Project Policy	.mythos/policy.json adds enforced repo-local SWD guardrails for sensitive project surfaces
Self-Healing Memory	Authority-based logging with a rebuildable SQLite FTS5 search index (Node 22+)
Auto-Healing TDD	Pass --test-cmd for bounded, error-driven autonomous repair loops
Correction Turns	Model gets 2 retries to match filesystem reality, then yields
Integrity Gate	verify command ensures referenced memory files still exist
CI Verification	verify --ci runs read-only PR checks for command-surface, sensitive-file, and receipt risks without an API key
Bring Your Own Agent	mythos swd apply --stdin --json lets any external agent route file actions through SWD without a Mythos model key
MCP Adapter	mythos mcp exposes SWD, receipt, and skill tools over stdio; mythos mcp config prints client setup snippets
Token Limiter	Budget cap with graceful save — progress saved to MEMORY.md, never lose work
Session Resume	Pick up exactly where you left off after a crash or exit (--resume)
Dry-Run Mode	Preview every file operation before it executes — full transparency
Verbose Tracing	See exactly what the AI is parsing, thinking, and verifying
Budget Analytics	Persistent tracking of cost across sessions and projects via stats
Session Branching	Isolate AI actions in a namespaced git branch (mythos/)
Zero Build	Runs directly via tsx — no compile step in dev

---

Core Architectural Pillars

1. Configurable Model Selection

Choose the right model for the job via the --effort flag:

Effort	Model	Best For
high (default)	Claude Opus 5	Architecture, deep reasoning, complex refactors
medium	Claude Sonnet 5	Balanced code generation, everyday tasks
low	Claude Haiku 4.5	Quick answers, memory compression, verification

The dream command automatically uses low effort (Haiku 4.5) for cost-efficient memory compression, and verify uses lightweight scanning — so you only burn Opus/Fable tokens when you need deep reasoning.

2. Authority-Based “Self-Healing” Memory

Most agentic systems stored state in opaque databases or messy JSON files. Mythos Router treats MEMORY.md as the Sole Authority.

Every action is logged in Markdown first. On startup, the system verifies the integrity of the log via SHA-256 manifest hashing and reconstructs a high-performance Derivative SQLite Index (FTS5). If the index drifts or the database is deleted, the system self-heals by rebuilding from the authoritative Markdown source.

As memory approaches capacity, the dream command delegates a compression phase to a low-cost model (Haiku 4.5), ensuring your “Sacred Log” is always lean and relevant.

---

Installation

Node.js Version Requirement: The CLI requires Node.js 22+ (enforced via engines and tested in CI on Node 22 and 24). The advanced SQLite-backed features (Telemetry Dashboard, Deterministic Caching, and High-Performance Memory Index) require Node.js 22.5.0+ specifically; on Node 22.0–22.4 these features safely degrade with a warning without crashing the router.

Quick Start (npm)

# Install globally
npm install -g mythos-router

# Set at least one model key for mythos chat/run
# Anthropic remains the recommended default, but OpenAI/DeepSeek/Surplus can be used standalone.
export ANTHROPIC_API_KEY="sk-ant-..."
# export OPENAI_API_KEY="sk-proj-..."
# export DEEPSEEK_API_KEY="sk-..."
# export SURPLUS_API_KEY="inf_..."   # Surplus marketplace (OpenAI-compatible, discounted)

# Initialize and start the built-in Mythos agent
mythos init
mythos chat

# Or use only the model-free SWD layer with your own external agent
your-agent --emit-file-actions | mythos swd apply --stdin --json

# Or expose Mythos to an MCP-compatible local agent client
mythos mcp

Or try without installing

npx mythos-router chat

Integration Examples

Small, runnable examples are available in examples/:

Example	Purpose
verified-writes	Route any agent’s file claims through SWD (stdin/JSON, SDK, or MCP) — includes a runnable agent-hallucination demo
external-agent-json	Submit structured file actions through mythos swd apply without a Mythos model key
mcp-stdio	Configure an MCP client to launch mythos mcp over local stdio
project-policy	Add enforced repo-local SWD block/confirm rules with .mythos/policy.json
github-action	Add a read-only verify --ci PR gate — one-line reusable action (uses: thewaltero/mythos-router@v1) or copy-a-workflow

From Source

git clone https://github.com/thewaltero/mythos-router.git
cd mythos-router
npm install
npm run chat

---

Usage

mythos init — Project Onboarding

mythos init                  # Initialize mythos-router in the current project
mythos init --check          # Check environment and project setup without writing files
mythos init --force          # Re-scaffold files even if they already exist

init prepares the local repo surface Mythos uses: .mythosignore, MEMORY.md, .mythos/policy.json, and the project-local .mythos/skills/ directory.

mythos learn - Repo Skill Generation

mythos learn                 # Generate .mythos/skills/repo/SKILL.md
mythos learn --dry-run       # Preview the generated skill without writing files
mythos learn --force         # Overwrite an existing repo skill
mythos learn --name backend  # Generate .mythos/skills/backend/SKILL.md

learn turns the current repo into a reviewable project skill. It scans local repo signals such as README.md, package.json, source directories, CI workflows, config files, docs, tests, package scripts, public exports, and security-sensitive paths. It does not run npm scripts, shell commands, tests, builds, or a model. The generated SKILL.md is a deterministic starting point that should be inspected and edited like any other project file.

mythos skills - Verified Skill Packs

mythos skills                # List project-local and user-global skills
mythos skills new repo       # Create .mythos/skills/repo/SKILL.md
mythos skills new audit --global  # Create ~/.mythos-router/skills/audit/SKILL.md
mythos skills show repo      # Inspect metadata and instructions
mythos skills check          # Validate all discovered skills

Skill packs are repo operating manuals for Mythos. They encode project conventions, files to read first, files to avoid, review expectations, and verification rules without adding runtime code. Project-local skills live in .mythos/skills/<name>/SKILL.md and win over global skills with the same name. User-global skills live in ~/.mythos-router/skills/<name>/SKILL.md for personal reuse across repositories.

mythos run --file TASK.md -s repo
mythos chat -s repo -s security-review

When a non-dry-run SWD operation creates a receipt, Mythos records the active skill ids and versions. That makes skill-guided changes auditable: reviewers can see which repo rules were loaded when the verified edit happened. See docs/skills.md for the format and examples.

mythos run — One-Shot Task

mythos run "explain this repo architecture"
mythos run --file TASK.md
cat TASK.md | mythos run --stdin
mythos run --provider openai "explain this repo architecture"
mythos run "update the docs for verify --ci" --dry-run
mythos run "fix the failing smoke test" --test-cmd "npm test"
mythos run "refactor provider scoring" --branch provider-score

run sends one prompt through the same Mythos pipeline as chat, including SWD verification, budget tracking, skills, branch sandboxing, receipts, and optional --test-cmd healing. The prompt can come from the command line, a local file, or piped stdin. It exits after that prompt instead of opening the interactive REPL, and it does not overwrite the resumable chat session used by mythos chat --resume.

mythos chat — Interactive Session

mythos chat                  # Full power (high effort, Opus 5)
mythos chat -s repo          # Load a project-local skill pack
mythos chat --test-cmd "npm test" # Enable autonomous test-driven self-healing
mythos chat --provider openai # Force a configured BYOK provider
mythos chat --tools          # Opt in to native provider tool-calling
mythos chat --effort low     # Budget mode (Haiku 4.5 when using Claude)
mythos chat --effort medium  # Balanced (Sonnet 4.6 when using Claude)
mythos chat --resume         # Resume your previous session exactly where you left off
mythos chat --dry-run        # Preview all file changes before executing
mythos chat --verbose        # See full SWD traces and thinking
mythos chat --branch refactor # Isolate session in a fresh git branch
mythos chat --dry-run --verbose  # Maximum transparency

Financial Safety — Budget Limiter

mythos chat                           # Default: 500K tokens, 25 turns
mythos chat --max-tokens 100000       # Cap at 100K tokens
mythos chat --max-turns 10            # Cap at 10 turns
mythos chat --max-tokens 50000 --max-turns 5  # Tight budget
mythos chat --no-budget               # Expert mode (no limits)

The budget limiter tracks every token, turn, and estimated cost in real-time:

budget: [████████░░░░░░░░░░░░] 78,342/500,000 tokens · [██████░░░░] 12/25 turns · ~$1.2340 · 4m 32s

At 80%, you get a yellow warning. At 100%, the session performs a graceful save — current progress is written to MEMORY.md so you can resume context in your next session. No work lost. Use --no-budget to disable (at your own risk). Note: The limiter checks token usage between API calls, so a single large response may overshoot the configured limit.

Dry-Run Mode — The Trust Builder

mythos chat --dry-run

In dry-run mode, every file operation is previewed before execution:

 DRY-RUN  ── File Action Preview ──
  2 file action(s) detected. Review each:

  1/2 MODIFY src/index.ts
  Description: Change 'axios' to 'fetch'
  Current state: 1,832 bytes, hash: 7a3f2c1e..
   DRY-RUN  Accept MODIFY on src/index.ts? [Y/n] y
  ✔ Accepted: MODIFY src/index.ts

  2/2 CREATE src/utils.ts
  Description: Add helper utilities
  Current state: does not exist
   DRY-RUN  Accept CREATE on src/utils.ts? [Y/n] n
  ⚠ Rejected: CREATE src/utils.ts

In-session commands:

• /exit, /q or quit — End session (shows final budget summary)

mythos swd apply — Bring Your Own Agent

# Pipe raw [FILE_ACTION] blocks from any external agent
your-agent --task "update docs" | mythos swd apply --stdin --json

# Or pass a JSON action envelope
cat actions.json | mythos swd apply --stdin --json --agent python-agent --model local-llama

# Preview without touching disk or writing receipts
cat actions.json | mythos swd apply --stdin --dry-run --json

# Gate the apply behind a trusted check in an isolated temp repo copy
cat actions.json | mythos swd apply --stdin --json --check "npm test"

# Run checks declared in .mythos/policy.json before applying
cat actions.json | mythos swd apply --stdin --json --run-checks

# High-impact files such as package.json require explicit opt-in; sensitive files stay blocked
cat actions.json | mythos swd apply --stdin --allow-risky --json

swd apply is the model-free external-agent interface. It does not call Anthropic, OpenAI, DeepSeek, or any other model provider. Your agent keeps its own model key and only hands Mythos structured file actions. Mythos then applies Strict Write Discipline: path validation, security-policy review, pre/post snapshots, hash verification, rollback on failed verification, and local SWD receipts for successful non-dry-run applies.

When --check or --run-checks is used, Mythos adds an isolated pre-apply gate. It mirrors the current project into a throwaway temp repo copy, applies the approved actions inside that copy, runs the requested checks there, and only then applies the same actions to the real working tree through SWD. If the temp copy cannot be prepared or any check fails, the real working tree is left untouched.

The mirror follows Git’s tracked/untracked view and honors .gitignore plus .mythosignore. Common secret material such as .env, private-key files, credential JSON, and user registry configuration is excluded by default; .env.example remains eligible. Existing ignored action targets are copied only when needed to verify the proposed batch and are still blocked when they match a sensitive-file rule.

This is an isolated workspace gate, not an OS or container sandbox. Check commands are trusted shell commands supplied by the user or explicitly enabled from project policy, and they run with the local user’s permissions. Use commands you already trust, such as npm test, npm run build, npm run lint, or npx tsc --noEmit. --dry-run never executes checks.

Accepted input formats:

[FILE_ACTION: src/example.ts]
OPERATION: CREATE | MODIFY | DELETE | READ
INTENT: MUTATE | NOOP | UNKNOWN
CONTENT_HASH: <optional sha256 of final content>
DESCRIPTION: <one-line summary>
CONTENT:
<full file content for CREATE/MODIFY>
[/FILE_ACTION]

{
  "request": "external agent task label",
  "summary": "CREATE: src/example.ts",
  "agent": { "id": "python-agent", "model": "custom-model" },
  "actions": [
    {
      "path": "src/example.ts",
      "operation": "CREATE",
      "intent": "MUTATE",
      "description": "Create example file",
      "content": "export const ok = true;\n"
    }
  ]
}

Security defaults:

• input is size-limited and schema-validated before execution
• JSON action batches contain 1–500 actions; operation and intent values are uppercase and case-sensitive
• unknown or misspelled envelope, agent, contract, and action fields are rejected instead of ignored
• external JSON paths must be safe project-relative paths
• .env, private keys, wallet files, .git, .npmrc, and secrets paths are blocked
• deletes and command-surface files require --allow-risky
• .mythos/policy.json can add repo-specific blocks, confirmations, operation limits, batch limits, and opt-in checks
• --check and --run-checks run checks in a temp repo copy before the real tree is touched
• check commands are caller-trusted shell commands, not an OS/container security sandbox
• dry-runs do not write files or receipts
• dry-runs do not execute checks
• receipts record the external agent/model as external:<agent-id>

.mythos/policy.json - Project Safety Policy

{
  "version": 1,
  "block": ["contracts/mainnet/**", "infra/prod/**"],
  "confirm": ["src/payments/**", ".github/workflows/**"],
  "limits": {
    "allowDeletes": false,
    "maxActions": 25,
    "maxActionContentBytes": 120000,
    "allowedOperations": ["CREATE", "MODIFY", "READ"]
  },
  "checks": [
    { "name": "build", "command": "npm run build" },
    { "name": "test", "command": "npm test" }
  ]
}

Project policy is an enforced SWD guardrail, not a prompt hint. Its block/confirm/limit rules apply to chat, run, swd apply, and MCP swd_apply. Built-in sensitive path protection still wins, so policy files cannot allow .env, private keys, wallet files, .git, or .npmrc. block patterns fail closed, confirm patterns require human approval or explicit --allow-risky in external-agent flows, and malformed policy files block writes until fixed. Policy validation is strict at every level: unknown top-level, limits, or check fields are rejected with typo suggestions rather than silently ignored.

Published JSON Schemas are available from the package as mythos-router/schema for external-agent actions and mythos-router/policy-schema for .mythos/policy.json. The same limits are enforced by the runtime, and tests keep the checked-in schemas synchronized with their runtime definitions.

Policy checks are different from path rules: declaring them does not execute anything. They run only when mythos swd apply --run-checks is passed, or when an MCP client calls swd_apply with runChecks: true. Checks run in the same isolated temp repo copy as ad-hoc --check commands, and failed checks prevent writes from reaching the real working tree.

mythos mcp — MCP Adapter for SWD

mythos mcp
mythos mcp config
mythos mcp config claude
mythos mcp config cursor
mythos mcp config cursor --json

mcp runs a local stdio Model Context Protocol server. It does not start an HTTP daemon, open a port, call a model provider, or duplicate the SWD engine. MCP clients launch it as a subprocess and call Mythos tools through JSON-RPC over stdin/stdout.

mcp config prints a paste-ready MCP server entry for clients such as Claude and Cursor:

{
  "mcpServers": {
    "mythos-router": {
      "command": "mythos",
      "args": ["mcp"]
    }
  }
}

Run the client from the repository you want Mythos to guard, or use a project-scoped MCP config when your client supports it.

Exposed tools:

Tool	Behavior
swd_dry_run	Validates external-agent file actions without writing files or receipts
swd_apply	Applies external-agent file actions through SWD, can gate writes behind isolated checks, verifies disk state, rolls back failures, and writes receipts by default
receipts_list	Lists recent local SWD receipts
receipts_show	Reads a receipt by id, file path, or latest; pass format: "markdown" for PR-ready text
receipts_verify	Re-checks current files and receipt integrity
skills_list	Lists project-local and user-global skill packs
skills_check	Validates all skills or one named skill/path

The mutating MCP tool is still guarded by the same external-agent SWD policy as mythos swd apply: safe project-relative paths, sensitive path blocking, repo-local .mythos/policy.json rules, explicit allowRisky for high-impact command surfaces and deletes, rollback on failed verification, and local receipts for successful non-dry-run applies.

mythos receipts — SWD Trust Receipts

mythos receipts              # List recent SWD receipts
mythos receipts show latest  # Inspect the newest receipt
mythos receipts show latest --markdown  # PR-ready Markdown summary
mythos receipts show latest --format markdown  # Same output, useful for tooling parity with MCP
mythos receipts verify latest  # Re-check current files against receipt hashes
mythos receipts verify         # Verify all receipts AND the append-only chain
mythos receipts --json       # Machine-readable output for tooling

Every non-dry-run SWD file operation writes a local receipt to .mythos/receipts/. Receipts include the request summary, provider or external-agent/model identity, git branch/commit, per-file before/after hashes, rollback status, and verification errors. Built-in chat/run receipts also include token usage, budget snapshot, active skill packs, and optional --test-cmd result. verify first checks the receipt’s own integrity before opening any referenced workspace path, then streams current file hashes through the same repository path jail used by SWD. When run over all receipts, it also verifies the local append-only hash chain. Receipt and HEAD updates use same-directory atomic writes under a repository-scoped lock, so concurrent Mythos processes cannot assign the same sequence or silently fork the chain. Lock ownership includes a random token, PID, hostname, and creation time: live same-host writers are never reaped, dead same-host locks are reclaimed, and malformed or remote-host locks must exceed a stale grace period before recovery. The chain detects local gaps, duplicate sequences, forks, broken links, and mismatched tips; because the receipts and HEAD are stored under the same local account, an attacker able to rewrite the complete store can still manufacture a new self-consistent history. Signed or externally anchored receipts are a separate trust layer. --markdown, --pr, or --format markdown prints a compact paste-ready receipt summary for PR reviews, especially useful when a write failed or rolled back. Receipts are local by default and gitignored by default. They may include prompts, file paths, provider metadata, skill names, test command names, and a short test output tail. Do not publish raw receipts from private repositories; force-add only when you intentionally want a shared audit trail.

mythos verify — Local Memory Scan + CI Verification

mythos verify              # Scan and log results to MEMORY.md
mythos verify --dry-run    # Scan without writing to MEMORY.md
mythos verify --ci         # Read-only PR/diff verification for GitHub CI
mythos verify --ci --json  # Machine-readable CI report
mythos verify --ci --strict # Fail CI on warnings as well as high findings

Local mode scans your project and cross-references against MEMORY.md:

• ✅ Verified — Memory logs are present and up to date
• ❌ Missing — Memory references a file that doesn’t exist

CI mode does not call a model and does not require an API key. It reviews the current PR/diff for high-impact repo changes such as package scripts, npm lifecycle hooks, GitHub Actions workflows, shell/deploy surfaces, .env/.npmrc, .mythos/policy.json, high-confidence secrets, and changed Mythos receipts.

GitHub Actions example:

name: Mythos Verify

on:
  pull_request:
  push:

jobs:
  mythos-verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npx mythos-router verify --ci

See docs/CI.md for exit behavior, strict mode, JSON output, and examples.

mythos dream — Memory Compression

mythos dream              # Auto-compress when needed
mythos dream --force      # Force compression
mythos dream --dry-run    # Preview without writing

When MEMORY.md exceeds 100 entries, older logs are compressed into a summary block using Claude (low effort, minimal token burn). Recent entries are preserved intact.

mythos stats — Budget Analytics & Cost Profiling

mythos stats              # Show all-time token usage and costs
mythos stats --days 7      # Filter for the last week

Tracks every penny spent across all your projects. Costs are aggregated by:

• Command (e.g., chat vs dream)
• Project (directory name)
• Time Period

When a session ran file actions, stats also reports an SWD Verification summary: how many actions verified, how many claims were caught failing disk verification, correction turns, and the overall misreport rate — a measured “how often did the agent misreport a write” number rather than an asserted one.

Data is stored locally in ~/.mythos-router/metrics.json.

🔌 SDK Usage (For Agentic Systems)

mythos-router exposes its Strict Write Discipline engine for programmatic use:

import { WorkspaceContext, SWDEngine, parseActions } from 'mythos-router';

// Capture one canonical project identity at the integration boundary.
const workspace = new WorkspaceContext({ rootDir: process.cwd() });

// 1. Create an engine instance with your preferred options
const engine = new SWDEngine({
  // Embedded and parallel callers should always bind operations explicitly.
  rootDir: workspace.rootDir,
  strict: true,
  enableRollback: true,
  onAction: (action) => console.log(`Executing: ${action.operation} ${action.path}`),
  onVerify: (result) => console.log(`${result.status}: ${result.detail}`),
});

// 2. Let your agent generate code (must output [FILE_ACTION] blocks)
const agentOutput = await myAgent.generateCode();

// 3. Parse the agent's output and route through the SWD engine
const actions = parseActions(agentOutput);
const result = await engine.run(actions);

if (result.success) {
  console.log('✅ Agent execution verified securely');
} else {
  console.log('❌ Agent hallucinated a write. Rolled back:', result.rolledBack);
  console.log('Errors:', result.errors);
}

WorkspaceContext canonicalizes the project root once and derives a stable project identity from the canonical path. Repository-scoped helpers accept the context or its rootDir, so embedded or parallel Mythos operations do not rely on later process.cwd() changes. SWD, sandbox checks, project policy, Git, receipts, run records, memory, sessions, skills, MCP tools, and command wiring all use the captured workspace boundary. Legacy convenience APIs still default to the cwd present when they are invoked.

SWD canonicalizes rootDir when the engine is constructed and rejects action paths that escape it. Existing symbolic links are not followed in SWD action paths; a symlinked target or ancestor is rejected before mutation.

CREATE and MODIFY content is staged in an exclusive temporary file in the same directory, flushed, and committed atomically. CREATE uses no-replace semantics, so a destination created concurrently is never overwritten; MODIFY preserves its existing permission bits. SWD also checks that the target still matches its before-snapshot immediately before commit, refusing to clobber a concurrent edit.

SWDRunResult.rollbackStatus distinguishes not-needed, disabled, complete, partial, and failed. When recoveryRequired is true, committed filesystem state remains and should be inspected manually. The legacy rolledBack boolean remains available for compatibility. Every mutating batch now also creates a durable journal under .mythos/transactions/ before the first write. The journal records before-state hashes, intended after-state hashes, rollback backups, and progress markers. mythos doctor detects interrupted transactions; mythos doctor --repair restores only files that still match either the recorded before-state or the exact Mythos-written after-state, and fails closed on unrelated drift.

---

mythos doctor — Workspace Health and Recovery

mythos doctor             # Read-only health report
mythos doctor --json      # Machine-readable report and exit code
mythos doctor --repair    # Recover inactive SWD journals only

doctor checks the Node version, workspace permissions, fail-closed project policy, receipt store and local chain, scoped session structure, memory files, workspace-scoped provider telemetry, critical symlink surfaces, and persistent SWD transaction journals. The default command does not mutate the repository. --repair is intentionally narrow: it recovers inactive interrupted transactions and removes safe terminal journal residue, but never rewrites policies, receipts, sessions, telemetry, or user files speculatively.

Architecture

mythos-router/
├── src/
│   ├── cli.ts           # Commander.js entry point
│   ├── config.ts        # System prompt + constants + budget defaults + validation
│   ├── client.ts        # Provider facade (Anthropic/OpenAI/DeepSeek BYOK routing)
│   ├── budget.ts        # Session budget limiter (token cap, turn cap, progress bar)
│   ├── workspace.ts     # Canonical immutable project root and state identity
│   ├── swd.ts           # SWD execution kernel (engine, types, parsing, snapshots)
│   ├── atomic-writer.ts # Same-directory flushed atomic CREATE/MODIFY commits
│   ├── transaction-journal.ts # Durable SWD crash recovery records
│   ├── swd-cli.ts       # SWD terminal presentation (verification output, dry-run)
│   ├── sandbox.ts       # Isolated temp repo copy gate for external-agent checks
│   ├── sandbox-files.ts # Ignore-aware, secret-filtered workspace mirroring
│   ├── receipts.ts      # SWD trust receipt creation, storage, and verification
│   ├── skills.ts        # Project-local and user-global SKILL.md packs
│   ├── learn.ts         # Deterministic repo skill generator
│   ├── ci/              # Read-only CI verification for PR/diff risk review
│   ├── memory.ts        # MEMORY.md self-healing manager (SQLite FTS5 index)
│   ├── metrics.ts       # Global metrics store (persistent budget tracking)
│   ├── diff.ts          # Myers' diff algorithm (zero-dependency)
│   ├── git.ts           # Git operations (branching, committing)
│   ├── mcp.ts           # MCP stdio adapter for SWD, receipts, and skills tools
│   ├── mcp-config.ts    # Paste-ready MCP client config snippets
│   ├── project-policy.ts # Repo-local SWD policy loading and matching
│   ├── utils.ts         # Terminal formatting, badges, prompts (zero-dep ANSI)
│   ├── index.ts         # Public SDK exports
│   └── commands/
│       ├── chat.ts      # Interactive REPL (ChatSession + ChatUI abstraction)
│       ├── init.ts      # Project onboarding and read-only setup checks
│       ├── doctor.ts    # Workspace health and transaction recovery command
│       ├── verify.ts    # Codebase ↔ Memory scanner (dry-run aware)
│       ├── swd.ts       # External-agent SWD apply command
│       ├── mcp.ts       # MCP stdio server command
│       ├── receipts.ts  # SWD receipt list/show/verify command
│       ├── skills.ts    # Skill pack list/show/new/check command
│       ├── learn.ts     # Repo skill generation command
│       ├── dream.ts     # Memory compression (dry-run aware)
│       └── stats.ts     # Budget analytics reporter
├── src/providers/       # Multi-Provider Orchestration Engine
│   ├── orchestrator.ts  # Adaptive routing, circuit breakers, scoring
│   ├── pricing.ts       # Total + normalized token cost estimates
│   ├── errors.ts        # Typed provider error normalization
│   ├── types.ts         # Unified BaseProvider contracts
│   ├── anthropic.ts     # Claude provider
│   └── openai.ts        # Fetch-based OpenAI & DeepSeek provider
├── test/                # Automated test suite (node:test)
├── .mythosignore        # SWD scan exclusions
├── MEMORY.md            # Auto-generated agentic memory
└── AGENTS.md            # Project conventions

The SWD Protocol

User Input
    │
    ▼
[Claude Opus 5] ── adaptive thinking
    │
    ▼
[Parse FILE_ACTION blocks] ── extract claimed operations
    │
    ▼
[Snapshot referenced files] ── targeted filesystem state capture
    │
    ▼
[Verify] ── model claims vs. actual filesystem
    │
    ├── ✅ All verified → Log to MEMORY.md
    │
    └── ❌ Mismatch → Correction Turn (max 2 retries)
                │
                └── Still failing → Yield to human

Text FILE_ACTION protocol and native tool-calling

Mythos keeps plain-text [FILE_ACTION] blocks as the default because they remain provider-agnostic and work with any model backend. Native Anthropic/OpenAI-compatible tool-calling is available as an opt-in transport with --tools. Both paths feed the same SWD validation, path jail, atomic writer, verification, rollback, and receipt pipeline; enabling tools does not grant the model any additional filesystem authority.

Native tool conversations are stored in a provider-neutral structured history:

• assistant text and tool_call blocks are preserved together;
• every tool call receives a matching tool_result, including blocked, malformed, failed, and rolled-back writes;
• Anthropic histories are replayed as tool_use / tool_result blocks;
• OpenAI-compatible histories are replayed as assistant tool_calls followed by tool role messages;
• tool-only assistant turns are never serialized as empty messages; and
• provider fallback, SWD correction turns, test-healing turns, and chat --resume retain the complete tool exchange.

The text protocol remains the compatibility fallback if a selected model ignores the tool definition and emits [FILE_ACTION] output instead.

---

Configuration

Env Variable	Required	Description
ANTHROPIC_API_KEY	Optional*	Anthropic/Claude key; recommended default provider for chat/run
OPENAI_API_KEY	Optional*	OpenAI API key; can be used as the only configured provider or fallback
DEEPSEEK_API_KEY	Optional*	DeepSeek API key; can be used as the only configured provider or fallback
SURPLUS_API_KEY	Optional*	Surplus marketplace key (inf_...); OpenAI-compatible, routes the same models at a discount. Defaults to claude-opus-5.
MYTHOS_SURPLUS_MODEL	Optional	Override the Surplus model id (default claude-opus-5)
MYTHOS_SURPLUS_BASE_URL	Optional	Override the Surplus endpoint (default https://www.surplusintelligence.ai/api/inference/v1)

* mythos chat and mythos run need at least one model provider key. mythos swd apply needs no model key because an external agent brings its own model/key and Mythos only verifies file actions.

Provider routing guarantees

• ProviderConfig.maxConcurrency is a hard in-flight limit. When every eligible provider is saturated, requests wait for capacity instead of exceeding the configured cap. An aborted queued request is removed without calling a provider.
• Forced and deterministic routing do not silently change providers under load. They wait for the selected provider’s capacity slot.
• OrchestrationEvent.retryCount counts same-provider retries only. fallbackCount counts provider transitions, and fallbackReason preserves the actual triggering reason such as rate_limit, overloaded, timeout, or network_error.
• cost is the estimated total USD cost of that request. costPer1k is the blended estimated USD per 1,000 processed tokens and is the normalized value used by adaptive routing, so larger requests are not penalized merely for containing more tokens.
• Provider adapters throw ProviderError with structured kind, status, providerId, optional request ID/provider code, retryability, and the original error as cause.

File	Purpose
.mythosignore	Patterns to exclude from SWD scanning
.mythos/policy.json	Enforced repo-local SWD safety policy
.mythos/skills/	Optional project-local skill packs that can be committed with a repo
.mythos/receipts/	Local SWD receipts, gitignored by default because they may include prompts and file paths
MEMORY.md	Auto-generated agentic memory log
~/.mythos-router/skills/	User-global skill packs available across projects
~/.mythos-router/sessions/	Resumable chat session state

---

Token Usage & Budget

Claude model pricing (API, as of 2026-08)

Model	API ID	Input / 1M	Output / 1M	Role in Mythos
Claude Fable 5	claude-fable-5	$10.00	$50.00	Optional max (MYTHOS_ANTHROPIC_MODEL_HIGH=claude-fable-5)
Claude Opus 5	claude-opus-5	$5.00	$25.00	Default --effort high
Claude Sonnet 5	claude-sonnet-5	$2.00	$10.00	Default --effort medium
Claude Haiku 4.5	claude-haiku-4-5-20251001	$1.00	$5.00	Default --effort low / dream

Prior Opus IDs (claude-opus-4-8, etc.) remain in the pricing registry if you pin them via env.

Defaults: Mythos maps high → Opus 5, medium → Sonnet 5, low → Haiku 4.5. For the hardest long-horizon work, set MYTHOS_ANTHROPIC_MODEL_HIGH=claude-fable-5. Budget estimates use the model ID returned by the provider; unknown IDs fall back to Opus-class rates.

Graceful Save

When the budget is reached, mythos doesn’t just kill your session — it performs a graceful save:

⏸ BUDGET REACHED — Graceful Save
  498,231 tokens consumed across 25 turns (~$7.4200).
  Progress saved to MEMORY.md. Resume with mythos chat --resume to continue.
  Increase limits: mythos chat --max-tokens 1000000 --max-turns 50
  Disable limits:  mythos chat --no-budget

The system automatically saves conversation history and budget state under ~/.mythos-router/sessions/<project-id>/latest.json, where <project-id> combines the project name with a digest of its canonical root. Repositories with the same directory name therefore cannot resume one another’s session. Session format v2 preserves structured assistant tool calls and tool results. A matching legacy ~/.mythos-router/sessions/latest.json v1/v2 session is migrated one way into the scoped location when loaded. Malformed or incomplete tool histories are rejected rather than sent back to a provider. Restore the scoped context with mythos chat --resume.

Token counts, estimated cost, and budget status are displayed after every chat response.

---

Testing

npm test                 # Run full test suite
npx tsc --noEmit         # Type check only
npm run build            # Production build

---

License

MIT

---

Disclaimer

This project is an independent open-source tool built on top of the Anthropic API. It is not affiliated with or endorsed by Anthropic.