Branch Thinking

by ssdeanx

1 stars

469 downloads

Not rated

GitHub

About

Enables simultaneous management of multiple reasoning paths through a branch-based navigation system that supports creation, cross-referencing, insight generation, and priority tracking for complex problem-solving tasks.

Details

Author: ssdeanx
Repository: ssdeanx/branch-thinking-mcp
GitHub stars: 1
Downloads: 469
License: MIT License
Categories: Productivity, Design, Developer Tools, AI, Infrastructure, Frontend, Project Management, Knowledge Base, Automation

- 🌳 Branch Management: Create, focus, and navigate multiple lines of thought
- 🔗 Cross-References: Link related thoughts across branches (typed, scored)
- 💡 AI Insights: Automatic insight and summary generation
- 🧠 Semantic Search: Find related thoughts using embeddings
- 📊 Advanced Visualization:
- Node clustering (k-means/degree)
- Centrality overlays (closeness, betweenness)
- Edge bundling
- Task overlays (status, priority, next-action)
- Agentic overlays and metadata for all nodes/edges
- FocusNode and multi-branch visualization
- ⚡ Agentic Cache & Prefetch:
- LRU+TTL caches for embeddings, summaries, analytics
- Proactive cache warming for agent workflows
- 🗂️ Persistent Storage: Queryable, extensible, and never lose a thought
- 🔄 Real-Time & Multi-Branch: Visualize and analyze multiple branches and nodes in real-time
- 🛠️ Production-Grade: Robust error handling, performance optimizations, and agent/human-friendly APIs

---

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below
Plugin Name Branch Thinking

Command (node, npx, python, etc.) npx
Arguments
- Argument 1 -y
- Argument 2 @highlight/mcp-server
Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "branch thinking": {
            "env": {},
            "args": [
                "-y",
                "@highlight/mcp-server"
            ],
            "command": "npx"
        }
    }
}

JSON

{
    "mcpServers": {
        "branch thinking": {
            "env": {},
            "args": [
                "/c",
                "npx",
                "-y",
                "@highlight/mcp-server"
            ],
            "command": "cmd"
        }
    }
}

JSON

{
    "mcpServers": {
        "branch thinking": {
            "env": {},
            "args": [
                "-y",
                "@highlight/mcp-server"
            ],
            "command": "npx"
        }
    }
}

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

{
    "mcpServers": {
        "branch thinking": {
            "env": {},
            "args": [
                "-y",
                "@highlight/mcp-server"
            ],
            "command": "npx"
        }
    }
}

JSON

{
    "mcpServers": {
        "branch thinking": {
            "env": {},
            "args": [
                "/c",
                "npx",
                "-y",
                "@highlight/mcp-server"
            ],
            "command": "cmd"
        }
    }
}

JSON

{
    "mcpServers": {
        "branch thinking": {
            "env": {},
            "args": [
                "-y",
                "@highlight/mcp-server"
            ],
            "command": "npx"
        }
    }
}

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "branch thinking": {
            "env": {},
            "args": [
                "-y",
                "@highlight/mcp-server"
            ],
            "command": "npx"
        }
    }
}

JSON

{
    "mcpServers": {
        "branch thinking": {
            "env": {},
            "args": [
                "/c",
                "npx",
                "-y",
                "@highlight/mcp-server"
            ],
            "command": "cmd"
        }
    }
}

JSON

{
    "mcpServers": {
        "branch thinking": {
            "env": {},
            "args": [
                "-y",
                "@highlight/mcp-server"
            ],
            "command": "npx"
        }
    }
}

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

{
    "mcpServers": {
        "branch thinking": {
            "env": {},
            "args": [
                "-y",
                "@highlight/mcp-server"
            ],
            "command": "npx"
        }
    }
}

JSON

{
    "mcpServers": {
        "branch thinking": {
            "env": {},
            "args": [
                "/c",
                "npx",
                "-y",
                "@highlight/mcp-server"
            ],
            "command": "cmd"
        }
    }
}

JSON

{
    "mcpServers": {
        "branch thinking": {
            "env": {},
            "args": [
                "-y",
                "@highlight/mcp-server"
            ],
            "command": "npx"
        }
    }
}

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "branch thinking": {
            "env": {},
            "args": [
                "-y",
                "@highlight/mcp-server"
            ],
            "command": "npx"
        }
    }
}

JSON

