The nucleus

The nucleus is one folder on the box. Bare clones live in it once and are shared; every session gets its own folder of worktrees. This page is what is in that folder and why it is shaped that way.

On this page

The layout #

Everything nucleate manages lives under one root. On a box built with the recipe, the root is /home/agent/workspace.

The nucleus
/home/agent/workspace/
  .repos/
    web.git/               # a bare clone; "web" is available because this exists
    api.git/
  .worktrees/
    fix-login/             # one folder per session
      .workspace.json      # the session's manifest
      AGENTS.md            # a note for the agent, listing the session's repos
      web/                 # a linked worktree on branch workspace/fix-login
      api/
      .subworktrees/       # extra worktrees an agent asked for mid-session
  .seeds/
    web/                   # untracked files to copy into new worktrees of web

nucleate init creates .repos/, .worktrees/ and .seeds/. Nothing else in the root is touched, so you can keep your own files there: an AGENTS.md for every session to read, or the .claude/settings.json that registers the hooks.

Bare clones #

A repo is available when its bare clone exists at .repos/<repo>.git. There is no list to maintain: the directory listing is the list, and nucleate available prints it.

nucleate clone <url> makes a clone the way sessions need it. Done by hand, it is four git commands:

Boxas agent
git clone --bare https://github.com/your-org/web.git ~/workspace/.repos/web.git
git --git-dir="$HOME/workspace/.repos/web.git" config remote.origin.fetch '+refs/heads/*:refs/remotes/origin/*'
git --git-dir="$HOME/workspace/.repos/web.git" fetch origin
git --git-dir="$HOME/workspace/.repos/web.git" remote set-head origin --auto

The second line is the one that matters. A plain bare clone fetches straight into its own branches. With several sessions holding worktrees of the same clone, a fetch would then try to rewrite a branch that a session has checked out. Remote-tracking refs (refs/remotes/origin/*) keep what the remote has apart from what sessions are working on, so fetching is always safe. The last line records the remote's default branch, which is where new session branches start.

One clone serves every session. A second session that adds web gets a second worktree of the same clone, in seconds, without downloading anything twice.

Names and labels #

Each available repo has two names.

Name Where it comes from Example
repo The clone's folder name, without .git web
label The owner and name from the clone's GitHub remote URL your-org/web

If the remote is not on GitHub, the label is the same as the repo name. Every command and tool that takes a repo accepts either form.

Sessions #

A session is a folder at .worktrees/<session>/. It starts with a manifest and a note and no repos. Each repo added to it becomes a subfolder that is a real, independent git worktree.

All of a session's worktrees are on one session branch, named <branch_prefix>/<session>. The prefix is workspace unless you change it, so the session fix-login works on workspace/fix-login in every repo it touches. A pull request per repo, all with the same branch name, is easy to find again.

When a repo is added, nucleate fetches first and then picks the starting point:

  1. If the branch already exists in the bare clone, the worktree checks it out.
  2. If the branch exists on the remote, the worktree tracks it. This is how an earlier session's pushed work is resumed.
  3. Otherwise the branch is created from the tip of the remote's default branch.

nucleate add web some-branch puts that one repo on a branch you name instead of the session branch, by the same three steps.

Name rules #

Thing Rule
Session and repo names Start with a letter or digit, then letters, digits, ., _ and -. No /, no spaces.
Branch names The same, plus /. No .., and no / at the end.

Anything else is refused before git is run:

Output
nucleate: invalid session name: "bad name"

The manifest #

.workspace.json is the session's own record of what it holds. nucleate writes it; you read it.

.workspace.json
{
  "name": "fix-login",
  "branch": "workspace/fix-login",
  "repos": {
    "web": {
      "label": "your-org/web",
      "bare": "/home/agent/workspace/.repos/web.git",
      "path": "/home/agent/workspace/.worktrees/fix-login/web",
      "branch": "workspace/fix-login",
      "base": "15b80ae12bb3a17934cf98b293f75248c1b73e73"
    }
  }
}
Field Meaning
name The session's name, which is also its folder name.
branch The session branch.
repos One entry per repo in the session, keyed by repo name.
repos.*.label The repo's label when it was added.
repos.*.bare The bare clone the worktree belongs to.
repos.*.path The worktree's folder.
repos.*.branch The branch this repo is on. It differs from the session branch only if the repo was added on a named branch.
repos.*.base The commit the worktree started at.

A folder under .worktrees/ with no manifest is not a session, and every command says so:

Output
nucleate: not a workspace session (no .workspace.json): /home/agent/workspace/.worktrees/scratch

AGENTS.md #

Each session folder also gets an AGENTS.md, rewritten whenever a repo is added or removed. An agent that starts in the session folder reads it and knows what it has to work with:

AGENTS.md
# Workspace session

Each subdirectory is an independent git worktree on branch `workspace/fix-login`. Work only inside them; never edit the bare repos under `../../.repos/`. Use the nucleate MCP tools (`list_repos`, `add_repo`) to expand this session.

- `api/` — your-org/api on `workspace/fix-login`
- `web/` — your-org/web on `workspace/fix-login`

Sub-worktrees #

An agent working inside a session can ask for another worktree, for a subagent that needs its own copy of a repo, say. With the hooks registered, that request lands in the session's own .subworktrees/ folder, as <name>-<repo> on a new branch <branch_prefix>/<name>, started from the clone's default branch. It never leaks outside the session.

Seed files #

A fresh worktree has only what is committed. Files a repo needs but does not commit, an .env for instance, have to come from somewhere, and a bare clone has no working files to copy from.

So nucleate copies them from .seeds/<repo>/, which only you populate. What is copied is decided by the repo itself, in its committed .worktreeinclude file:

web/.worktreeinclude
# Files every worktree of this repo needs, but that are not committed.
.env
config/local/*.json

Each line is a pattern, matched against the files in .seeds/web/. Whatever matches is copied to the same relative path in the new worktree. Folders are copied whole and symbolic links stay links.

Boxas agent
mkdir -p ~/workspace/.seeds/web
cp ~/web.env ~/workspace/.seeds/web/.env
chmod 600 ~/workspace/.seeds/web/.env

The rules are deliberately narrow:

  • A file in .seeds/web/ that no pattern names is not copied.
  • A pattern that starts with / or contains .. is skipped, so a repo cannot ask for files outside its own seed folder.
  • Blank lines and lines starting with # are skipped.
  • No .worktreeinclude, or no seed folder, means no copy and no error.