Thread Mind

npm version License: MIT

Organize your AI conversations into thread trees. Think less tokens, think more.

ThreadMind is a Model Context Protocol (MCP) server that structures AI conversations into hierarchical threads. Instead of feeding entire conversation histories to your AI model, ThreadMind lets you maintain concise summaries organized in a tree — drastically reducing token consumption while preserving full context.

Documentation | npm | GitHub

---

Why ThreadMind?

When working with AI coding assistants (Claude Code, ChatGPT, Gemini, etc.), conversations quickly grow long. Every new message sends the entire history as context, burning through tokens and hitting context limits. ThreadMind solves this by:

• Replacing history with summaries — each thread stores a concise summary instead of raw conversation
• Inheriting context through the tree — a child thread automatically includes its ancestors' summaries
• Enabling branching exploration — explore different approaches in separate threads without polluting each other
• Supporting team collaboration — share thread trees via git, branch from teammates' threads

Before ThreadMind

Message 1 → Message 2 → ... → Message 50 → Message 51
                                              ↑
                              All 50 messages sent as context
                              = thousands of tokens wasted

With ThreadMind

main (summary: 200 tokens)
├── auth (summary: 150 tokens)
│   └── auth-ui (summary: 100 tokens) ← active
└── dashboard (summary: 180 tokens)

Context sent = main + auth + auth-ui = ~450 tokens

---

Quick Start

Installation

No installation required — run directly with npx:

npx thread-mind-mcp

Or install globally:

npm install -g thread-mind-mcp

Configure with Claude Code

Add to your Claude Code MCP settings (~/.claude/settings.json or project .claude/settings.json):

macOS / Linux:

{
  "mcpServers": {
    "thread-mind": {
      "command": "npx",
      "args": ["-y", "thread-mind-mcp"]
    }
  }
}

Windows:

{
  "mcpServers": {
    "thread-mind": {
      "type": "stdio",
      "command": "cmd",
      "args": ["/c", "npx", "thread-mind-mcp"],
      "env": {}
    }
  }
}

On Windows, npx must be wrapped with cmd /c because npx is a .cmd wrapper and cannot be spawned directly by the MCP stdio transport.

Windows + Volta:

If you use Volta as your Node.js version manager, use volta run to ensure the correct Node.js version is resolved when Claude Code spawns the MCP subprocess:

{
  "mcpServers": {
    "thread-mind": {
      "type": "stdio",
      "command": "cmd",
      "args": ["/c", "volta", "run", "npx", "-y", "thread-mind-mcp"],
      "env": {}
    }
  }
}

Or via CLI: claude mcp add thread-mind-mcp --scope project -- cmd /c volta run npx -y thread-mind-mcp

Configure with other MCP clients

ThreadMind uses the stdio transport, compatible with any MCP client. Use the same configuration above for your platform.

---

How It Works

Core Concepts

Concept	Description
Project	A workspace containing a thread tree. Has a title, system context, and mode (solo/team).
Thread	A node in the tree representing a discussion topic. Stores a markdown summary.
Context	The assembled chain of summaries from root to active thread — what gets sent to the AI.
Summary	A concise markdown description of what was discussed/decided in a thread.

Storage

ThreadMind stores everything in a .threadmind/ directory at your project root:

.threadmind/
  config.json              # Local state (active project/thread, author ID)
  .gitignore               # Excludes config.json from git
  projects/
    my-app.json            # Project configuration
  threads/
    my-app/
      main.md              # Root thread (markdown + YAML frontmatter)
      auth-system.md       # Child thread
      auth-api.md          # Grandchild thread
  trees/
    my-app.json            # Tree structure index

Thread files use YAML frontmatter:

---
id: auth-system
title: Authentication System
parentId: main
author: mahmoud-a3f9
createdAt: 2026-04-15T10:00:00Z
updatedAt: 2026-04-15T12:30:00Z
---

Implemented JWT-based authentication with refresh tokens.
Using bcrypt for password hashing. Session stored in httpOnly cookies.
Decision: chose Passport.js over custom middleware for maintainability.

Context Assembly

When you request context, ThreadMind walks up from the active thread to the root, collecting summaries:

## System Context
You are building a Next.js e-commerce application...

---

## Thread: My App
Project overview: Next.js 15, PostgreSQL, Stripe integration...

---

