Nomos OS Docs

Appearance

Getting Started with Nomos ​

Nomos is a deterministic engineering substrate for autonomous AI coding agents. It replaces stochastic conversational guardrails with compiled Go binaries, isolated transient Git worktrees, SQLite transactional state, and 36 machine-enforced AST verification gates.

⚡ Prerequisites ​

  • Go: 1.24+ (compiled substrate engine)
  • Git: 2.40+ (worktree and notes support)
  • Nix / Direnv (Optional, Recommended): For deterministic reproducible host environments
  • SQLite: Local state engine (~/.nomos/data/db/)

📦 Installation & Setup ​

1. Build & Install CLI ​

Clone the repository and install the nomos binary directly into your ~/.nomos/bin or $GOPATH/bin:

bash
git clone https://github.com/mgantlett/nomos.git
cd nomos
make install

Ensure ~/.nomos/bin is in your $PATH:

bash
export PATH="$HOME/.nomos/bin:$PATH"

2. The Boot Handshake ​

Every agentic engineering session begins with the boot handshake. This verifies SQLite database health, indexes subconscious GitBrain memories, and injects localized architectural context:

bash
nomos handshake

🔄 The 4-Stage Autonomous Engineering Loop ​

Nomos enforces strict Phase Discipline across four procedural gates:

1. Claim & Sandbox (PLAN Phase) ​

When an agent claims a task, Nomos snapshots uncommitted working tree diffs, provisions an isolated transient Git worktree (worktrees/<repo>-<task>), dynamically links dependencies via go.work, and locks the workspace to read-only PLAN phase:

bash
nomos task start NOM-101

2. Transition to Edit (EDIT Phase) ​

Before modifying source code, the agent transitions to EDIT phase to acquire the cryptographic workspace lock:

bash
nomos task transition EDIT

(For surgical $\le 3$-line hotfixes, use nomos task transition EDIT --override=surgical)

3. Definition of Done (REVIEW Phase) ​

Before committing, Nomos runs 36 binary AST quality gates verifying zero cyclomatic complexity debt ($< 15$), docstring density ($\ge 10%$), clean import boundaries, and full TDD test suite execution:

bash
nomos verify

4. Atomic Release & Teardown (IDLE Phase) ​

Once verification passes, the release is executed via an atomic Two-Phase Commit (2PC):

bash
nomos task sync --approve -F walkthrough.md

This command signs the phase state, validates the walkthrough schema, fast-forward merges into the active branch, prunes the feature branch, tears down the transient worktree, and resets the workspace to IDLE.

🧭 Next Steps ​