# Build the ledger and architecture model from an existing repository
nool init --from-git main
nool discover features
# Propose a change with declared intent; it is built and tested before it can land
nool propose --path src/invoice/rounding.ts --path src/invoice/index.ts --intent "Split invoice rounding into its own module"
nool solidify --compact
# Ask the history questions Git cannot answer
nool why <knot-id> --depth 3
nool log --fuzzy "rounding"
nool debug bisect --good <knot-id> --test "npm test -- invoice"
# Ingest a pull request branch through the semantic gate stack
nool merge feature/paddle-webhooksnool init onboards a Git repository without changing it. Git remains the storage layer; the ledger lives alongside it in .nool and mirrors back.
Git records bytes. Agents change meaning.
Git is a content-addressed store of file snapshots with a line-based merge on top. That model is exactly right for humans committing a few hundred lines a day with a message explaining themselves. It says nothing about what a change means: which entities it touched, which callers it affected, which invariant it preserved or broke, or why it was made. Coding agents produce far more change with far less explanation, and the questions a team then needs to answer are semantic ones. Did this refactor stay inside its scope? Do these two branches conflict in behaviour even though they merge in text? Which change introduced the regression, and what was it trying to do?
What a knot carries that a commit does not
Nool's unit of change is a knot on a directed acyclic graph. A knot carries the declared intent it was proposed under, the computed blast radius across the architecture model, the gate results and evidence attached before it was sealed, its causal parents, and a signature. Knots can be assertions of architectural judgment, attestations from checkers, findings and tasks as well as code changes, so the ledger holds the reasoning around the code rather than just the code. Proposals in --full mode are validated against the AST, which is how contract breaks are caught rather than merged. Git stays underneath as the storage and ecosystem layer: solidified knots mirror to Git, and Git history can be ingested into the DAG.
Commutative convergence instead of merge order
Nool is a semantic-agentic commutative version control system: changes that touch disjoint scopes converge in any order, and the system's job is to know precisely when two changes are not disjoint. Leases fence scope while work is in flight, blast radius exposes the reach of each change, and nool merge ingests an incoming Git branch, such as a pull request, into candidate knots, converges them and checks for semantic conflicts before running the gate stack. When two changes truly touch the same symbol, Nool serializes them and says so, rather than producing a merge that compiles and is wrong. In the coordination benchmark that showed up as fewer child processes and less stall than git worktrees on the bare path, with governance a statistical tie on throughput.
History you can query, replay and bisect
Because every knot records intent, the history answers questions Git cannot. nool why walks the causal chain of any knot with the intent of each ancestor. nool log with a fuzzy query finds the changes that were about a subject. nool debug replay steps through a Git ref or an agent run; nool debug bisect binary-searches knots between a known-good and a known-bad state with a test command; nool debug blame walks from a failure to its origin. nool changelog renders a semantic changelog, and nool compare shows what differs between threads or releases in terms of entities rather than lines.
Day one on an existing repository
Nothing about adopting Nool requires a migration. nool init with --from-git onboards the repository and its history; nool discover features maps the architecture into the entity graph the rest of the system reads. Daily work is propose and solidify, with try branches for anything experimental. Releases are checkpoints: nool checkpoint with a semver label marks a release on a release branch, nool doctor --strict checks readiness first, and nool changelog renders what changed in semantic terms. If two timelines diverge, nool status says so and nool pluck removes a thread from the active timeline while keeping its history. Git users will recognise every step; the difference is what each step records.
Frequently asked questions
- Do I have to stop using Git?
- No. Git stays as storage and as the ecosystem your tools expect. Nool adds a semantic ledger on top, mirrors solidified changes to Git, and can ingest Git branches into the DAG. Your remote, your CI and your pull requests keep working.
- What is a knot?
- The unit of change on Nool's DAG: a signed record carrying intent, blast radius, evidence and causal parents. Code changes are knots, and so are assertions, attestations, tasks and findings. The word is fixed product vocabulary, not a rename of commit.
- How is this different from a git forge with merge queues?
- A merge queue orders text merges. Nool decides whether two changes are semantically compatible before either lands, fences scope with leases while work is in flight, and validates against the AST in --full mode. The Cursor Origin comparison covers the difference in detail.
- Which languages are supported?
- nool languages lists the supported languages and their validation status on your installed version. Fast mode works on any repository; AST-aware --full validation depends on language support.
- How do releases work?
- nool checkpoint with an X.Y.Z label treats the current state as a release on a release branch. Run nool doctor --strict beforehand; it reports release-readiness and repository health, and nool doctor --fix repairs what it can. nool compare shows what differs between two releases in entities rather than lines.