{
    "mcpServers": {
        "branch thinking": {
            "env": {},
            "args": [
                "/c",
                "npx",
                "-y",
                "@highlight/mcp-server"
            ],
            "command": "cmd"
        }
    }
}

JSON

{
    "mcpServers": {
        "branch thinking": {
            "env": {},
            "args": [
                "-y",
                "@highlight/mcp-server"
            ],
            "command": "npx"
        }
    }
}

From the repository

git clone https://github.com/your-org/branch-thinking-mcp.git
cd branch-thinking-mcp
pnpm install  # Or npm install
pnpm build   # Or npm run build

For Claude Desktop integration, add to your claude_desktop_config.json:

"branch-thinking": {
  "command": "node",
  "args": [
    "/your-custom-mcp-dir-here/branch-thinking/dist/index.js"
  ]
}

`list`

Show all branches with status.

`focus [branchId]`

Switch focus to a branch.

`history [branchId?]`

Show thought history.

`summarize-branch [branchId?]`

AI summary of branch.

`review-branch [branchId?]`

AI review of branch.

`visualize [branchId]`

Visual graph of connections.

`insights [branchId?]`

Get AI-generated insights.

`crossrefs [branchId?]`

Show cross-references.

`hub-thoughts [branchId?]`

List hub thoughts.

`semantic-search [query]`

Find similar thoughts.

`link-thoughts [from] [to] [type] [reason?]`

Link two thoughts.

`add-snippet [content] [tags]`

Save a code snippet.

`snippet-search [query]`

Search code snippets.

`doc-thought [thoughtId]`

Document a thought.

`extract-tasks [branchId?]`

Extract actionable items.

`list-tasks [branchId] [status] [assignee] [due]`

List/filter tasks.

`update-task-status [taskId] [status]`

Update a task’s status.

`summarize-tasks [branchId]`

Summarize tasks.

`ask [question]`

AI answer from knowledge base.

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "branch thinking": {
            "env": {},
            "args": [
                "-y",
                "@highlight/mcp-server"
            ],
            "command": "npx"
        }
    }
}

Linux

{
    "env": [],
    "args": [
        "-y",
        "@highlight/mcp-server"
    ],
    "command": "npx"
}

Macos

{
    "env": [],
    "args": [
        "-y",
        "@highlight/mcp-server"
    ],
    "command": "npx"
}

Windows

{
    "env": [],
    "args": [
        "/c",
        "npx",
        "-y",
        "@highlight/mcp-server"
    ],
    "command": "cmd"
}

🚦 Branch-Thinking MCP Tool

> What’s New (2025-04):
>
> - Advanced visualization: clustering (k-means/degree), centrality overlays, edge bundling, and agentic overlays for tasks and priorities
> - Agentic cache & prefetch: LRU+TTL caches for embeddings, summaries, analytics, and proactive agent cache warming
> - Enhanced analytics: real-time, multi-branch, and focusNode support; agent-optimized metadata
> - Upgraded documentation and onboarding for agents and users

---

Features

---

🛠️ Technology Stack

- Node.js (18+)
- TypeScript (4.x)
- @dagrejs/graphlib: Graph structure, algorithms, and analytics
- ml-kmeans: Clustering for visualization
- lru-cache: LRU+TTL caching for embeddings, summaries, analytics
- @xenova/transformers: Embedding and summarization pipelines
- @modelcontextprotocol/sdk: MCP protocol and agent integration
- chalk: CLI output styling
- Mermaid: Gantt/roadmap visualization
- pnpm: Fast dependency management

---

Roadmap (Gantt)

gantt
    title Branch-Thinking MCP Roadmap (2025)
    dateFormat  YYYY-MM-DD
    section Q2 2025
    Advanced Visualization/Analytics :done,      vis1, 2025-04-01,2025-04-20
    Agentic Cache & Prefetch         :done,      cache1, 2025-04-10,2025-04-22
    Enhanced Agentic Docs            :done,      doc1, 2025-04-15,2025-04-25
    Real-time Collaboration          :active,    collab1, 2025-04-20,2025-06-01
    Web Visualization Dashboard      :active,    webviz1, 2025-04-25,2025-06-15
    section Q3 2025
    Plugin System                    :planned,   plugin1, 2025-06-15,2025-07-15
    Mobile/Tablet UI                 :planned,   mobile1, 2025-07-01,2025-08-01
    AI Branch Merging                :planned,   merge1, 2025-07-15,2025-08-15
    Knowledge Base Sync              :planned,   sync1, 2025-08-01,2025-09-01

