smart-fork

Smart Fork is an MCP server for Claude Code that maintains a searchable vector index of your past Claude Code sessions and enables smart session forking. It exposes a fork-detect tool that Claude Code can invoke to semantically search your session history and surface the most relevant previous conversations to resume work with full context. With this server running, you can describe your task in Claude Code and rely on the system to locate and fork from the most relevant prior session, helping you overcome context limits and accelerate re-use of prior work.

During use, you’ll interact with the fork-detect capability through Claude Code. The tool performs semantic search across your session history, returns a curated list of top matches, and enables you to fork from one of those sessions. You can then copy the generated command and run it locally to continue from that session with preserved context. The server also supports features like background indexing, project-scoped search, and fork history tracking to streamline your workflow.

Prerequisites:

• Python 3.10 or higher
• Claude Code with MCP support
• Virtual environment support (recommended)
• Git for cloning the repository

Install from Source:

1. Clone the repository:

git clone https://github.com/recursive-vibe/smart-fork.git
cd smart-fork

2. Create and activate a virtual environment:

python -m venv venv
# macOS/Linux
source venv/bin/activate
# Windows
venv\Scripts\activate

3. Install in editable mode:

pip install -e .

4. Verify installation (optional):

python -c "import smart_fork; print(smart_fork.__version__)"

5. Configure Claude Code MCP:

• Edit your Claude Code MCP configuration file (e.g., ~/.claude/mcp_servers.json) to add the Smart Fork server with the appropriate command and environment. Example provided in the project README:

{
  "mcpServers": {
    "smart-fork": {
      "command": "/path/to/smart-fork/venv/bin/python",
      "args": ["-m", "smart_fork.server"],
      "cwd": "/path/to/smart-fork/src",
      "env": {
        "PYTHONPATH": "/path/to/smart-fork/src"
      }
    }
  }
}

6. Restart Claude Code (or reload the MCP configuration) to load the MCP server.

Tips and notes:

• The server relies on a vector database for indexing sessions; ensure you have enough RAM for indexing large session histories.
• If you’re running from source, keep the virtual environment activated when starting Claude Code so the MCP server is available.
• Environment variables such as PYTHONPATH may need to be adjusted to point to your local source tree (replace /path/to/smart-fork with your actual path).
• The initial indexing may take time depending on the number of existing sessions. Use the recommended batch-mode option for large datasets if provided by the tool.
• If you encounter timeouts processing large sessions, consider adjusting timeout handling in your configuration (not shown in this README) and ensure sessions with parseable messages are prioritized.
• The MCP tooling is designed to work with Claude Code and VS Code integration (beta); you can also use the provided CLI tool to perform manual searches and forks.