nucleate
Two agents share a checkout and overwrite each other. A real task touches two or three repos. You tidy up by hand, and one day you delete the only copy of something. nucleate gives every session its own workspace and refuses to delete work that exists nowhere else.
nucleateOn this page
What it does #
nucleate is a command-line tool. It keeps one folder, the nucleus, with a bare clone of each repository you work on. Each agent session gets its own folder inside it and adds the repos it needs as git worktrees, all on one session branch.
When a session ends, its folder is removed. If anything in it is uncommitted, unpushed or otherwise stored nowhere else, nothing is touched. That is the safety rule, and it is the reason to use nucleate instead of a shell script.
It stands alone. There is no account, no daemon and no network service: nucleate needs git on the PATH and nothing else. It is built for Claude Code, with worktree hooks and an MCP server, but every command works by hand.
Install #
On a Linux box #
Release archives are published for two targets. Each archive holds two static binaries, nucleate and nucleated, and has a checksum file beside it.
| Machine | Target |
|---|---|
| x86_64 (most mini PCs) | x86_64-unknown-linux-musl |
| arm64 | aarch64-unknown-linux-musl |
Download the archive for your machine from the releases page, check it, and unpack the binaries somewhere on the PATH. As the user your agents run as:
cd /tmp
curl -fsSLO https://github.com/nucarium/nucarium-cli/releases/download/v0.3.0/nucleate-v0.3.0-x86_64-unknown-linux-musl.tar.gz
curl -fsSLO https://github.com/nucarium/nucarium-cli/releases/download/v0.3.0/nucleate-v0.3.0-x86_64-unknown-linux-musl.tar.gz.sha256
sha256sum -c nucleate-v0.3.0-x86_64-unknown-linux-musl.tar.gz.sha256
mkdir -p ~/.local/bin
tar -xzf nucleate-v0.3.0-x86_64-unknown-linux-musl.tar.gz -C ~/.local/bin nucleate nucleated
nucleate --version
nucleate 0.3.0
On a Mac, to try it #
brew install nucarium/tap/nucleate
From source #
With a Rust toolchain:
cargo install --git https://github.com/nucarium/nucarium-cli
Create a nucleus #
Pick the folder that will hold everything and run nucleate init in it. It creates the three folders nucleate uses and records the folder as the root in your config file, so every later command finds it from anywhere.
mkdir -p ~/workspace && cd ~/workspace
nucleate init
{
"config": "/home/agent/.config/nucleate/config.toml",
"created": true,
"root": "/home/agent/workspace"
}
Running it again changes nothing and prints "created": false.
Make a repository available #
A repo can be added to a session once its bare clone exists in the nucleus. nucleate clone makes that clone.
nucleate clone https://github.com/your-org/web.git
nucleate clone https://github.com/your-org/api.git
{
"bare": "/home/agent/workspace/.repos/web.git",
"label": "your-org/web",
"repo": "web"
}
nucleate runs git, so cloning a private repository uses whatever credentials git already has on this machine. nucleate available lists what can be added:
nucleate available
[
{
"bare": "/home/agent/workspace/.repos/api.git",
"label": "your-org/api",
"repo": "api"
},
{
"bare": "/home/agent/workspace/.repos/web.git",
"label": "your-org/web",
"repo": "web"
}
]
A first session #
This is what an agent session does through the hooks and tools. Doing it once by hand shows every moving part.
-
Create an empty session. It is a folder with a manifest and a note for the agent, and nothing else yet.
Boxas agent nucleate create-session fix-loginOutput { "path": "/home/agent/workspace/.worktrees/fix-login", "session": "fix-login" } -
Go into it and add a repo. The session is the folder you are in. The repo arrives as a worktree on the session's branch,
workspace/fix-login, started from the tip of the repo's default branch.Boxas agent cd ~/workspace/.worktrees/fix-login nucleate add webOutput { "already_present": false, "bare": "/home/agent/workspace/.repos/web.git", "base": "15b80ae12bb3a17934cf98b293f75248c1b73e73", "branch": "workspace/fix-login", "label": "your-org/web", "path": "/home/agent/workspace/.worktrees/fix-login/web", "repo": "web" } -
Do some work in
web/, then ask what is unsaved.Boxas agent echo "scratch" > web/notes.txt nucleate statusThe part of the answer that matters:
Output, the web entry { "branch": "workspace/fix-login", "dirty": true, "head": "15b80ae", "unsafe_reasons": [ "uncommitted changes" ] } -
Try to remove the session.
nucleaterefuses, prints why on standard error, exits 1 and leaves every file where it was.Boxas agent nucleate remove-sessionOutput nucleate: refusing to remove session with unsaved work: web: uncommitted changes -
Deal with the work: commit it and push the branch, or delete the scratch file. Then removal goes through, and the folder and its local branch are gone.
Boxas agent rm web/notes.txt nucleate remove-sessionOutput { "removed_session": "/home/agent/workspace/.worktrees/fix-login" }
Where to go next #
- The nucleus: the folder layout, the manifest, and seed files such as an
.env. - Commands: every command, its output and its errors.
- The safety rule: exactly what counts as unsaved, and how to rescue a session that will not go.
- Claude Code hooks and the MCP server: let sessions create, expand and remove their own workspaces.
- Configuration: the root, the branch prefix and the GitHub token.
To hear when one of those sessions stops and waits for you, add nucleated and Watch.