mythos-router

What is this?

mythos-router is a local CLI power tool that wraps Claude Opus 4.7 with a custom verification protocol called Strict Write Discipline (SWD).

Unlike standard Claude wrappers, mythos-router enforces filesystem verification: every file operation the AI claims to perform is checked against the actual filesystem using SHA-256 snapshots. If the model's claim doesn't match reality, it gets a Correction Turn. If it fails twice, it yields to the human.

Zero slop. Zero hallucinated state. Full adaptive thinking.

Features

| Feature | Description | |---------|-------------| | mythos init | Single-command project onboarding with environment validation, read-only --check, and scaffolding | | mythos run | One-shot prompt mode with inline, file, or stdin input: same SWD, budget, skills, branch, and optional test-healing pipeline as chat | | Multi-Provider Fallback | Auto-routes between Anthropic, DeepSeek, and OpenAI with circuit breakers | | Verified Skill Packs | Load project-local or user-global SKILL.md rules with -s <name>; active skills are recorded in SWD receipts | | Deterministic Caching | SQLite-backed caching for reasoning (SDK only) (Node 22+) | | Adaptive Thinking | Opus 4.7 with configurable effort levels (high/medium/low) | | Strict Write Discipline | Pre/post filesystem snapshots verify every model claim | | SWD Receipts | Per-run trust receipts record touched files, hashes, provider, budget, git state, and verification result | | 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 | | 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 4.7 | Architecture, deep reasoning, complex refactors | | medium | Claude Sonnet 4.6 | 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 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 core CLI runs perfectly on Node 20+. However, the advanced SQLite-backed features (Telemetry Dashboard, Deterministic Caching, and High-Performance Memory Index) require Node.js 22.5.0+. If you run the tool on an older version, these features safely degrade with a warning without crashing the router.

Quick Start (npm)

# Install globally
npm install -g mythos-router

# Set your API keys (Anthropic is primary, others are fallbacks)
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-proj-..."
export DEEPSEEK_API_KEY="sk-..."

# Initialize and start
mythos init
mythos chat

Or try without installing

npx mythos-router chat

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, and the project-local .mythos/skills/ directory.

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 "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 4.7)
mythos chat -s repo          # Load a project-local skill pack
mythos chat --test-cmd "npm test" # Enable autonomous test-driven self-healing
mythos chat --effort low     # Budget mode (Haiku 4.5)
mythos chat --effort medium  # Balanced (Sonnet 4.6)
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 --ma