<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/guides/how-to/collaboration/worktrees-with-mcp-agents/">
  <id>https://docs.spec-kitty.ai/guides/how-to/collaboration/worktrees-with-mcp-agents/</id>
  <title>How to Keep MCP Agents in the Worktree</title>
  <updated>2026-06-12T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/guides/how-to/collaboration/worktrees-with-mcp-agents/"/>
  <summary>Keep MCP-backed editors and agents pointed at the active Spec Kitty worktree instead of the repository root.</summary>
  <content type="html">&lt;span id=&quot;how-to-keep-mcp-agents-in-the-worktree&quot;&gt;&lt;/span&gt;
&lt;p&gt;Use this guide when an MCP-backed editor or agent keeps opening the repository root instead of the active Spec Kitty worktree.&lt;/p&gt;
&lt;p&gt;This is a workspace configuration issue, not a Spec Kitty workflow bug. Spec Kitty creates the worktree for implementation, but the MCP server or editor still has to follow that new workspace root.&lt;/p&gt;
&lt;h2 id=&quot;what-goes-wrong&quot;&gt;What Goes Wrong&lt;/h2&gt;
&lt;p&gt;For code-change work packages, &lt;code dir=&quot;auto&quot;&gt;spec-kitty&lt;/code&gt; creates an execution worktree under &lt;code dir=&quot;auto&quot;&gt;.worktrees/&lt;/code&gt; and prints its path; your shell, editor, and MCP server must follow it.
If your MCP-backed editor keeps its own repository root, it can keep editing files in the main checkout while Spec Kitty thinks you are inside the worktree.&lt;/p&gt;
&lt;p&gt;That mismatch is the whole problem:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Spec Kitty is operating in the worktree&lt;/li&gt;
&lt;li&gt;the editor or MCP agent is still attached to the repository root&lt;/li&gt;
&lt;li&gt;edits land in the wrong place&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;recommended-pattern&quot;&gt;Recommended Pattern&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;Start implementation with &lt;code dir=&quot;auto&quot;&gt;spec-kitty agent action implement WP01 --agent &amp;#x3C;name&gt;&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Use the path printed by the command as the workspace root in your editor.&lt;/li&gt;
&lt;li&gt;Restart the MCP server or agent after switching into that worktree.&lt;/li&gt;
&lt;li&gt;Keep one editor session per worktree.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;If you are using tools such as Serena MCP or OpenCode, the same rule applies: open the worktree path as the workspace, not the repository root.&lt;/p&gt;
&lt;h2 id=&quot;if-the-agent-still-points-at-the-root&quot;&gt;If the Agent Still Points at the Root&lt;/h2&gt;
&lt;p&gt;If the agent keeps finding files in the root checkout:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Close the MCP-backed editor or agent session.&lt;/li&gt;
&lt;li&gt;Reopen it from inside the worktree directory.&lt;/li&gt;
&lt;li&gt;Confirm the shell and file tree now point at the worktree path.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;If that still does not stick, treat the current session as attached to the wrong root and start a fresh one in the worktree.&lt;/p&gt;
&lt;h2 id=&quot;good-habits&quot;&gt;Good Habits&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Do not keep the root checkout and the active worktree open in the same MCP session.&lt;/li&gt;
&lt;li&gt;Treat the printed worktree path as authoritative for implementation.&lt;/li&gt;
&lt;li&gt;Use a separate session for each active worktree.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;see-also&quot;&gt;See Also&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;/guides/how-to/missions/implement-work-package/&quot;&gt;Implement a work package&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/architecture/git-worktrees/&quot;&gt;Git Worktrees Explained&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/guides/how-to/collaboration/parallel-development/&quot;&gt;Parallel Development&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
