██████╗ ██╗████████╗██╗ ██╗ █████╗ ██╗ ██╔══██╗██║╚══██╔══╝██║ ██║██╔══██╗██║ ██████╔╝██║ ██║ ██║ ██║███████║██║ ██╔══██╗██║ ██║ ██║ ██║██╔══██║██║ ██║ ██║██║ ██║ ╚██████╔╝██║ ██║███████╗
╚═╝ ╚═╝╚═╝ ╚═╝ ╚═════╝ ╚═╝ ╚═╝╚══════╝
s u m m o n · r e v i e w · v e r i f y

A fast, eldritch-themed TUI that drives a multi-LLM coding workflow:
Claude Code implements, OpenAI Codex adversarially reviews plans, designs tests,
and second-reviews diffs, every loop grounded in your project's ./check.sh.

Explore the guide »

View Demo · Roadmap · Playbook · Usage

Table of Contents

1. About The Project
   • Built With
2. Features
   • The loop
   • Running things
   • Trust & audit
   • Ergonomics
3. Getting Started
   • Prerequisites
   • Installation
4. Usage
   • Quick start
   • Configuration
   • Recipes
   • Default keys
5. Roadmap
6. Design Notes
7. Documentation
8. Development
9. Acknowledgments

About The Project

╭ feature title ─────────────╮╭ ritual ──────────────────────────────────────╮
│ > ! feat-auth ││ live | findings | history | plan │
│ main ││ * claude-fable-5 │
│ ───────────────────────────││ > mcp__codex__codex {"prompt":"critique..."} │
│ > spec ││ -> Finding 1 (major): missing rollback step │
│ / plan-review ││ $0.31 4 turns 92.3s │
│ o tests-red ││ │
│ ││ │
│ feat/auth ││ │
│ * claude ok (max) ││ │
│ * codex ok | bridge ok ││ │
│ check green ││ │
╰────────────────────────────╯╰──────────────────────────────────────────────╯
enter run | : commands | j/k move | ? help $1.42/$5.00 / plan-review

ritual is built on one bet, backed by the research: external feedback is the quality engine. Tests, checks, mutation kills, and cross-model review beat any single model talking to itself. Everything here exists to make that loop fast, auditable, and cheap to repeat:

• A per-branch pipeline (spec → plan → plan-review → tests-red → implement → dual-review → coverage) where the adversarial stages run a different vendor's model against Claude's work
• Runs are daemons: archived raw before parsing, resumable after any crash, tamper-evident forever
• Findings are the currency: every gate (models, mutation testing, secret scanning, a third reviewer) emits the same anchored JSON, adjudicated with two keys and enforced by one exit-code contract

Everything ritual orchestrates, and what's optional:

flowchart TD
ritual["ritual<br/>TUI + CLI"]
ritual ==> claude["Claude Code<br/>required · implements, plans, judges"]
ritual ==> codex["Codex CLI<br/>required · adversarial reviewer"]
claude <-->|"MCP bridge<br/>(codex mcp-server)"| codex
ritual ==> check["./check.sh<br/>required · your lint/type/test gate"]
ritual -.-> optbox
subgraph optbox ["optional · feature-gated"]
direction TB
rabbit["CodeRabbit CLI<br/>third reviewer"] ~~~ mutants["cargo-mutants<br/>mutation gate"] ~~~ gh["gh CLI<br/>pr-comment"] ~~~ srt["srt sandbox<br/>wraps headless runs"]
pal["pal MCP + Gemini<br/>consensus arbitration"] ~~~ leaks["gitleaks<br/>secrets gate"] ~~~ nvim["running nvim<br/>open/quickfix"] ~~~ pandoc["pandoc<br/>PDF reports"]
end
%% solid/bold = required · dashed/muted = optional; vendor colors match the pipeline diagram
classDef core fill:#0f172a,stroke:#334155,color:#ffffff
classDef claudec fill:#d97757,stroke:#b45309,color:#ffffff
classDef codexc fill:#10a37f,stroke:#047857,color:#ffffff
classDef gate fill:#22c55e,stroke:#15803d,color:#052e16
classDef opt fill:#94a3b8,stroke:#64748b,color:#0f172a
classDef optframe fill:transparent,stroke:#64748b,stroke-dasharray:6 4,color:#64748b
class ritual core
class claude claudec
class codex codexc
class check gate
class rabbit,pal,mutants,leaks,gh,nvim,srt,pandoc opt
class optbox optframe

