Claude Code hooks and the MCP server

You start a session from your phone and say which repos it needs. Two hooks give that session its own folder and take it away when it is done; four tools let the agent add repos itself while it works.

On this page

How the pieces fit #

Claude Code's Remote Control server can start each new session in a fresh git worktree. Out of the box that means one worktree of one repository. nucleate replaces that step with its own, so a session gets a folder in the nucleus that can hold several repos.

Piece When it runs What it does
WorktreeCreate hook A session starts Creates the session folder and tells Claude Code to start there.
MCP server During the session Gives the agent tools to list, add and remove repos.
WorktreeRemove hook A session is cleaned up Removes the session folder, unless it holds unsaved work.

All three are the nucleate binary, so creating, expanding and removing a session can never disagree about the rules.

Run the server in the nucleus #

Start the Remote Control server in the nucleus root itself, not inside a repo:

Boxas agent
cd ~/workspace
claude remote-control --spawn worktree

--spawn worktree is what makes Claude Code ask for a worktree per session, and so what makes it call the hooks.

Register the hooks #

The hooks go in the settings file of the folder the server runs in, which is the nucleus root:

Boxas agent/home/agent/workspace/.claude/settings.json
{
  "hooks": {
    "WorktreeCreate": [
      { "hooks": [{ "type": "command", "command": "nucleate hook-create", "timeout": 120 }] }
    ],
    "WorktreeRemove": [
      { "hooks": [{ "type": "command", "command": "nucleate hook-remove", "timeout": 120 }] }
    ]
  }
}

nucleate must be on the PATH of the server process, not only of your login shell. Both hooks find the nucleus the way every command does; because the server runs in the root, the .repos folder beside it is enough. The timeout is generous because adding repos fetches from the remote first.

What the create hook does #

Claude Code runs nucleate hook-create with the event as JSON on standard input. Two fields are read:

Field Used for
name The session's name, and so its folder and its branch workspace/<name>.
cwd Where the request came from. Decides between a new session and a sub-worktree.

The hook creates .worktrees/<name>/ and prints its path, alone on one line. Claude Code starts the session in the folder the hook printed. The session is empty: the agent adds what it needs with the tools below.

Start every session with a repo #

Repos named after hook-create are added to every new session before the agent starts:

Boxas agent/home/agent/workspace/.claude/settings.json
{
  "hooks": {
    "WorktreeCreate": [
      { "hooks": [{ "type": "command", "command": "nucleate hook-create web", "timeout": 120 }] }
    ]
  }
}

If a default repo cannot be added, no session folder is left behind and the hook fails with the reason.

What the remove hook does #

Claude Code runs nucleate hook-remove with one field that matters:

Field Used for
worktree_path The folder to remove.

If the path is a session, the hook does what nucleate remove-session does: all or nothing. It prints nothing. Exit status 0 means the folder is gone; exit status 1 means it was left alone, with the reason on standard error.

A session folder that is still there after its session ended is the hook saying no. See when a session will not go.

A worktree requested inside a session #

When the agent itself asks for a worktree, for a subagent that needs its own copy, the request's cwd is inside a session. The create hook then makes a sub-worktree of the repo at cwd, at .subworktrees/<name>-<repo> in the same session, and prints that path. The remove hook removes it under the same unsaved-work check.

Seed files #

Claude Code normally copies the files listed in a repo's .worktreeinclude into a new worktree. A custom WorktreeCreate hook replaces that behaviour, and a bare clone has no working files to copy from anyway. nucleate does the copy itself, from the nucleus's seed folder.

Register the MCP server #

Register the server for the user, not for a folder:

Boxas agent
claude mcp add --scope user nucleate -- nucleate mcp

A session's own folder is .worktrees/<session>/. Project-level MCP configuration in the nucleus root would not be found from there, so the registration has to follow the user. Check it took:

Boxas agent
claude mcp list

Claude Code starts nucleate mcp with the session folder as its working folder. The server works out which session it is serving from that folder on every call, so one registration serves every session.

The four tools #

Tool Arguments Returns
list_repos None The session's status: repos available to add and repos already in the session.
add_repo repo (required), branch What nucleate add prints.
remove_repo repo (required), force What nucleate remove prints.
workspace_status None The same status object as list_repos.

list_repos and workspace_status are two names for one answer. An agent reads it to decide what to add, and again to check what is unsaved before it finishes.

The arguments, as the server declares them:

Tool Argument Type Meaning
add_repo repo string A name like web or a label like your-org/web.
add_repo branch string Optional. Defaults to the session branch.
remove_repo repo string The repo to remove from this session.
remove_repo force boolean Optional. Remove even if the worktree holds unsaved work.

There is no tool to remove a session. An agent can drop a repo it added by mistake; taking the whole session away is the remove hook's job.

What the agent sees #

A tool's result is the command's JSON, as text:

Result of add_repo with repo: web
{
  "content": [
    {
      "type": "text",
      "text": "{\n  \"already_present\": false,\n  \"bare\": \"/home/agent/workspace/.repos/web.git\",\n  \"base\": \"15b80ae12bb3a17934cf98b293f75248c1b73e73\",\n  \"branch\": \"workspace/fix-login\",\n  \"label\": \"your-org/web\",\n  \"path\": \"/home/agent/workspace/.worktrees/fix-login/web\",\n  \"repo\": \"web\"\n}"
    }
  ],
  "isError": false
}

A failure is a result too, with isError set and the same message the command line prints, without the nucleate: prefix. The agent reads it and can act on it:

Result of add_repo with repo: docs
{
  "content": [
    {
      "type": "text",
      "text": "repo not available in /home/agent/workspace/.repos: docs"
    }
  ],
  "isError": true
}
Result of remove_repo on a repo with unsaved work
{
  "content": [
    {
      "type": "text",
      "text": "web: uncommitted changes"
    }
  ],
  "isError": true
}
Message Why
missing required argument: repo add_repo or remove_repo was called without repo.
unknown tool: ... The tool name is not one of the four.
not inside a workspace session under ... The server was started outside a session folder.

In practice #

You start a session from your phone and write: "Include web and the API. The login form rejects addresses with a plus sign." The agent calls list_repos, sees your-org/web and your-org/api, calls add_repo for each, and starts work in two worktrees on workspace/<session>. If it later needs a third repo, it adds it then. Approve the add_repo call the first time it asks.

Protocol details #

For anyone connecting something other than Claude Code:

  • The transport is standard input and output, one JSON-RPC 2.0 message per line.
  • The methods are initialize, ping, tools/list and tools/call. Any other method gets error -32601, method not found.
  • initialize answers with the protocol version the client asked for, or 2025-06-18 if it named none, and the server name nucleate with its version.
  • Messages without an id are notifications and get no reply.
  • The server exits when its input closes.