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.
nucleateOn 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:
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:
{
"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:
{
"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:
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:
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:
{
"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:
{
"content": [
{
"type": "text",
"text": "repo not available in /home/agent/workspace/.repos: docs"
}
],
"isError": true
}
{
"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/listandtools/call. Any other method gets error-32601,method not found. initializeanswers with the protocol version the client asked for, or2025-06-18if it named none, and the server namenucleatewith its version.- Messages without an
idare notifications and get no reply. - The server exits when its input closes.