Migration guide

Add Nool to the repository you already have.

Nool runs on top of Git, in the repository where your code already lives. It imports your history as it is, your agents land their changes through it, and what reaches your forge is still ordinary commits. Nothing is moved or rewritten.

Talk to usTry Community free

Before you start

What Nool adds to your repository, and what it leaves alone.

Left alone

  • — Your commit history. Existing commits keep their hashes.
  • — Your forge, pull requests and code review.
  • — CI and how you deploy.
  • — Your coding agents: Claude Code, Codex or opencode.

Added

  • — A .nool folder for Nool's records. Most of it stays on your machine, ignored by Git.
  • — nool.toml and .noolignore, plus entries in .gitignore and .gitattributes, committed like any other change.
  • — Hooks for coding agents: Claude Code, Codex, Gemini, opencode and Pi.
  • — A few lines in each new commit message that name the change's record and say whether it was validated.

The steps

From a Git repository to a first landed change.

  1. Install the CLI

    One line on macOS or Linux; the setup page has the PowerShell line for Windows. Community is free, with no email and no card.

    curl -fsSL "https://www.nool.dev/nool-install.sh" | bash

  2. Run nool init

    At the root of the repository, on the branch you work from. Nool imports that branch's history, writes its configuration files and sets up hooks for your coding agents. Existing commits are not rewritten.

    nool init

  3. Put the guard on your agents

    In Claude Code and Codex CLI, an agent that tries to commit, merge or push with raw Git is refused and told which Nool command to use. For Cursor, Gemini, Windsurf or opencode, nool hooks mcp registers Nool's tools with the agent.

    nool hooks install

  4. Land a change

    You or your agent name the files and say why. Nool builds the change and runs the tests it affects in an isolated copy, holds it to your rules, and lands it as one commit with the reason as its message.

    nool propose --path <file> --intent "<why>" --solidify

  5. Push to your forge

    The branch goes up as an ordinary push, so pull requests and CI run as before. Nool's records travel beside it under refs/nool.

    nool push origin

On install, Nool coordinates agents, builds and tests each change, and records it. It enforces none of your own rules until you add them: nool init --governed starts a repository with one rule that blocks credentials and private keys. How to write a rule

A real run

The history you had is the history you keep.

We ran these steps on a clone of github.com/octocat/Spoon-Knife. The three marked commits are the repository's own, with the hashes they have on GitHub. Above them are the two commits nool init made for its configuration files, then the first change landed through Nool.

nool 7.24.0, 5 November 2026

The repository's own commits, unchanged
~/Spoon-Knife $ nool init 
Imported 3 Git commits without rewriting history.
Created nool.toml, .noolignore and agent hooks.
~/Spoon-Knife $ nool propose --path README.md --intent "Add migration note" --solidify
✓ Validated and landed change 39d2859c
~/Spoon-Knife $ git log --oneline -6
39d2859 Add migration note
6e854e1 Initialize Nool agent hooks
1d1e562 Initialize Nool repository
d0dd1f6 Merge pull request #3 from octocat/test
bb4cc8d Create styles.css and updated README
a30c19e Initial commit

The rest of the team

Not everyone has to switch on the same day.

  • The next engineer

    They clone the repository as usual, run nool init in the clone and pull. The record of every change landed so far comes down with the branch.

    nool init && nool pull origin

  • A teammate still on plain Git

    Their branch merges in through Nool. Each commit made without Nool is named as it comes in, so nothing enters the history unnoticed.

    nool pull origin --branch <name>

  • Pull requests merged on the forge

    Merge with any button: squash, rebase or merge commit. The next pull finds the changes those commits carry and records them as merged, without landing anything twice.

    nool pull origin

Leaving

If you stop, you still have a Git repository.

Every change that landed through Nool is an ordinary commit on your branch, so there is nothing to convert back. Remove the agent guard, delete the .nool folder, nool.toml and .noolignore, commit that, and carry on with Git.

nool hooks uninstall

Questions

What teams ask before they start.

Does Nool replace GitHub or GitLab?
No. Nool pushes ordinary Git commits to the forge you use today, so pull requests, code owners and CI keep working.
Does CI have to change?
No. CI receives the same branch and the same kind of commit as before. Nool's build and tests run before a change lands, on the machine where it was made; CI still runs after the push.
Can engineers still use Git directly?
For reading, yes: git log, git diff and git blame work as before. To change history, people and agents go through Nool, so each change gets its checks and its record. A commit a teammate made with plain Git is named when Nool pulls it in, and nool bridge adopt brings it into the record.
Does it work with Git LFS?
Yes. nool bridge lfs init sets up Git LFS in the repository, and nool bridge lfs track adds a file pattern such as *.psd.

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

Start with one repository.

Have one engineer run it on a real repository first, or talk to us about a rollout for your team.

Talk to usTry Community free