---

- Why Branch-Thinking?
- Summary
- Features
- Quick Start
- Getting Started
- Real-World Usage Recipes
- Architecture & Flow
- Roadmap (Gantt)
- Testing & Quality
- Security
- Accessibility & Internationalization
- Troubleshooting & FAQ
- Best Practices
- Contributing
- Changelog
- References & Related Projects
- Credits
- License

---

Why Branch-Thinking?

- Agentic by Design: Built for both human and AI workflows—every command is agent-friendly.
- True Branching: Organize, cross-link, and reason over ideas, code, and tasks in parallel.
- AI-Native: Semantic search, auto-summarization, and insight generation out-of-the-box.
- Persistent & Visual: Never lose a thought—everything is queryable, visualizable, and extensible.

Summary

> Branch-Thinking MCP Tool is an advanced agentic platform for managing, visualizing, and reasoning over branching thoughts, tasks, code, and knowledge. It empowers both AI agents and humans to organize complex projects, cross-link ideas, and automate insight generation using a powerful branch-based paradigm. With semantic search, visualization, and persistent task/code management, it is designed for next-generation collaborative and autonomous workflows.

Branch-Thinking MCP Tool is an advanced agentic platform for managing, visualizing, and reasoning over branching thoughts, tasks, code, and knowledge. It empowers both AI agents and humans to organize complex projects, cross-link ideas, and automate insight generation using a powerful branch-based paradigm. With semantic search, visualization, and persistent task/code management, it is designed for next-generation collaborative and autonomous workflows.

---

Architecture & Flow

flowchart TD
    User([User/Agent 🤖])
    CLI([CLI/API])
    BM[BranchManager 🧠]
    EmbCache[[Embedding/Summary Cache]]
    Storage[(Persistent Storage 💾)]
    Viz([Visualization/Analytics])
    Tasks([Task Extraction])
    Snippets([Code Snippet Storage])
User-->|Commands/Queries|CLI

    CLI-->|Manage/Query|BM

    BM-->|Cache|EmbCache

    BM-->|Save/Load|Storage

    BM-->|Visualize|Viz

    BM-->|Tasks|Tasks

    BM-->|Snippets|Snippets

    BM-->|Results|CLI

    CLI-->|Output|User

---

Quick Start

Get up and running in seconds:

pnpm install  # Recommended for speed (or npm install)
pnpm build
node dist/index.js --help  # See available commands

---

Getting Started

1. Clone & Install

git clone https://github.com/your-org/branch-thinking-mcp.git
cd branch-thinking-mcp
pnpm install  # Or npm install
pnpm build   # Or npm run build

2. Configure (Optional)

For Claude Desktop integration, add to your claude_desktop_config.json:

"branch-thinking": {
  "command": "node",
  "args": [
    "/your-custom-mcp-dir-here/branch-thinking/dist/index.js"
  ]
}

3. Run

node dist/index.js

---

Real-World Usage Recipes

1. Knowledge Capture & Linking

# Batch capture meeting notes
add-thought dev "Discussed semantic search improvements" note
add-thought dev "Agreed to refactor API" decision
Link related thoughts
link-thoughts t1 t2 supports "API refactor supports search improvements"

2. Agentic Task Extraction

# Extract and manage tasks from a research branch
extract-tasks research
list-tasks research open
update-task-status task-1 in_progress

3. Visualization for Insight

# Generate and interpret a knowledge graph
visualize dev
Review AI-generated summary
summarize-branch dev

---

🧑‍💻 Live Example: Agentic Workflow

# 1. Create a new branch for your project or idea
create-branch "AI Research"
2. Add thoughts and observations
add-thought [branchId] "Explore semantic search for agent workflows" analysis
add-thought [branchId] "Test cross-linking and summarization" observation
3. Link related thoughts
link-thoughts [thoughtId1] [thoughtId2] supports "Thought 2 validates Thought 1"
4. See your knowledge graph
visualize [branchId]
5. Extract tasks and get AI review
extract-tasks [branchId]
review-branch [branchId]

> Replace [branchId] and [thoughtIdX] with actual IDs from list and history.

---

Command Reference

Branch Management