Loading

(back to top)

Built With

(back to top)

Features

The loop

%%{init: {"flowchart": {"curve": "basis"}}}%%
flowchart TD
subgraph pipe [" the per-branch pipeline · every stage = one budgeted, archived, resumable run "]
direction LR
spec["spec<br/>you + claude chat<br/>→ spec.md"]
plan["plan<br/>claude · plan mode<br/>→ plan.md + ## Deliverables"]
pr["plan-review<br/>codex critiques the plan<br/>via the MCP bridge"]
tr["tests-red<br/>codex designs the tests<br/>claude writes them failing"]
impl["implement<br/>claude resumes the<br/>red session → green"]
dr["dual-review<br/>claude ∥ codex · blind<br/>only agreement confirms"]
cov["coverage<br/>read-only judge<br/>tree vs ## Deliverables"]
spec --> plan --> pr --> tr --> impl --> dr --> cov
end
arch[".ritual/architecture.md<br/>the generated map"] -.->|grounds| plan
arch -.->|"duplication / boundary<br/>ground truth"| pr
check{{"./check.sh<br/>your lint · types · tests<br/>the non-negotiable gate"}}
tr -.->|"red:<br/>must fail"| check
impl -.->|"green:<br/>must pass"| check
findings[".ritual/findings/*.json<br/>anchored findings ·<br/>the one currency"]
pr & dr & cov -->|emit| findings
findings -->|"F/A batch"| fix["code-fix<br/>claude fixes → check.sh →<br/>independent re-review"]
fix -->|"only confirmed-resolved<br/>marked fixed"| findings
cov ==>|"zero gaps · check green<br/>no open findings"| done(["ritual complete<br/>done means done"])
done -->|auto-refresh| arch
%% orange = claude · teal = codex · purple = cross-model · blue = judge/driver · amber = artifact · green = gate/done
classDef you fill:#64748b,stroke:#475569,color:#ffffff
classDef claude fill:#d97757,stroke:#b45309,color:#ffffff
classDef codex fill:#10a37f,stroke:#047857,color:#ffffff
classDef both fill:#8b5cf6,stroke:#6d28d9,color:#ffffff
classDef judge fill:#3b82f6,stroke:#1d4ed8,color:#ffffff
classDef artifact fill:#f59e0b,stroke:#b45309,color:#1f2937
classDef ok fill:#22c55e,stroke:#15803d,color:#052e16
classDef laneframe fill:transparent,stroke:#334155,stroke-dasharray:2 3,color:#64748b
class spec you
class plan,impl claude
class pr codex
class tr,dr both
class cov,fix judge
class arch,findings artifact
class check,done ok
class pipe laneframe

Loading

Every box above is a real, separately budgeted run (budget_*_usd), and every stage's model is yours to route: the [models] table pins a model per stage (e.g. plan = "claude-fable-5"), [effort] sets its reasoning effort, and fallback_model catches provider overloads mid-run.

