Nomos (Νόμος)

Agents guess; Git cannot. The transactional governance harness between any coding agent and your repository.

AI coding agents optimize for making their prompt finish, even when that means taking shortcuts. Without a deterministic boundary, agents routinely introduce three silent failures into production repositories:

• Reward Hacking Tests: Deleting, skipping, or weakening failing assertions instead of fixing the root cause.
• Hollow Shims & Stubs: Leaving empty // TODO stubs, mock returns, or dead unreferenced code to make a build compile.
• Unbounded Workspace Drift: Mutating main directly, polluting unrelated modules, or forgetting architectural context across sessions.

Just as PostgreSQL placed ACID transactions between concurrent applications and raw disk files, Nomos introduces a new infrastructure layer between your coding agent (Claude Code, Cursor, Antigravity, OpenCode, Windsurf, or Aider) and your Git repository - physically enforcing causal INT-*/SUB-* spec-vs-code DAGs, hermetic Git worktree sandboxes, 42 polyglot anti-reward-hacking AST quality gates (with trunk-pinned nomos.yaml), receipt-gated SQLite memory (mneme.db), and atomic Two-Phase Commit (2PC) releases before a single line can touch main:

⚡ Two commands to install and initialize. Invisible after that.
Run curl -fsSL https://sophialabs.ca/install | bash and nomos init once. There are zero custom slash commands to memorize, zero prompt templates to maintain, and zero manual handshake steps (nomos hook session-start runs nomos handshake automatically on session boot). You prompt Claude Code, Cursor, Antigravity, or OpenCode in plain English the exact way you already do, while Nomos governs worktree isolation, ~24ms single-file AST checks, and two-phase commits silently under the hood.

⚡ Quick Start (Under 60 Seconds)

1. Install the nomos Binary

curl -fsSL https://sophialabs.ca/install | bash

Installs the SHA-256-verified release binary directly to standard Go binary paths ($GOBIN / $(go env GOPATH)/bin / ~/go/bin; pass NOMOS_VERSION=v4.10.0 to pin a specific release tag). Or on Arch Linux / Omarchy via AUR, or directly from main via the Go toolchain (substrate/ subdirectory module):

yay -S nomos-bin
# or build from source:
CGO_ENABLED=0 go install github.com/mgantlett/nomos/substrate/cmd/nomos@main

To cleanly uninstall at any time:

curl -fsSL https://sophialabs.ca/uninstall | bash

2. Initialize Any Repository

cd your-project
nomos init

nomos init detects your language stack, scaffolds nomos.yaml (validated against nomos.schema.json), installs self-healing Git defense hooks (pre-commit, commit-msg, pre-push), and drops indirect-control agent contracts (AGENTS.md, CLAUDE.md) plus ambient lifecycle hooks (.agents/hooks.json) into your repo.

3. Prompt Your Coding Agent Naturally

You are done with the CLI. Open Claude Code, Cursor, Antigravity, OpenCode, or Windsurf and prompt in plain English:

> "Add TTL cache eviction to Store with unit tests"

Because nomos init injected AGENTS.md / CLAUDE.md and Git defense hooks, your coding agent autonomously executes the Nomos lifecycle under the hood:

# Executed autonomously by your coding agent (not typed by you):
nomos task chore "Add TTL cache eviction"          # 1. Agent provisions isolated worktree (worktrees/<repo>-SUB-1)
nomos verify -w worktrees/your-project-SUB-1       # 2. Agent runs 42 AST & DoD gates (self-correcting any failures)
nomos task sync SUB-1 -F .tmp/walkthrough.md       # 3. Agent atomically merges to main with a Git Notes audit receipt

🏗️ How It Works in Your Repository