| Command | Description |
|---------|-------------|
| list | Show all branches with status |
| focus [branchId] | Switch focus to a branch |
| history [branchId?] | Show thought history |
| summarize-branch [branchId?] | AI summary of branch |
| review-branch [branchId?] | AI review of branch |
| visualize [branchId?] | Visual graph of connections |

Thought & Insight Management

| Command | Description |
|---------|-------------|
| insights [branchId?] | Get AI-generated insights |
| crossrefs [branchId?] | Show cross-references |
| hub-thoughts [branchId?] | List hub thoughts |
| semantic-search [query] | Find similar thoughts |
| link-thoughts [from] [to] [type] [reason?] | Link two thoughts |
| add-snippet [content] [tags] | Save a code snippet |
| snippet-search [query] | Search code snippets |
| doc-thought [thoughtId] | Document a thought |

Task Management

| Command | Description |
|---------|-------------|
| extract-tasks [branchId?] | Extract actionable items |
| list-tasks [branchId] [status] [assignee] [due] | List/filter tasks |
| update-task-status [taskId] [status] | Update a task’s status |
| summarize-tasks [branchId] | Summarize tasks |

AI & Knowledge

| Command | Description |
|---------|-------------|
| ask [question] | AI answer from knowledge base |

Best Practices

- Always start with create-branch to ensure clean context.
- Use list and focus to navigate between projects or lines of thought.
- Leverage summarize-branch and insights after adding several thoughts to get AI-generated context.
- Use link-thoughts to explicitly connect ideas, tasks, or code for richer semantic graphs.
- After code changes, always run pnpm lint and pnpm build to catch errors early.
- Decompose complex goals into sequences of thought/task/insight commands.
- Iterate and adapt: Use feedback from summaries, reviews, and visualizations to refine next actions.
- Explicitly specify parameters (branchId, status, assignee, etc.) for precise results.
- Use cross-references and multi-hop links to foster creativity and bridge ideas.
- Prompt agents (Claude, GPT-4, etc.) to "think step by step" or "use chain of thought" for best results.

Security

- All persistent data is stored locally (default: project directory or MCP_STORAGE_PATH)
- No external API calls unless configured
- Agents/users are responsible for privacy of stored thoughts and tasks
- To report security issues, please open an issue or email the maintainer.

Troubleshooting and FAQ

Q: The tool isn't responding!

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Details

Jump to

Setting up with Highlight

From the repository

list

focus [branchId]

history [branchId?]

summarize-branch [branchId?]

review-branch [branchId?]

visualize [branchId]

insights [branchId?]

crossrefs [branchId?]

hub-thoughts [branchId?]

semantic-search [query]

link-thoughts [from] [to] [type] [reason?]

add-snippet [content] [tags]

snippet-search [query]

doc-thought [thoughtId]

extract-tasks [branchId?]

list-tasks [branchId] [status] [assignee] [due]

update-task-status [taskId] [status]

summarize-tasks [branchId]

ask [question]

Claude Desktop / Cursor

Linux

Macos

Windows

🚦 Branch-Thinking MCP Tool

Features

🛠️ Technology Stack

Roadmap (Gantt)

Table of Contents

Why Branch-Thinking?

Summary

Architecture & Flow

Quick Start

Getting Started

1. Clone & Install

2. Configure (Optional)

3. Run

Real-World Usage Recipes

1. Knowledge Capture & Linking

Link related thoughts

2. Agentic Task Extraction

3. Visualization for Insight

Review AI-generated summary

🧑‍💻 Live Example: Agentic Workflow

2. Add thoughts and observations

3. Link related thoughts

4. See your knowledge graph

5. Extract tasks and get AI review

Command Reference

Branch Management

Thought & Insight Management

Task Management

AI & Knowledge

Best Practices

Security

Troubleshooting and FAQ

Install

More like this

Time

Sentry

Github

Git

GitLab

Context 7

`list`

`focus [branchId]`

`history [branchId?]`

`summarize-branch [branchId?]`

`review-branch [branchId?]`

`visualize [branchId]`

`insights [branchId?]`

`crossrefs [branchId?]`

`hub-thoughts [branchId?]`

`semantic-search [query]`

`link-thoughts [from] [to] [type] [reason?]`

`add-snippet [content] [tags]`

`snippet-search [query]`

`doc-thought [thoughtId]`

`extract-tasks [branchId?]`

`list-tasks [branchId] [status] [assignee] [due]`

`update-task-status [taskId] [status]`

`summarize-tasks [branchId]`

`ask [question]`