## Thread: Authentication System
JWT-based auth with refresh tokens, bcrypt, Passport.js...

---

## Thread: Auth API Endpoints (active)
POST /auth/login, POST /auth/register, POST /auth/refresh...

Only the direct ancestor chain is included — sibling branches are excluded, keeping context minimal.

context_get also reports token estimation:

ThreadMind context: ~450 tokens | depth: 3 threads

---

Available Tools

Project Management

Tool	Description
project_create	Create a new project with a root "main" thread
project_list	List all projects (shows active project)
project_switch	Switch to a different project

project_create

Parameter	Type	Required	Description
title	string	Yes	Project title (used to generate ID)
systemContext	string	No	System prompt or global instructions
mode	"solo" | "team"	No	Project mode (default: "solo")

Thread Management

Tool	Description
thread_create	Create a child thread branching from a parent
thread_switch	Switch to a different thread
thread_list	Display the thread tree as ASCII art
thread_delete	Delete a thread and all its descendants
thread_rebase	Move a thread to a different parent (like git rebase)

thread_create

Parameter	Type	Required	Description
title	string	Yes	Thread title (used to generate ID)
parentId	string	No	Parent thread ID (defaults to active thread)

thread_delete

Parameter	Type	Required	Description
threadId	string	Yes	Thread ID to delete (cascades to descendants)

thread_rebase

Parameter	Type	Required	Description
threadId	string	Yes	Thread ID to move
newParentId	string	Yes	New parent thread ID

Summary & Context

Tool	Description
summary_update	Update the summary content of a thread
context_get	Get the full assembled context with token estimation

summary_update

Parameter	Type	Required	Description
content	string	Yes	New summary content (markdown)
threadId	string	No	Target thread (defaults to active thread)

Setup

Tool	Description
threadmind_init	Generate instruction files for AI clients (CLAUDE.md, .cursorrules, etc.)

threadmind_init

Parameter	Type	Required	Description
clients	string[]	No	Clients to generate for: "claude", "cursor", "generic" (default: all)

Generates instruction files that tell AI clients to automatically use ThreadMind:

Client	File	Behavior
Claude Code	CLAUDE.md	Read automatically at every session start
Cursor	.cursorrules	Read automatically by Cursor
Generic	.threadmind/instructions.md	Copy-paste into any client's custom instructions

Statistics

Tool	Description
stats_show	Show token savings statistics (compression ratio, per-thread breakdown)

stats_show tracks every summary_update call and computes estimated token savings by comparing cumulative input against the current assembled context.

---

Available Resources

Resource	URI	Description
Current Context	threadmind://context	Assembled context for the active thread
Thread Tree	threadmind://tree	ASCII visualization of the thread tree

---

Available Prompts

Prompt	Description
start-thread	Load and inject the assembled context at the start of a session
summarize-thread	Guide the AI to generate a structured summary for the current thread
tm-help	Show all available ThreadMind commands
tm-context	Get assembled context (shortcut for context_get)
tm-tree	Display thread tree (shortcut for thread_list)
tm-create	Create a new thread (shortcut for thread_create)
tm-switch	Switch to a thread (shortcut for thread_switch)
tm-summary	Update or generate summary (shortcut for summary_update)
tm-stats	Show token savings (shortcut for stats_show)
tm-init	Generate instruction files (shortcut for threadmind_init)

In Claude Code, these appear as slash commands: /mcp__thread-mind__tm-help, /mcp__thread-mind__tm-create, etc.

Quick Shortcuts (via CLAUDE.md)

After running threadmind_init, the generated CLAUDE.md enables short text commands you can type directly in chat:

Command	Action
tm:help	Show all available commands
tm:context	Load assembled context
tm:tree	Show thread tree
tm:create <title>	Create a new thread
tm:switch <id>	Switch to a thread
tm:summary	Auto-generate and save a summary
tm:summary <content>	Save specific summary content
tm:stats	Show token savings statistics
tm:delete <id>	Delete a thread
tm:init	Generate instruction files
tm:project <title>	Create a new project
tm:projects	List all projects

---

Usage Examples

1. Start a new project

You: Create a new ThreadMind project called "E-Commerce App" with system context
     "Building a Next.js e-commerce platform with Stripe payments"

AI: [calls project_create] → Project "e-commerce-app" created. Main thread active.

You: Initialize ThreadMind for this project

