🗺️ ThreadMap MCP for Claude

Conversation drift visualization and forking for Claude.

Stop losing your original intent. See exactly where your conversation drifted. Fork from any point and pick up with clean context.

The Problem

You start a Claude session: "Build me a login system."

Three hours later you're deep in a JWT refresh token bug, the original architecture is buried under 80 messages, and Claude has completely lost track of what you were building. You've wasted tokens, lost context, and have to start over.

ThreadMap MCP for Claude fixes this.

How It Works

ThreadMap MCP for Claude tracks every message and assigns it a color based on semantic drift from your original intent:

| Color | Drift | Meaning | |-------|-------|---------| | 🔵 Blue | 0–15% | On track — core intent | | 🟢 Green | 16–35% | Productive expansion | | 🟡 Yellow | 36–55% | Adjacent drift — related but expanding | | 🟠 Orange | 56–72% | Inflection point — meaningful pivot | | 🔴 Red | 73–88% | Full context break — different territory | | 🟣 Purple | 89–95% | Meta — talking about the conversation | | ⚪ White | 96–100% | Resolution — conclusion reached |

When you hit Orange or Red, ThreadMap flags it as an inflection point. You can fork the conversation right there — creating a clean branch with only the context up to that moment. Claude in that branch doesn't know about the drift. Fresh start, without losing history.

Install

Claude Code (one line)

claude mcp add threadmap npx threadmap-mcp

Manual (any MCP client)

npm install -g threadmap-mcp

Add to your MCP config (~/.claude/claude_desktop_config.json or similar):

{
  "mcpServers": {
    "threadmap": {
      "command": "threadmap-mcp"
    }
  }
}

Quick Start

1. Track messages as you go

threadmap_track(
  sessionId="myproject",
  role="user",
  content="build me a login system with JWT auth"
)

Response:

🔵 Blue — Drift: 0%
Topic: build me a login system with JWT auth
Message #1 tracked.

A few messages later...

threadmap_track(
  sessionId="myproject",
  role="user",
  content="the refresh token keeps expiring after 30 seconds, lets debug this"
)

Response:

🟠 Orange — Drift: 63%
Topic: the refresh token keeps expiring after 30 seconds
⚡ INFLECTION POINT — significant topic shift detected. Consider forking here.
Message #8 tracked.

2. See your full timeline

threadmap_timeline(sessionId="myproject")

Response:

📍 ThreadMap Timeline — Session: myproject
🎯 Origin Intent: build me a login system with JWT auth

Messages (8 total):

1. 🔵 Blue   [0%]  USER: build me a login system with JWT auth
2. 🟢 Green  [18%] Claude: here's the auth architecture with JWT...
3. 🔵 Blue   [12%] USER: add refresh token support
4. 🟢 Green  [24%] Claude: here's the refresh token implementation...
5. 🟡 Yellow [38%] USER: the expiry time seems off
6. 🟡 Yellow [41%] Claude: let me check the token configuration...
7. 🟠 Orange [63%] USER: refresh token keeps expiring after 30s ← INFLECTION POINT
8. 🔴 Red    [71%] Claude: let's debug the token lifecycle...

⚡ Inflection Points:
1. 🟠 Orange at message #7: Topic shifted: refresh token expiry debug
   → Fork: call threadmap_fork with messageIndex: 6

3. Fork from an inflection point

threadmap_fork(
  sessionId="myproject",
  messageIndex=6,
  branchName="jwt-debug"
)

Response:

🌿 Branch Created: "jwt-debug"
Branch ID: branch_1712345678
Forked at: Message #7 — refresh token keeps expiring
Context: 7 messages carried forward
Origin preserved: build me a login system with JWT auth

Resume with: threadmap_branch_context branchId: branch_1712345678

Now you have a clean branch with only the auth architecture context — no rabbit holes, no off-topic debugging contaminating Claude's context.

4. Resume from the branch

threadmap_branch_context(
  sessionId="myproject",
  branchId="branch_1712345678"
)

Response:

🌿 Branch Context: "jwt-debug"
Original Intent: build me a login system with JWT auth
Fork Point: Message #7
Messages in branch: 7

Recent context (last 5):
USER: add refresh token support
Claude: here's the refresh token implementation...
USER: the expiry time seems off
Claude: let me check the token configuration...
USER: refresh token keeps expiring after 30 seconds

Use this to anchor a clean focused session — without the drift.

All Tools

threadmap_track

Track a message and get its drift score.

| Parameter | Type | Description | |-----------|------|-------------| | sessionId | string | Unique ID for this conversation/project | | role | "user" | "assistant" | Who sent the message | | content | string | The message text |

