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.

On 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:

Boxas agent
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
Boxas agent
mkdir -p ~/.local/bin
tar -xzf nucleate-v0.3.0-x86_64-unknown-linux-musl.tar.gz -C ~/.local/bin nucleate nucleated
nucleate --version
Output
nucleate 0.3.0

On a Mac, to try it #

Workstation
brew install nucarium/tap/nucleate

From source #

With a Rust toolchain:

Workstation
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.

Boxas agent
mkdir -p ~/workspace && cd ~/workspace
nucleate init
Output
{
  "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.

Boxas agent
nucleate clone https://github.com/your-org/web.git
nucleate clone https://github.com/your-org/api.git
Output of the first command
{
  "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:

Boxas agent
nucleate available
Output
[
  {
    "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.

  1. 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-login
    
    Output
    {
      "path": "/home/agent/workspace/.worktrees/fix-login",
      "session": "fix-login"
    }
    
  2. 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 web
    
    Output
    {
      "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"
    }
    
  3. Do some work in web/, then ask what is unsaved.

    Boxas agent
    echo "scratch" > web/notes.txt
    nucleate status
    

    The part of the answer that matters:

    Output, the web entry
    {
      "branch": "workspace/fix-login",
      "dirty": true,
      "head": "15b80ae",
      "unsafe_reasons": [
        "uncommitted changes"
      ]
    }
    
  4. Try to remove the session. nucleate refuses, prints why on standard error, exits 1 and leaves every file where it was.

    Boxas agent
    nucleate remove-session
    
    Output
    nucleate: refusing to remove session with unsaved work: web: uncommitted changes
    
  5. 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-session
    
    Output
    {
      "removed_session": "/home/agent/workspace/.worktrees/fix-login"
    }
    

Where to go next #

To hear when one of those sessions stops and waits for you, add nucleated and Watch.