AI: [calls threadmind_init] → Generated CLAUDE.md, .cursorrules, instructions.md

2. Work and summarize

You: [discuss authentication implementation with AI...]
You: Update the summary for this thread with what we discussed

AI: [calls summary_update with content summarizing the auth discussion]

3. Branch into a sub-topic

You: Create a new thread for "Payment Integration"

AI: [calls thread_create] → Thread "payment-integration" created under "main".

     main ← active
     └── payment-integration

4. Navigate threads

You: Show me the thread tree

AI: [calls thread_list] →
     main
     ├── auth-system
     │   ├── auth-ui
     │   └── auth-api
     └── payment-integration ← active

5. Get assembled context

You: What's the current context?

AI: [calls context_get] →
     ## System Context
     Building a Next.js e-commerce platform with Stripe payments

     ---

     ## Thread: E-Commerce App
     Project overview...

     ---

     ## Thread: Payment Integration (active)
     Stripe integration details...

---

Team Mode

Team mode enables collaborative thread trees shared via git.

How it works

1. Create a project in team mode:

   project_create with title "Shared Project" and mode "team"
   

2. Each team member gets a unique author ID (auto-generated from git config user.name)

3. Thread files (.threadmind/threads/) and tree structure (.threadmind/trees/) are tracked by git

4. The local config (.threadmind/config.json) is gitignored — each member has their own active thread state

Rules

Action	Own threads	Teammates' threads
Read summary	Yes	Yes
Update summary	Yes	No
Delete	Yes	No
Create child thread	Yes	Yes
Switch to	Yes	Yes

Workflow

# Pull teammates' threads
git pull

# View the full tree (includes everyone's threads)
# → Use thread_list

# Branch from a teammate's thread
# → Use thread_create with parentId set to their thread

# Push your new threads
git add .threadmind/
git commit -m "Add payment-integration thread"
git push

---

Development

Setup

git clone <repository-url>
cd thread-mind-mcp
npm install

Build

npm run build

Test

npm test              # Run all tests once
npm run test:watch    # Watch mode

Local development

npm run dev           # Watches src/ and restarts on changes

Type checking

npm run lint          # TypeScript type check without emitting

---

Publishing

Prerequisites

1. Make sure you are logged in to npm:

   npm login
   

2. Ensure all tests pass:

   npm test
   

Release

# Patch release (0.1.0 → 0.1.1) — bug fixes
npm run release:patch

# Minor release (0.1.0 → 0.2.0) — new features
npm run release:minor

# Major release (0.1.0 → 1.0.0) — breaking changes
npm run release:major

These commands will:

1. Run tests
2. Build the project
3. Bump the version in package.json
4. Publish to npm

Don't forget to update CHANGELOG.md before releasing.

---

Architecture

src/
  index.ts              # Entry point — stdio transport
  server.ts             # McpServer factory (tools + resources + prompts)
  types/
    index.ts            # All TypeScript interfaces
  core/
    frontmatter.ts      # YAML frontmatter parser/serializer (zero deps)
    storage.ts          # File I/O layer with atomic writes
    project.ts          # Project lifecycle management
    thread.ts           # Thread CRUD, tree operations, ASCII rendering
    context.ts          # Context assembly + token estimation
    instructions.ts     # Multi-client instruction file generator
    stats.ts            # Token savings tracking and statistics
  tools/
    index.ts            # 11 MCP tool registrations with Zod schemas
  resources/
    index.ts            # 2 MCP resource registrations
  prompts/
    index.ts            # 2 MCP prompt templates

Design Decisions

• File-based storage over SQLite — git-friendly, human-readable, zero native dependencies
• YAML frontmatter — thread metadata and content in a single .md file, readable by both humans and tools
• No external YAML parser — minimal hand-rolled parser for the simple flat frontmatter format
• Atomic writes — write to temp file first, prevents corruption on crash
• Slugified IDs — thread IDs derived from titles ("Auth System" → "auth-system"), collision-safe with auto-suffix
• MCP Prompts — structured templates (start-thread, summarize-thread) to guide AI clients
• Multi-client instructions — auto-generated CLAUDE.md / .cursorrules for seamless integration
• Token estimation — approximate token count reported with every context assembly

---

Requirements

• Node.js >= 18.0.0
• Git (optional, for team mode author detection and collaboration)

License

MIT