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.
nucleateOn this page
The layout #
Everything nucleate manages lives under one root. On a box built with the recipe, the root is /home/agent/workspace.
/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:
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:
- If the branch already exists in the bare clone, the worktree checks it out.
- If the branch exists on the remote, the worktree tracks it. This is how an earlier session's pushed work is resumed.
- 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:
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.
{
"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:
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:
# 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:
# 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.
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.