Returns: color, drift %, topic summary, inflection point alert if triggered.

threadmap_timeline

Show the full color-coded conversation map with all drift scores, inflection points, and branch markers.

| Parameter | Type | Description | |-----------|------|-------------| | sessionId | string | Session to display |

threadmap_fork

Fork from any message index with clean context.

| Parameter | Type | Description | |-----------|------|-------------| | sessionId | string | Session to fork from | | messageIndex | number | 0-based index of the fork point | | branchName | string | Name for the branch (e.g. "auth-restart", "back-to-origin") |

Returns: branch ID, fork point summary, context size.

threadmap_branch_context

Get the context packet for a branch to resume cleanly.

| Parameter | Type | Description | |-----------|------|-------------| | sessionId | string | Session ID | | branchId | string | Branch ID from threadmap_fork |

Returns: original intent, fork point, recent messages — everything needed to anchor a new Claude session.

threadmap_status

Quick current drift check without loading the full timeline.

| Parameter | Type | Description | |-----------|------|-------------| | sessionId | string | Session to check |

Returns: current color, drift %, message count, warning if drift is high.

threadmap_reset

Archive current thread and start fresh with a new origin.

| Parameter | Type | Description | |-----------|------|-------------| | sessionId | string | Session to reset | | newOriginContent | string | New starting message to set as origin |

Old thread is archived as a branch. Fresh tracking begins.

threadmap_legend

Show the color reference guide — useful to paste into any Claude session.

Real-World Use Cases

Claude Code — Architecture Integrity

You're building a feature with Claude Code. Start the session, track every message. When you see Orange, scope is creeping. Fork before the drift gets worse. The architecture decisions from the first 10 messages stay clean and uncontaminated.

Session: "build a user dashboard with real-time updates"
Message 1-5:   🔵🟢🟢🔵🟢   (core architecture — on track)
Message 6-8:   🟡🟡🟠         (WebSocket config tangent) ← fork here
Message 9-15:  🔴🔴🟣🔴       (deep debugging rabbit hole)

Fork at message 6. Tackle the WebSocket issue in a clean separate branch. Main architecture stays untouched.

Long Research Sessions — Stay on Topic

Long Claude research conversations drift naturally. ThreadMap shows you exactly when you left the original question. Jump back to the moment before the drift with one fork.

Brainstorming — Preserve the Original Spark

You have an idea, the conversation gets messy exploring it, and the original insight gets buried. ThreadMap keeps a pointer to the first moment of clarity — fork back to it anytime.

Team Handoffs — Clean Context Packets

Use threadmap_branch_context to extract a clean summary of exactly what was decided up to any point. Drop it into a new Claude session. No scrolling through 200 messages to find the relevant decisions.

Architecture

• Zero external API calls — drift scoring runs locally using keyword-based semantic comparison
• No database required — in-memory session state, zero setup
• Stateless across restarts — sessions reset cleanly, lightweight by design
• Works with Claude Code natively via MCP protocol
• Future-ready — designed to support local embedding models (MiniLM) for richer semantic drift scoring

Why Open Source?

This should be a protocol, not a product.

Like Markdown defined how people write on the internet. Like Git defined how code is versioned.

Non-linear conversation navigation is the missing primitive for AI-native work.

Right now Claude conversations are books with no table of contents, no chapters, no bookmarks. You just scroll. Nobody would accept that from a book. We accept it from AI because we don't know better yet.

ThreadMap MCP for Claude is the table of contents. The chapter marker. The ability to fork — and pick up from any margin at will.

If this becomes the standard, it travels across Claude, GPT, Gemini, anything. Nobody owns it. Everybody benefits.

Roadmap

• [ ] Local embedding model support (MiniLM) for richer semantic scoring
• [ ] Visual timeline export (SVG/HTML mini-map)
• [ ] Cross-session branch persistence (optional SQLite mode)
• [ ] Shared learning layer — anonymous correction signals improve scoring across users
• [ ] Native Claude.ai extension when Anthropic opens the plugin API
• [ ] GPT / Gemini compatibility

Contributing

MIT licensed. Fork it, extend it, publish it.

git clone https://github.com/Advertflair/threadmap-mcp
cd threadmap-mcp
npm install
npm run build
npm run dev   # runs locally for testing

Issues and PRs welcome. Especially interested in:

• Better drift scoring algorithms
• More granular color thresholds
• Integrations with other AI platforms

License

MIT — see LICENSE

Built by Advertflair. Open source. Ship it. See what happens.