1. Indirect Control & Persistent Memory (nomos init / nomos hook / nomos mem): Your coding agent reads the bootstrapped AGENTS.md / CLAUDE.md protocol, runs sub-5ms compiled lifecycle hooks (nomos hook session-start, pre-tool, post-tool), and queries Nomos Mneme (nomos mem recall) for sub-50ms hybrid vector and lexical architectural context before touching code.
2. Hermetic Worktree Sandbox & Causal Plane DAG (nomos task): Direct commits on main fail closed. Tasks separate intent/contract specs (INT-*) from substrate code (SUB-*) in a local causal DAG (nomos task pair, nomos task chore, nomos task dag), and every task executes inside an isolated Git worktree (worktrees/<repo>-<task>) governed by a strict state machine (IDLE → PLAN → EDIT → REVIEW → SYNC → LEARN).
3. 42-Gate Polyglot AST & Toolchain Verification (nomos verify): Before any code can be reviewed or merged, Nomos evaluates go/ast, embedded .scm S-expression query rules, wazero WebAssembly linear-memory scanning, pure-Go multiline-aware structural scanners, and native compiler/coverage probes (tsc --noEmit, pytest, cargo check, ruby -c, cmake, gradle/mvn, dotnet build, plus LCOV and Cobertura XML ratchets) across Go, TypeScript/Svelte, Python, Rust, Ruby, C/C++, Java, Kotlin, and C# - catching empty stubs, todo!()/pass/raise NotImplementedError shims, skipped-test annotations (t.Skip, @pytest.mark.skip, #[ignore], xit, @Disabled, [Fact(Skip=...)]), functions over 60 LOC (400 LOC file ceiling), cyclomatic complexity spikes (> 15), hardcoded paths, security flaws, and test coverage drops.
4. 1-Turn Auto-Remediation Loop (NomosError): When a gate fails, nomos verify emits a structured NomosError with the exact file, line, violated law, and remediation instruction so the coding agent fixes its own mistake on the next turn.
5. Physically Locked Trunk & Atomic 2PC Release (nomos task sync): Once all 42 gates pass, Nomos fast-forward merges the worktree into main, attaches a cryptographic Git Notes (refs/notes/nomos/releases) verification receipt, and prunes the sandbox.

🧩 Core Capabilities & Deep-Dive Specifications

🛡️ The 7 Laws of Nomos

Every check in nomos verify maps to one of seven compiled architectural laws (full 42-gate matrix in seven_laws_canonical_gate_matrix_spec.md):

📊 Verified Benchmarks & Runtime Footprint

Nomos is engineered so deterministic governance adds sub-second overhead on every agent turn while failing closed under adversarial stress (see tracetrial_harness_reliability_spec.md):

Terminal-Bench 2.0 Controlled A/B (Harbor · nomos-harbor · 89 / 89 Tasks)

Across all 89 containerized tasks in [email protected] holding Gemini CLI 0.67.0, vertex_ai/gemini-3.5-flash, and unmodified task timeouts fixed, adding compiled nomos hook pre-tool/post-tool governance lifted single-shot pass@1 from 65.17% (58 / 89) to 70.79% (63 / 89, +5.62 pp, 0 API crashes), and 84.27% (75 / 89, +19.10 pp, pass<=2) when resuming the 26 failed trials with nomos v4.7.0 (--budget-sec wall-clock advisories + interactive/binary stdout guards, cutting timeouts from 24 to 13):

External Harness Reliability (TraceTrial-Bench · arXiv:2610.32285)

Across all 95 containerized tasks in Trial by Trace (TraceTrial-Bench, arXiv:2610.32285) (190 paired Docker runs holding Claude Code v2.1.220 and Gemini 2.5 Flash-Lite fixed), adding compiled ~4ms nomos hook governance lifted Agent deliverables by +15.2% (+78.3% in Context & Continuity), lifted Harness reliability by +2.51 (44.89 → 48.78 Overall, 36W / 30T / 29L), and cut harness_caused failures by -18.2% (55 → 45). See the full 7-pillar paired scorecard and engineering takeaways in tracetrial_harness_reliability_spec.md.

🧭 Open-Core Boundary

Nomos Community Edition is 100% open-source under Apache 2.0 with zero telemetry, zero cloud account requirements, and zero crippled CLI commands. Every single-developer and single-repository governance capability runs locally out of the box (see LICENSE, NOTICE, and agent_tiers_and_indirect_control_spec.md):

📄 License

Licensed under the Apache License, Version 2.0. See LICENSE, NOTICE, and THIRD_PARTY_NOTICES.md for full text and attribution terms.