nomos
Enforces repository governance around Git: Branch Guard blocks direct main/master writes and config/hook tampering, commit hooks run AST verification on feature branches, and worktree isolation is available for parallel agents.
Connects Nomos verification to GitHub repositories and Code Scanning, including public-repo X-Ray scans, PR receipts, and SARIF output uploaded through the Nomos GitHub Action.
Provides a reusable GitHub Action and scaffolded CI workflows that run zero-trust diff-mutation verification on pull requests, emit SARIF, and post verification receipts.
Scaffolds GitLab CI workflows for zero-trust PR/CI verification and mutation-proof gates.
This server has a remotely hosted endpoint. Open its connector listing for connection details, authentication requirements, and setup instructions:
Nomos (Νόμος)
Agents guess; Git cannot. The Apache 2.0 Go execution substrate beneath any coding agent (0 LLM tokens, certified up to 3.60M LOC).
Nomos is a single ~20 MB static Go binary (Apache 2.0, 0 LLM tokens, zero cloud account) between your coding agent (Claude Code, Cursor, OpenCode, Codex, Gemini CLI, Antigravity, Windsurf, or Aider) and Git. Run nomos init once (or paste 1 prompt into your agent) - Nomos blocks skipped tests, hollow stubs, monolith bloat, and leaked secrets in 24ms (<365ms full 42-gate diff verify even across 3.60M-LOC monorepos), your agent fixes its own mess mid-turn, and your feat/* workflow never changes:
You -> Same plain-English prompts, same IDE, normal feat/* PRs (0 new commands to learn)
|
Coding Agent -> Claude Code · Cursor · OpenCode · Codex · Gemini CLI · Antigravity · Windsurf
|
Nomos Substrate -> Invisible ~4ms hooks + 42 AST gates + Day-0 debt ratchet (0 LLM tokens)
|
Git -> main stays read-only & verified; shortcuts fail closed before commitInitialize once, then forget
nomosexists. Nomos supplies0-token repository physics; your coding agent supplies the intelligence to self-correct before ending its turn. Usenomos xray .anytime you want a~4scodebase health scan.
Two Ways to Set Up in 30 Seconds (Or Scan in Browser First)
Zero-Install Browser Scan (5s): Paste any public GitHub repository at sophialabs.ca/xray - or just replace
github.comwithsophialabs.cain your browser URL bar (e.g.https://sophialabs.ca/go-chi/chi) - to inspect its 11-languageAI Hangover Score(0-100) and download a pre-computednomos.baseline.json+ 4-line GitHub Action PR gate before installing anything locally.
Path A - Paste 1 Prompt Into Your Coding Agent (Zero Manual Setup):
Install Nomos (curl -fsSL https://sophialabs.ca/install | bash), run `nomos xray .` to summarize our Day-0 AI Hangover Score and top 3 structural hotspots, then run `nomos init` so Branch Guard, brownfield baseline ratcheting, and agent hooks run automatically underneath future feature branches (use `nomos init --local` if we want git status untouched; do not enable `--worktrees`).Path B - Run 3 Commands in Your Terminal:
curl -fsSL https://sophialabs.ca/install | bash
cd your-project && nomos xray . # 1. Read-only ~4s AI Hangover Score & hotspot scan (use --markdown to share)
nomos init # 2. Branch Guard + brownfield baseline + agent hooks (or --local for stealth trial)
git switch -c feat/auth # 3. Done - forget nomos and keep coding & committing as usualWhat happens automatically underneath your agent the next time it tries taking a shortcut on feat/*:
$ git commit -m "fix: resolve flaky billing test"
✗ [AntiShimGate] billing_test.go:42 skipped test (t.Skip) + 2 deleted assertions
✗ [UncheckedErr] billing.go:108 discarded error return on ledger.Charge()
✗ [ProtectedRubric] .golangci.yml linter config modified on feature branch
-> Commit blocked in 24ms (0 LLM tokens). Fix billing.go without weakening billing_test.go.Your coding agent receives that deterministic AST fix recipe mid-turn and repairs billing.go itself before handing control back to you.
How It Works Without Changing Your Workflow (100% Apache 2.0 Open-Core)
Every single-repository governance capability ships locally in the open-source nomos binary with zero crippled commands, organized around three clear boundaries:
1. What You Touch Once (30 Seconds: nomos xray, nomos init)
On-Demand 5s Stethoscope (
nomos xray . [--markdown]): Walksgit ls-filesacross 11 languages for anAI Hangover Score(0-100,Grade A-F), clones, monoliths (>400 LOC), stubs, swallowed errors, secret/host-path leaks, CWE sinks, and ready-to-lockarchitecture_boundarieswith zero repository writes. Run it on Day 0 or whenever you want a codebase report card.Non-Breaking Legacy Drop-In (
nomos init): Automatically freezes Day-0 debt bounds innomos.baseline.json(strict_mode: falseon brownfield, strict anywhere via--strict) so zero existing legacy files fail, ratcheting only touched files (<= 0added complexity/debt,>= 0coverage delta,0new clones or swallowed errors; self-hostednomosholds0/100 Grade Aunderstrict_mode: true). Auto-detects installed agents, scaffolds a compact~13-lineAGENTS.mdBranch Guard block, and wires native lifecycle + Git hooks (nomos --helpshows everyday commands;nomos --help-agentkeeps internal agent RPCs out of your way).Zero-Footprint Stealth Trial (
nomos init --local): Registers generated configs and hooks in.git/info/excludeinstead of.gitignore, leavinggit status100% clean while you evaluate solo; promote anytime withnomos init.
2. What Runs Invisibly Underneath Every Agent Turn (0 Commands to Learn)
Protected
main& Automaticfeat/*Verification: Defaultisolation_mode: "branch"blocks directmain/masterwrites and config/hook tampering (nomos.yaml,nomos.baseline.json,.git/hooks/*), while plaingit commitonfeat/*branches runs42polyglot AST gates across Go, TypeScript/Svelte, Python, Rust, Ruby, C/C++, Java, Kotlin, and C# in~460ms(~24mssingle-file radar,0LLM tokens) - catching skipped/deleted tests (t.Skip,@pytest.mark.skip,#[ignore],xit,@Disabled,[Fact(Skip=...)]), hollow stubs (todo!(),pass,NotImplementedError),>60 LOCfunctions (400 LOCfile ceiling),architecture_boundaries, andstrict_types.~4msPre-Tool Security Airlock & Loop Breaker (nomos hook): Denies agent reads of~/.ssh,~/.aws,~/.kube,~/.gnupg,~/.config/gcloud,.netrc,.npmrc,.pypirc, blocks cloud metadata SSRF (169.254.169.254), rejects unverified "tests pass" claims, and halts 3 consecutive non-progressing tool failures before burning context windows.Verified-Only Episodic Memory (
mneme.db/nomos mcp):.git/hooks/post-commitdistillstrap -> fixlessons into pure-Go SQLite (mneme.db,<50mslexical/vector recall + read-onlystdioMCP vianomos mcp) only after verification passes, so broken attempts never poison future agent sessions.
3. Optional Scale-Up When You Outgrow Single Branches (--ci, --worktrees)
Zero-Trust CI Diff-Mutation Proofs (
nomos init --ci,nomos verify --pr --mutate-diff): Mutates newly added conditionals/returns across Go, TS/JS, and Python so tautological tests fail closed on PRs, emits OASIS SARIF 2.1.0 for GitHub Code Scanning, and posts PR receipts viaaction.yml.Parallel Multi-Agent Worktrees (
nomos init --worktrees): Upgrade on demand when running multiple concurrent agents to enforce disposablegit worktreesandboxes, live exported-symbol collision radar (MTPO), and causal spec-before-code (INT/SUB) separation (see Architecture Blueprint below).
Related MCP server: uacos
Install Alternatives & Graduation Recipes
Alternative Package Managers & Updates
# Linux, macOS & WSL2 (SHA-256 verified release binary):
curl -fsSL https://sophialabs.ca/install | bash
# macOS & Linux (Homebrew):
brew install --cask mgantlett/tap/nomos
# Zero-install Node.js / Cloud Agent Sandbox Launcher (SHA-256 verified):
npx --yes @mgantlett/nomos xray .
# Arch Linux / Omarchy (verified PKGBUILD):
(tmp="$(mktemp -d)" && cd "$tmp" && curl -fsSLO https://raw.githubusercontent.com/mgantlett/nomos/main/packaging/aur/PKGBUILD && makepkg -si && rm -rf "$tmp")
# Build from source (Go 1.26+; GOTOOLCHAIN=auto fetches Go 1.26+ automatically):
GOTOOLCHAIN=auto CGO_ENABLED=0 go install github.com/mgantlett/nomos/substrate/cmd/nomos@main
# Agent Skill, Remote HTTP MCP & Claude Code Plugin Catalogs (Thin Binary Bootstrapper):
npx skills add mgantlett/nomos
claude mcp add --transport http nomos https://sophialabs.ca/mcp
# Or inside Claude Code: /plugin marketplace add mgantlett/nomos && /plugin install nomosUpdate or cleanly uninstall anytime:
nomos update && nomos update --sync-workspace
curl -fsSL https://sophialabs.ca/uninstall | bashOptional Graduation: CI PR Proofs & Parallel Worktrees
Install the official Nomos Zero-Trust PR Proof GitHub Action from GitHub Marketplace, or scaffold CI workflows locally when ready:
# Scaffold zero-phone-home GitHub Actions (SARIF) & GitLab CI workflows:
nomos init --ci
# Graduate an existing repo to isolated git worktrees & causal INT/SUB task twins:
nomos init --worktreesEnforce zero-trust PR mutation proofs in GitHub Actions (GitHub Marketplace):
- uses: actions/checkout@v4
with: { fetch-depth: 0 }
- uses: mgantlett/nomos@v4.29.0
with: { base-ref: origin/main, mutate-diff: 'true' }Cheap Workhorse Stack (
OpenCode+OpenRouter/ Local16GBGPU): Because.opencode/plugins/nomos.tsenforces frontier merge rules in local compiled Go (0middleman token tax),14B-32Bopen-weight models jump from27.8%to86.1%brownfield resolution (3.1xlift) while cutting token spend-43%to-57%.
Why Nomos Is a New Layer of the Stack
What Nomos Is Not | Why Existing Tools Leave | What the Nomos Transaction Layer Adds |
Not Another Coding Agent | Switching models or IDEs does not stop a stochastic optimizer from cutting corners at 70% context. | Keep your favorite agent; Nomos enforces sandbox isolation and merge rules underneath it. |
Not a Linter or Post-Hoc CI | Traditional linters assume honest humans after a branch is dirty; agents edit configs or add ignore comments. | Evaluates |
Not a | Markdown rules decay past 60% context, and unverified agent notes poison future sessions. | Enforces compiled Go exit codes ( |
Verified Benchmarks & Runtime Footprint
Reproduce locally in one command:
go -C substrate test ./cli -run "TestTraceTrialBench|TestCleanroomPolyglotObligation|TestCleanroomDownstreamVectors" -v
Engineering Metric | Verified Result | Proof / Suite |
Workhorse Brownfield Lift ( |
|
|
Prompt-Injection & Security ( |
| Official |
CLI Harness Security ( |
|
|
|
|
|
|
| Zero-hint refactors across |
|
| Lightweight |
Self-Dogfooding Velocity ( |
|
|
Footprint & Gate Latency |
|
|
1. Open-Weight & Commodity Workhorse Brownfield Lift (N = 108 Paired Episodes · 8B to 32B)
Across 108 paired zero-hint brownfield episodes (54 Stock vs. 54 Nomos v4.13.1, temp=0.0) spanning Python, TypeScript, and Go on 6 open-weight models sized for single-card 16GB-24GB GPUs (RTX 4080, RTX 3090, A10G, L4):
Open-Weight Model ( | Stock Verified ( | Stock Layer Purity | Nomos | Nomos Layer Purity | Governance Delta |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
2. Zero-Trust Security & Real-Repo OSS Debt Containment (1,587 Live Trajectories)
Benchmark Suite | Scale & Corpus | Ungoverned |
| Efficiency / Utility Delta |
Official |
| Indirect tool-hijack exposure |
| Only |
4-Model |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| Zero-file-hint refactors across | Leaked |
|
|
3. Terminal-Bench 2.0 Harbor Hub Trajectories & TraceTrial-Bench (arXiv:2610.32285)
Terminal-Bench 2.0(89 / 89Tasks viaHarbor·nomos-harbor): Multi-trialk=5evaluation (445Docker trials onGemini Flash) achieved76.40%Pass@1(340/445) and92.13%Pass@5(82/89tasks solved) at91.20%prompt cache stability. In paired single-shotGemini CLI 0.67.0A/B runs, Stock scored58 / 89(65.17%,49f21995) vs.63 / 89(70.79%,+5.62 pp) single-shot (39059e9a) and75 / 89(84.27%,+19.10 pp)pass<=2(6b9f81a5).Frontier Harness Fault-Containment (
TraceTrial-Bench·arXiv:2610.32285): Across190paired Docker runs (95tasks holdingClaude Code v2.1.220+Gemini 2.5 Flash-Litefixed),nomos hooklifted Context & Continuity by+78.3%, cutharness_causedfailures by-18.2%(55->45), and raised reliability from44.89to48.78.
When your team scales beyond single-branch workflows (nomos init --worktrees):
Hermetic Worktree Isolation: Direct edits in the root checkout fail closed;
nomos task chore/nomos task startmintscapbac.Leasecapabilities inside disposableworktrees/<repo>-<task>sandboxes (PLAN -> EDIT -> REVIEW -> SYNC -> LEARN).Two-Plane Spec-vs-Code Separation (
INT/SUB) &2PCSync: Separates human specifications (INT-*) from substrate implementation (SUB-*), whilenomos task syncruns42gates, fast-forwardsmain, records a SHA-256 Git Notes receipt (refs/notes/nomos/releases), and prunes the worktree.Multi-Worktree AST Collision Radar (
MTPO) &NCTE-100:nomos physicscomputes live exported symbol hulls across active sandboxes to prevent merge collisions, andnomos directive --lintenforces unambiguous controlled English inintent/specs.
Capability | Canonical CLI Surface | Architecture Specification |
Brownfield X-Ray, Indirect Control & Hooks |
| |
Worktrees, |
|
|
42-Gate AST, PR Receipts & Mutation Proofs |
|
|
NCTE-100 Directives & Config SSoT |
|
|
Receipt-Gated Episodic Memory |
|
Scope of Proof: Nomos verifies
<5mscompiled structural and traceability invariants (import boundaries, contract field parity, anti-shim AST checks,TC-*test bindings, and SHA-256 spec digests) rather than LLM-as-a-Judge critics or formal theorem provers (Coq,Lean,TLA+); runtime semantics remain governed by your test suite.
Full 42-gate matrix in nomos_intent_traceability_spec.md:
Law | Name | What It Prevents |
1 | Dual-Core Inversion | Unverified agent execution outside the phase state machine ( |
2 | Non-Verbal Proof | Conversational "tests pass" claims, |
3 | Hermetic Worktree | Direct commits on |
4 | Single Source of Truth | Broken documentation links, orphaned specs, and unaligned schemas ( |
5 | Zero Hardcoded Paths | Machine-specific absolute paths and secret literals ( |
6 | Canonical Singularity | Duplicate CLI aliases, rogue task keys, and filesystem symlinks ( |
7 | Fail-Closed Pre-Flight | Cross-plane drift, test coverage drops, static-analysis regressions, and vulnerability leaks ( |
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 intent/intent.md):
Capability Layer | Nomos Community Edition (Apache 2.0) | Sophia & Nomos (Sovereign) |
Zero-Init Brownfield X-Ray, Day-0 Debt Ratchet & Trunk-Pinned | ✅ Included | ✅ Included + X-Ray Debt Atlas HUD & Disjoint-AST Fleet Burndown ( |
Indirect Control for Tier 1 Coding Agents ( | ✅ Included | ✅ Included + 70/30 Cognitive Complexity Router ( |
42-Gate Polyglot Verification, PR Receipts & Diff Mutation Proofs ( | ✅ Included | ✅ Included + PR Mutation Proof Deck & Custom Enterprise Gates |
Pre-Tool Security & Anti-Snooping Airlock ( | ✅ Included | ✅ Included + Live 2D Firewall & Air-Gap Radar |
Causal | ✅ Included (Single-Repo Worktrees) | ✅ Included + Live |
Nomos Mneme Receipt-Gated Episodic Memory & Sanitized Issues ( | ✅ Included (Local Repo | ✅ + Sophia Memory Curation, Dream Cycle Synthesis, Mneme Cortex HUD & Squad Mesh |
Sophia & Nomos 4-Pillar Workbench & Sophia Flight Deck (Principal Architect & Orthogonal Critic over BYOK Cloud APIs or Local | Not Included (Lipgloss Terminal HUD Included) | 🔒 Sovereign Edition (Explore Tour) |
Headless Tier 2 Autonomous Worker Fleet & Adversarial Conformance Critic ( | Not Included | 🔒 Sovereign Edition (Interactive Demo) |
Turnkey Air-Gapped NixOS GPU Appliances & Offline Ed25519 Entitlement | Not Included | 🔒 Regulated & Enterprise (Adoption Profiles) |
Community & License
Community & Governance: Join GitHub Discussions for setup Q&A,
nomos.yamltuning, and feature ideas. SeeCONTRIBUTING.md,CODE_OF_CONDUCT.md, andSECURITY.md.License & Citation: Licensed under the Apache License, Version 2.0 (see
LICENSE,NOTICE, andTHIRD_PARTY_NOTICES.md). For academic citation, seeCITATION.cffand DOI10.5281/zenodo.24240539.
Available Tools
7 toolsnomos_capabilitiesInspect Compiled DoD Gates, Hooks & DirectivesARead-onlyIdempotentInspect
Inspect compiled Nomos Definition of Done quality gates, ambient Git/session hooks, embedded phase directives, or remediation guidance for a specific gate ID. Use when looking up gate invariants, hook behavior, or how to fix a specific gate ID. Do NOT use when searching project-specific historical decisions in Mneme (use nomos_mem_recall instead) or scanning live source files (use nomos_xray instead).
Inputs: id, type. Returns: gates_count
nomos_handshakeSynthesize JIT Session OrientationARead-onlyIdempotentInspect
Synthesize read-only Just-In-Time (JIT) session orientation, active task phase, and Next Actions for a repository without modifying files or Git hooks. Use when starting an agent turn to discover the active worktree and allowed phase actions. Do NOT use when checking global daemon/DB health without JIT directives (use nomos_status instead) or listing backlog tasks (use nomos_task_dag instead).
Inputs: dir. Returns: phase, next_actions
nomos_mem_recallSearch Nomos Mneme Episodic MemoryARead-onlyIdempotentInspect
Search Nomos Mneme institutional memory records (decisions, patterns, pitfalls, axioms) matching a keyword or semantic query. Use when retrieving prior architectural rationale, learned pitfalls, or workspace conventions before editing code. Do NOT use when inspecting compiled quality gate rules (use nomos_capabilities instead) or listing open backlog tasks (use nomos_task_dag instead).
Inputs: query (required), limit. Returns: count, items
nomos_statusInspect Workspace & Database Health StatusARead-onlyIdempotentInspect
Return a concise snapshot of workspace lifecycle phase, active Git branch, SQLite ledger health, and aggregate task counts. Use when checking overall host/database readiness or current branch state. Do NOT use when requesting full JIT phase playbooks (use nomos_handshake instead) or scanning code debt (use nomos_xray instead).
Inputs: no named parameters. Returns: phase, branch
nomos_task_dagList Unblocked Task DAG WavefrontARead-onlyIdempotentInspect
Query unblocked causal DAG wavefront tasks (including Agent-to-Agent scope_paths, TC-* obligations, and active worktree MTPO overlap flags) ready for execution without mutating task ledger state. Use when selecting the next unblocked INT-* or SUB-* task to start (to submit a new multi-node DAG subgraph, invoke CLI 'nomos task batch -F - --json'). Do NOT use when recalling past architectural decisions or lessons (use nomos_mem_recall instead).
Inputs: dir, limit. Returns: count, items
nomos_verify_impactCompute 1-Hop AST Reverse-Dependency Blast RadiusARead-onlyIdempotentInspect
Compute the deterministic 1-hop AST reverse-dependency blast radius of packages impacted by uncommitted or branch-modified files. Use when assessing which downstream packages and test suites are affected by current edits. Do NOT use when auditing full-repository structural complexity or AI Hangover Score (use nomos_xray instead).
Inputs: dir. Returns: dir, impacted_packages
nomos_xrayRun Zero-Write Polyglot AST Repository X-RayARead-onlyIdempotentInspect
Run a zero-write polyglot static AST structural X-Ray across a local repository directory to measure AI Hangover Score, cyclomatic/cognitive debt, and top hotspot files. Use when auditing overall codebase health, complexity hotspots, or brownfield baseline posture. Do NOT use when computing only the diff-scoped blast radius of modified files (use nomos_verify_impact instead) or looking up a single gate definition (use nomos_capabilities instead).
Inputs: dir, top. Returns: grade, hangover_score
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool targets a clearly distinct workflow: session orientation, status, task DAG, memory recall, impact analysis, structural X-ray, and gate capabilities. The descriptions explicitly disambiguate likely overlaps with 'Do NOT use... use X instead' guidance.
All tools use a consistent nomos_ prefix and snake_case formatting. The only minor inconsistency is grammatical style: some names are nouns (handshake, status, task_dag, capabilities) while others are verb phrases (mem_recall, verify_impact).
Seven tools is well within a healthy range for an agent-oriented orchestration/inspection server. Each tool has a distinct, justified role rather than duplicating surface area.
The read-only orientation and inspection surface is solid, but lifecycle mutations are noticeably absent: no task creation/update/completion, no memory write, and no gate execution tool. Some gaps are acknowledged via CLI alternatives, but agents cannot complete those workflows through this MCP surface alone.
Maintenance
Related MCP Connectors
AI-native git hosting — repos, PRs, issues, CI gates, and AI code review over MCP (60 tools).
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Related MCP Servers
- AlicenseBqualityDmaintenanceLocal MCP server providing project cognition capabilities for AI coding agents, including context packs, impact analysis, and git diff review through stdio communication.103MIT
- AlicenseNot gradedqualityBmaintenanceLocal-first code intelligence and safety layer for AI coding agents. MCP server exposes dependency graph, impact analysis, and AST-compressed repo context, backed by typed local memory, patch-scope safety gates, and git-independent transaction rollback.1MIT
- AlicenseNot gradedqualityCmaintenanceLocal-first MCP server that provides project context, verification gates, and structured tools for coding agents to discover knowledge, run diagnostics, and execute allowlisted commands within a repository.40 npmMIT
- AlicenseCqualityBmaintenanceLocal-first MCP runtime for coding agents with bounded workspace access, content-preconditioned writes, AST search, LSP navigation and diagnostics, and Git status/diff. Designed to give coding agents useful repository access without treating unrestricted shell access as the default integration boundary.133MIT