• The pipeline: per-branch stages spec → plan → plan-review → tests-red → implement → dual-review → coverage; one-key launch; headless stages stream live; interactive stages hand you a real attached claude session and resume the TUI on exit.
• Chat to author the spec/plan (s): a split view with the live document on the left (focused section highlighted in place) and a conversation on the right: type an instruction and Claude edits spec.md (or plan.md) in place while you watch, scopable to the whole doc or one ## section (Tab to switch; a missing plan is drafted from the spec). Ctrl+Z/Alt+Z undo/redo (persisted 10-deep stack), Ctrl+X cancel, Alt+Enter multi-line, messages queue while an edit runs, and reopening chat reattaches to a still-running edit. Alt+←/Alt+H unfocus the input into sidebar mode - j/k drive the pipeline with the draft kept (rebind-proof escapes; l/s return to typing; an accidental close stashes the draft with its target for reopen). The agent is hard-scoped at the permission layer: it can read the project but write only the targeted document. Also headless: ritual chat "<msg>" [--plan] [--section …].
• Findings lifecycle: on the findings tab, f marks fixed and d dismisses (write-through to the JSON; v shows/hides resolved); the selected finding shows the verbatim source snippet it anchors to. The exit-code/CI contract follows: a confirmed critical blocks until resolved. ritual pr-comment [N] [--inline] posts the open findings to the branch's GitHub PR, redacted.
• Quality gates: ritual mutants mutates only your diff (cargo-mutants) and turns every mutant the tests failed to kill into an anchored finding (a proven test gap, advisory); ritual secrets gitleaks-scans exactly what changed (incl. untracked files) and its critical findings block until dismissed or fingerprinted (auto-run before every dual-review). .ritual/invariants.md is the project constitution: every bullet becomes an acceptance criterion re-injected into each review stage. ritual lessons distills your f/d dispositions into review memory the critic reads first. It stops re-flagging what you already dismissed.
• Whole-project audit (ritual audit, optional): every other gate reviews a change; this one reviews the system. Blind parallel review lanes, one per flow/tech (--discover enumerates them into an editable .ritual/audit-lanes.md) plus an always-on global-overview lane for cross-flow contracts, adjudicated by an adversarial judge that demands an independent Codex verdict per finding. Lands standard findings (stage audit) that triage like any review. Run it at milestones, not per commit.
• Architecture map (ritual architect): one budgeted survey writes .ritual/architecture.md - modules, data flows, conventions, extension seams, boundaries - via a validated candidate swap that can never damage the live map. Once it has real content the plan stage aligns with it and plan-review flags plans that rebuild what already exists; a .ritual-scoped fingerprint marks it stale when SOURCE moves (ritual's own artifacts never trip it), surfaced in the sidebar, status, doctor, and the plan stage-detail; ritual complete auto-refreshes it at genuine completion so the next feature plans against post-feature reality.
• Done means done (ritual complete): plans declare a ## Deliverables checklist; the read-only coverage judge checks each item against the actually-built tree and files a gap per miss; complete auto-drives the gaps through bounded, budget-capped fix rounds (containment-gated: a fixer that edits outside its target, self-certifies a checkbox, or commits gets reverted/rejected); complete --check is the token-free CI gate.
• Third reviewer, ensemble-style, optional CodeRabbit CLI review before each dual-review: its comments land as unconfirmed single-source findings that never block; the dual-review skill verifies or refutes each one. Three agreeing sources is the strongest signal there is.
• Reproducible workbench: the whole multi-LLM setup (14 skills incl. /spec and the optional /consensus, the code-reviewer agent, both hooks) is vendored in workbench/ and installed by ritual init --skills; ritual skills diff shows exactly where installed copies diverge. An optional third-model consensus tier ([consensus] enabled, pal MCP + Gemini) lets plan-review escalate one contested finding for arbitration.

Running things

flowchart LR
ui["TUI / CLI"] -->|"spawn detached (setsid)"| daemon["run daemon<br/>survives the TUI"]
daemon -->|"raw stream archived BEFORE parsing"| runs[".ritual/runs/&lt;id&gt;.jsonl"]
daemon -->|on exit| meta["&lt;id&gt;.meta.json<br/>cost · session · hash-chain link"]
runs -->|tail| ui
gates["dual-review · plan-review · coverage<br/>audit · mutants · secrets · coderabbit"] -->|"anchored findings JSON"| findings[".ritual/findings/*.json"]
findings -->|"f fixed / d dismissed · F/A fix batches"| ui
findings ==>|"exit-code / CI contract"| ci["ritual run --ci · complete --check"]
%% slate = your terminal · blue = ritual machinery · amber = artifacts · purple = gates · green = CI verdict
classDef term fill:#64748b,stroke:#475569,color:#ffffff
classDef machine fill:#3b82f6,stroke:#1d4ed8,color:#ffffff
classDef artifact fill:#f59e0b,stroke:#b45309,color:#1f2937
classDef gatec fill:#8b5cf6,stroke:#6d28d9,color:#ffffff
classDef verdict fill:#22c55e,stroke:#15803d,color:#052e16
class ui term
class daemon machine
class runs,meta,findings artifact
class gates gatec
class ci verdict

Loading

• Runs are daemons: every headless run detaches (setsid) and survives the TUI, the terminal, and reboots of your session. The raw event stream is archived to .ritual/runs/*.jsonlbefore parsing; the TUI is just a tailer. Restart ritual and it reattaches to live runs, reconciles anything that finished while you were away, and announces parallel runs it can't attach. Cancel kills the whole process group.
• Run control from anywhere: ritual ps lists live daemons, ritual attach <run-id> streams one into any terminal (--kill stops it). ritual doctor [--deep] checks agents, auth, MCP wiring, skills drift, hooks, check.sh, gates, and disk pressure. ritual clean [--keep N] [--dry-run] prunes old run artifacts: live/state-referenced/today's runs protected, pruned chained runs attested by a tamper-evident checkpoint so verify-log never breaks.
• Attempts + resilience: fallback_model keeps headless runs alive through provider overloads; [retry] models offers retry <stage> with <model> in the palette for failed stages (run --model on the CLI); the sidebar shows ×N attempts and history/reports grow a model column.
• Parallel features in git worktrees: ritual new "Title" --worktree feat/x creates a worktree sharing ONE .ritual/ state in the main repo. The sidebar lists all features with a needs-you queue (! badge, attention-first ordering); [] cycle features; runs execute in the right checkout automatically.
• One-key takeover: a reattaches the selected stage's recorded session interactively (claude --resume <session-id>).

Trust & audit

• Safety + money: gitleaks-style secret redaction on every archived line, stream, and report (vendor key shapes, PEM blocks, assignments, entropy tokens; redaction = false to opt out). Daily budgets (budget_daily_usd) with a status-bar meter and run refusal (--force overrides); offline = true hard-blocks every agent spawn (metered/plane kill-switch); ritual costs for per-stage, cache-aware spend analytics. Desktop notifications on stage completion.
• Provenance: every run records a reproducibility bundle (git commit, dirty-diff hash, claude/codex versions, skill-file hashes, config snapshot; ritual repro <run-id> diffs it against your current env) and a tamper-evident hash chain (ritual verify-log walks it and reports the first break) - parallel-safe: concurrent daemons (audit lanes, worktrees sharing one .ritual/) serialize on a chain lock and verify in linkage order.
• Sandboxing: [sandbox] wrapper spawns every headless run under Anthropic's srt (or any argv prefix) from the single spawn chokepoint; supervisor-owned, persisted per run, recorded in the meta (example settings).
• CI mode: ritual run dual-review --ci writes JUnit XML to .ritual/ci/ (confirmed critical/major findings = failures) and exits nonzero. Findings browsing is scriptable: --json everywhere, ritual findings exits 1 on confirmed criticals.
• Standards-shaped telemetry: ritual export emits OTLP-JSON spans with OTel GenAI semconv attributes for any OpenTelemetry collector; --audit-trail emits IETF draft-sharif agent-audit-trail records (RFC 8785-canonical, SHA-256 hash-chained JSONL).

Ergonomics

• Keyboard-first: every action is rebindable ([keys] table), and the : command palette fuzzy-matches all actions, per-stage runs, dynamic retries, and your own [commands] templates (lazygit-style, with {{branch}}, {{run_id}}, {{finding.file}}, {{finding.line}}).
• nvim remote control: ritual drives your running nvim (no suspend, no nested editors): o opens the selected finding at file:line in it, Q pushes all located findings into its quickfix list (:copen included). Discovery: $NVIM → newest $XDG_RUNTIME_DIR/nvim.*.0 socket → nvim_server config; the sidebar shows nvim ok when one is found. Falls back to attached $EDITOR when nvim isn't running.
• Bench: ritual bench plan-review --runs 5 [--golden expected.json] scores repeated runs (findings, cross-confirmation, golden recall, cost, mean/σ spread, cost-per-hit) for model/prompt comparison.
• Reports (ritual report [--pdf]): one Markdown document per feature (pipeline state, spec, plan, findings + evidence snippets, runs, per-stage costs), redacted, pandoc-converted when available.
• In-app guide: tab 5 renders the full guide & tips inside the TUI.

(back to top)

Getting Started

Prerequisites

Verified against: Claude Code 2.1.205, Codex CLI 0.144.1 (July 2026).

• Claude Code, logged in: the multi-LLM skills install with ritual init --skills (or see the playbook)
• Codex CLI, authenticated

  npm i -g @openai/codex && codex login

• The codex MCP bridge

  claude mcp add --scope user codex -- codex mcp-server

• Optional, feature-gated: gitleaks (secrets gate), cargo-mutants (mutation gate), gh (pr-comment), coderabbit (third reviewer), @anthropic-ai/sandbox-runtime (sandbox), pandoc (PDF reports), pal-mcp-server + a Gemini key ([consensus] third-model arbitration), a running nvim (open findings / quickfix; falls back to $EDITOR)

Installation

1. Clone and install the binary

   git clone <this repo>&&cd ritual
   cargo install --path . --root ~/.local # → ~/.local/bin/ritual

2. Install the vendored workbench (skills, agent, hooks) into ~/.claude

   ritual init --skills

3. Verify everything in one shot

   ritual doctor

(back to top)

Usage

Quick start

cd your-project
ritual init # .ritual/, stack-detected check.sh, CLAUDE.md, invariants.md
ritual new "My feature"# or: ritual new "Big thing" --worktree feat/big
ritual # the dashboard

Scriptable: status|findings|history|costs [--json], run <stage> [--force] [--ci] [--model m], complete [--check], audit [--discover], chat "<msg>" [--plan] [--section s], mutants [--base ref], secrets, lessons [--stdout], report [--pdf], repro <run-id>, verify-log, bench <stage> --runs N, ps / attach <run-id> [--kill], clean [--keep N], doctor [--deep], skills diff, export [--out f] [--audit-trail].

For the full manual, including a start-to-finish walkthrough of every feature, see the guide (also rendered in-app on tab 5).

Configuration

.ritual/config.toml or ~/.config/ritual/config.toml (layered: defaults ← user ← project ← env ← flags):

theme = "eldritch"# or tokyonight; --ascii for no Nerd Fontbase_ref = "main"budget_daily_usd = 5.0# omit for no ceilingbudget_plan_review_usd = 5.0# per-run --max-budget-usd capsbudget_dual_review_usd = 10.0budget_finding_fix_usd = 1.0# per F-apply batch run (answers ALL queued findings)budget_code_fix_usd = 5.0# per code-fix batch (fix + check + re-review)budget_coverage_usd = 2.0# per coverage judge passbudget_audit_usd = 3.0# per audit LANE; the judge's cap scales with lane countaudit_max_lanes = 8# global-overview lane always survives the capbudget_architect_usd = 3.0# per architecture-map survey (ritual architect)redaction = truenotifications = truecheck_timeout_secs = 600# hung build / dead HIL board can't wedge the loopoffline = false# true = BLOCK all agent runs (metered/plane kill-switch)fallback_model = ""# overload fallback for headless claude runs# nvim_server = "/run/user/1000/nvim.12345.0" # explicit socket (auto-discovered otherwise)
[keys] # rebind any actioncheck-full = "W"
[models] # per-stage model routingplan-review = "opus"
[effort] # per-stage reasoning effort (plan-fix = the F fix runs)plan = "xhigh"
[retry] # palette offers for failed stagesmodels = ["claude-opus-4-8"]
[mutants] # mutation-kill gate (ritual mutants)cmd = "cargo mutants"timeout_secs = 300
[secrets] # gitleaks gate (auto before dual-review)enabled = true
[sandbox] # wrap headless runs (srt recipe in the guide)enabled = falsewrapper = ""
[coderabbit] # third reviewer (cloud-backed, off by default)enabled = false
[consensus] # third-model arbitration (off by default)enabled = false
[architect] # the generated architecture mapenabled = true# false silences the missing/stale nudgesauto_refresh = true# refresh the map when `ritual complete` reaches done
[commands] # palette-invocable templatesblame = "git log --oneline -3 -- {{finding.file}}"

Recipes

GitHub Actions gate

- name: dual review gaterun: | ritual run dual-review --ci ${{ github.base_ref }}- uses: mikepenz/action-junit-report@v4if: always()with: { report_paths: ".ritual/ci/*.xml" }

Air-gapped / local models: point the seam at any local agent CLI: claude_cmd = "my-ollama-agent" (or env RITUAL_CLAUDE_CMD); have it answer the tiny auth probes the way tests/fake_agent.sh does. Everything that matters (archives, findings, reports, chain) is local files; nothing requires cloud auth. offline = true is something else: a hard kill-switch that refuses to spawn any agent run (metered connections, planes) while the TUI, findings, and reports keep working.

Embedded / hardware-in-the-loop: use templates/check-hil.sh (build → flash → capture serial → assert) as your project's check.sh and set check_timeout_secs low enough that a dead board fails fast.

Default keys

All rebindable via [keys]:

enter run stage / finding details · s chat: edit spec/plan · : palette · S settings editor · j/k move · h/l focus sidebar/panel · tab1-5 panes (5 = in-app guide & tips) · f/d/v finding fix/dismiss(+reason)/show-resolved · F queue + apply claude answers (plan + code, batch, gated) · A queue all code fixes · m queue manual · t one-touch recommended triage · u revert applied batch · / filter list · [] features · a takeover · o open in nvim · Q findings → quickfix · c/C check fast/full · x cancel · e editor · r refresh · g/G scroll/follow · ? help · q quit. In chat: Ctrl+Z undo · Alt+Z redo · Ctrl+X cancel · Alt+Enter newline · Alt+←/Alt+H sidebar mode (j/k pipeline, l/s back to typing)

(back to top)

Roadmap

Everything that shipped per version (v0.2 → v0.13 · panel focus), the deferred list, the design rationale behind each item, and the non-goals live in ROADMAP.md.

(back to top)

Design Notes

• Drift-tolerant parsing: unknown stream-json events render dimmed (Raw), never crash; field names verified against live captures in tests/fixtures/. The same philosophy covers the cargo-mutants, gitleaks, and CodeRabbit adapters.
• Zero-token testing: RITUAL_CLAUDE_CMD/RITUAL_CODEX_CMD (and RITUAL_GH_CMD, RITUAL_MUTANTS_CMD, RITUAL_GITLEAKS_CMD, RITUAL_CODERABBIT_CMD) swap in fake CLIs from tests/; the entire pipeline, including daemon survival, gates, and the audit chain, is E2E-tested without an API call.
• Accessibility: state is never color-only (every status has a distinct glyph); --ascii replaces Nerd Font icons; NO_COLOR and piped output disable color.
• Terminal safety: one guard owns raw-mode transitions; a panic hook restores your shell; Ctrl-C in a child can't kill the TUI.

(back to top)

Documentation

• Guide & tips: the full manual, also rendered in-app on tab 5
• Roadmap: what shipped per version, what's deferred, design rationale
• Multi-LLM playbook: the workflow's research grounding and setup reference
• srt sandbox settings example: starting config for sandboxed runs

(back to top)

Development

./check.sh = fmt + clippy -D warnings + tests (546 across unit/CLI/snapshot suites, incl. proptest property tests); bash tests/e2e_live.sh drives the installed binary through 80 lifecycle checks token-free. Builds land in /var/tmp/ritual-target (see .cargo/config.toml). The repo dogfoods its own workflow (CLAUDE.md); demo.tape renders the demo GIF to assets/demo.gif via vhs (vhs demo.tape).

(back to top)

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option. This is the conventional Rust dual-license: it maximizes compatibility (MIT's simplicity, Apache-2.0's explicit patent grant) so anyone can use ritual in any project.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

(back to top)

Acknowledgments

• ratatui: the TUI framework; lazygit and k9s set the bar for what a pro TUI owes its user
• cargo-mutants and gitleaks: the engines behind the quality gates
• Anthropic sandbox-runtime: supervisor-owned sandboxing done right
• Meta's ACH (mutation-guided test hardening) and the 2026 multi-agent evidence base: the research this workflow is shaped by
• Best-README-Template via awesome-readme: this README's skeleton

(back to top)

---

_{ritual is a solo-power-user tool, built by dogfooding the workflow it drives. Every feature above was planned, cross-model-reviewed, and shipped through the pipeline itself.}