Architecture

How Nool sits between your agents and Git.

Nool is a command-line tool with a ledger that lives beside your repository. Agents propose changes to it, it checks each one, and what passes becomes an ordinary Git commit. This page covers the parts, what each one stores and where it runs.

Talk to us Try Community free

Where it sits

On the machine where the agent works, in front of Git.

There is no server to deploy. The nool command runs wherever an agent works, on a laptop or a build machine. It keeps its ledger in a .nool folder beside your code and writes to the Git repository you already have.

Your agents

Claude Code · Codex · opencode · nool code

nool announce intent · nool propose

Nool

On the same machine

Leases
Who may edit what, right now
Checks
Build, tests and your rules
Ledger
A signed record of each landed change
Memory
Findings the next session starts with

nool solidifyOne Git commit for each landed change

Git

Your branches, your forge, your CI/CD. Unchanged.

The path of a change

Four steps, each one a command.

Announce
The agent names the files it will change and gets a lease with a sequence number. A second agent asking for the same files is refused, and waits or takes other work.
nool announce intent
Propose
Nool takes the last landed state plus the changed files into a private worktree, builds it and runs the tests the change affects. It then alters a few changed lines to see whether the tests notice, and runs your rules. A failed build, test or rule refuses the change and names the cause.
nool propose
Solidify
Nool confirms the lease is still the current one, signs the change, appends it to the ledger and writes one Git commit.
nool solidify
Push
The commit goes to your forge as ordinary Git. The signed check results travel beside it on their own refs, never as commits on your branch.
nool push origin

Fast mode defers validation and is an explicit opt-in. Full validation is the default.

What is stored

Everything Nool records is in your repository or beside it.

What	Where it lives	How it travels
The ledger: every landed change, signed, with its intent and its parents	Beside your code`.nool/knots.redb`	Stays on the machine. Another machine rebuilds it from the Git history it pulls.
One Git commit for each landed change	On your branch`refs/heads/<branch>`	Pushed to your forge like any commit. Its trailers carry the change's id, intent and parents.
Check results: signed verdicts from builds, tests, scans and reviews	In Git refs, off your branch`refs/nool/detached/<writer>`	Pushed and fetched with the repository. They never appear as commits on your branch.
Leases	On the machine by default`refs/nool/claims/*`	Shared across machines as Git refs, or through an optional hub.
Your rules	Versioned with your code`policies/ · nool.toml`	With every clone. A configuration change lands on its own, with a written reason.
Findings: the decisions and root causes people and agents record	In the ledger, as signed entries`nool learn`	Shared with the team by default. A finding marked private is never pushed.

One landed change, as Git sees it

An ordinary commit. Its trailers carry the change's id, its intent, its parents, the validation result and the hash of the rule set it was checked against.

nool 7.24.0, fresh repository

git log

$ git log -1 --format=%BRaise the team quota to 60,000 Nool-Knot-ID: 39d2859c9082735f2bb4648f47b2237169d0b60761be927e931c2af1d2d3411bNool-Intent: Raise the team quota to 60,000Nool-Thread: mainNool-Parents: ce8fa096510d840d14f3c079980644060a027193850154f5d3c10a2b65a47911Nool-Validation: validatedNool-Policy-Version: 1Nool-Policy-Hash: 2e8b563ff1a0f6d478257fc6a82b13ac853a3787b40d0cc00df2893e7522a5c1

Code and evidence stay on your machines or in your VPC. The CLI contacts nool.dev only for licence and device activation. Security and data

Checks and rules

Every change passes the same gates.

None of these gates asks a model for an opinion, and your rules give the same change the same verdict every time. A model's judgment can be added on top and can hand the decision to a person. It never replaces a rule.

Syntax
precheck
The changed files are parsed first, and a file that does not parse stops here. Parsers for the common languages are built in; others load as WebAssembly plugins.
Build and tests
integrity
The last landed state plus this change is built in a private worktree and the affected tests run there, so another agent's unfinished edits cannot change the result.
Mutation check
tests_constrain_change
A few changed lines are altered on purpose and the tests run again. The record says whether they caught every alteration.
Blast radius
blast
The code that depends on the change is listed and compared with what the agent declared. A change that reaches much further needs a written justification.
Your rules
policy:<id>
Configurable rules in YAML and hard rules compiled to WebAssembly. Hard rules run in a sandbox with a compute limit and a memory limit, and each commit records the hash of the rule set it was checked against.
Lease
lease
Just before a change is signed, Nool checks that the agent's lease is still the current one. An expired or replaced lease is refused, even if it was valid when the work began.
Human approval
nool approve
Paths you name wait for a person's sign-off before the change lands.

Keys and signatures

Every record is signed. A clone is enough to check it.

A key for each machine
Each machine that lands changes holds its own Ed25519 key, and every change it lands is signed with it.
Role grants from your issuer
Who may land, approve or release is a grant signed by your issuer, with sign-in through your identity provider. Until you configure an issuer, grants are not enforced.
CI signs its own verdicts
A CI job records its result as a signed attestation under its own key. You list the checker keys you trust.
Verification from Git alone
nool audit verify recomputes the controls over any range of changes from Git history. A fresh clone gives the same answer.

At the edges

What happens outside Nool.

A commit made with plain Git: It is still a valid commit, but it carries no signed record. nool bridge adopt brings it into the ledger marked as foreign, so it is visible instead of hidden.
An agent that reaches for Git: The agent guard blocks Git commands that write history inside the agent's session and names the Nool command to use instead. Blocking is in place for Claude Code today.
A pull request merged on your forge: Squash, rebase or merge commit: nool pull finds the changes those commits carry and records them as merged. Nothing lands twice.
If you stop using Nool: Your history is ordinary Git commits on your own branches and forge. There is nothing to convert back.

Check it against your own repository.

Talk to us about a rollout for your team, or have one engineer try Community first.

Talk to us Try Community free

How Nool sits between your agents and Git.

On the machine where the agent works, in front of Git.

Four steps, each one a command.

Announce

Propose

Solidify

Push

Everything Nool records is in your repository or beside it.

One landed change, as Git sees it

Every change passes the same gates.

Syntax

Build and tests

Mutation check

Blast radius

Your rules

Lease

Human approval

Every record is signed. A clone is enough to check it.

A key for each machine

Role grants from your issuer

CI signs its own verdicts

Verification from Git alone

What happens outside Nool.

Check it against your own repository.