Tree of Thought (ToT)

Systematic problem-solving framework for Claude Code CLI based on Princeton NLP research.

🌳 What is Tree of Thought?

Tree of Thought (ToT) enables AI to solve complex problems through systematic exploration of solution spaces. Based on Princeton NLP's research, it:

Generates multiple solution paths at each decision point
Evaluates and compares different approaches systematically
Backtracks and explores alternatives when paths don't work
Finds optimal solutions through structured search

🚀 Quick Start

Install the /tot command for Claude Code CLI:

npm install -g tree-of-thought-cli

Then use it in Claude Code:

/tot "your problem description"

What Gets Installed

/tot command in ~/.claude/commands/
Algorithm guides in ~/.claude/tot/core/
Problem templates in ~/.claude/tot/templates/
Usage examples in ~/.claude/tot/examples/

How It Works

Claude Code reads documentation files and implements ToT dynamically. No code execution - purely prompt-based and transparent.

🔧 MCP Setup (Optional but Recommended)

Enable Multi-AI mode with Gemini and Codex MCP for maximum diversity and deeper analysis:

Gemini MCP (Architecture & Design Focus)

# Install Gemini MCP - provides system architecture expertise
claude mcp add gemini-cli -s user -- npx -y gemini-mcp-tool

Codex MCP (Performance & Optimization Focus)

# 1. Install OpenAI Codex CLI
npm install -g @openai/codex
# or: brew install codex

# 2. Login to Codex
codex login

# 3. Add Codex MCP to Claude Code
claude mcp add codex -s user -- codex mcp-server

Verify Installation

# Check if MCPs are configured
claude mcp list

You should see gemini-cli and codex in the MCP server list.

💡 Note:

No MCPs: /tot runs in Claude-only mode (~15s, 6 thoughts)

Gemini only: Claude + Gemini Hybrid mode (~20s)

Codex only: Claude + Codex Hybrid mode (~25s)

Both MCPs: Multi-AI mode (~20s, maximum diversity) ✨

📖 Example Usage

Debug a Memory Leak

/tot "Production app memory grows 50MB/hour after user logout"

Output:

Level 1: Generate 5 hypotheses
├─ [8.5] Unclosed event listeners
├─ [9.1] Timer not cleared ⭐
├─ [7.9] Cache not released
...

Level 2: Expand top 3
├─ Timer → [9.5] Search for setInterval ⭐
├─ Timer → [8.8] Search for setTimeout
...

Solution: Found 3 setInterval calls without cleanup

Design System Architecture

/tot "Design real-time notification system for 100k concurrent users"

Optimize Performance

/tot "Database query takes 5 seconds on 1M+ rows with JOINs"

🎯 Core Methodology

Based on Princeton ToT paper with Multi-AI enhancements:

Generate 6 diverse solution approaches (n_generate=6)
- Multi-AI: 2 Claude + 2 Gemini + 2 Codex
- Hybrid: 3 from each of 2 AIs
- Single: 6 from one AI
Evaluate each approach 3 times independently (n_evaluate=3)
Select top 3-4 for further exploration (n_select=3-4)
Search using BFS or DFS with early stopping
Return optimal solution path

AI Role Differentiation

Claude: Practical, user-focused, proven patterns
Gemini: Innovative architecture, creative system design
Codex: Algorithm optimization, performance analysis

This prevents thought overlap and maximizes solution diversity.

⚡ Execution Modes

Performance Comparison

Mode	MCPs Required	Execution Time	AI Distribution	Use Case
Multi-AI (Default)	Gemini + Codex	~20s	Claude 33% + Gemini 33% + Codex 33%	Maximum diversity ✨
Hybrid CG (`--hybrid cg`)	Gemini	~18s	Claude 50% + Gemini 50%	Practical + Architecture
Hybrid CX (`--hybrid cx`)	Codex	~22s	Claude 50% + Codex 50%	Practical + Performance
Hybrid GX (`--hybrid gx`)	Gemini + Codex	~20s	Gemini 50% + Codex 50%	Architecture + Performance
Claude-Only (`-c`)	None	~15s	Claude 100%	Quick, practical solutions
Gemini-Only (`-g`)	Gemini	~15s	Gemini 100%	Architecture focus only
Codex-Only (`-x`)	Codex	~18s	Codex 100%	Performance focus only

🔑 Key Point: MCPs not configured? Auto-fallback to Claude-only mode (~15s). All modes work without MCPs!

Mode Details

🌟 Multi-AI Mode (Claude + Gemini + Codex) - DEFAULT

/tot "your problem"              # Default: 3 AI perspectives
/tot --ratio 2:2:2               # Equal distribution (default)
/tot --ratio 3:2:1               # Claude-focused
/tot --ratio 1:2:3               # Performance-focused

Characteristics:

Speed: ~20 seconds (all AIs run in parallel)
Thoughts: 6 total (2 from each AI)
Strengths: Maximum diversity, balanced perspectives, comprehensive coverage
Best for: Complex problems requiring multiple viewpoints

AI Roles:

Claude (33%): Practical solutions, proven patterns, quick wins
Gemini (33%): System architecture, creative design, scalability
Codex (33%): Algorithm optimization, performance tuning, profiling

Auto-Fallback: If Gemini or Codex unavailable, Claude generates replacement thoughts automatically.

🤝 Hybrid Mode (2 AIs)

# Claude + Gemini (Practical + Architecture)
/tot --hybrid cg "your problem"

# Claude + Codex (Practical + Performance) - Classic
/tot --hybrid cx "your problem"

# Gemini + Codex (Architecture + Performance)
/tot --hybrid gx "your problem"

Characteristics:

Speed: ~18-22 seconds
Thoughts: 6 total (3 from each AI)
Best for: Focused expertise in 2 specific areas

🚀 Single-AI Mode

/tot -c "your problem"           # Claude-only (practical)
/tot -g "your problem"           # Gemini-only (architecture)
/tot -x "your problem"           # Codex-only (performance)

Characteristics:

Speed: ~15-18 seconds
Thoughts: 6 total (all from one AI)
Best for: Quick analysis, specific expertise needed

Problem Type Examples

Debug Problems

/tot debug "Memory leak grows 50MB/hour"
/tot -c debug "React component infinite re-render"

Refactoring

/tot refactor "PaymentService has 500 lines, needs modularization"
/tot --ratio 7:3 refactor "Extract algorithm to separate module"

Design & Architecture

/tot design "Real-time notification system for 100k users"
/tot -c design "API versioning strategy"

Performance Optimization

/tot optimize "Database query takes 5s on 1M+ rows"
/tot --ratio 3:7 optimize "Reduce bundle size from 2MB to 500KB"

Custom Problems

/tot "How to implement distributed cache invalidation?"
/tot -c "Best approach for handling file uploads in React?"

When to Choose Which Mode

Scenario	Recommended Mode	Reason
Complex system design	Multi-AI (default)	Need practical + architecture + performance
Quick bug fix	Claude-Only (`-c`)	Faster, sufficient for common issues
Architecture planning	`--hybrid cg` or `-g`	Gemini's design expertise
Algorithm optimization	`--hybrid cx` or `-x`	Codex's performance focus
Standard refactoring	Claude-Only (`-c`)	Proven patterns work well
Novel architecture	Multi-AI (default)	Maximum diversity needed
Performance tuning	`--hybrid gx`	Architecture + Optimization
Time-critical	Claude-Only (`-c`)	Fastest (~15s)

📊 Algorithm Comparison

Algorithm	Best For	Memory	Speed
BFS	Comprehensive exploration	High	Medium
DFS	Deep analysis with backtracking	Low	Fast

📖 Documentation

Core Documentation

Command Reference - Full /tot usage guide
Multi-AI Template - Multi-AI usage patterns
Core Algorithms - BFS, DFS, evaluation methods
Problem Templates - Debug, refactor, design
Usage Examples - Real-world scenarios
Output Format - Transparent thought display

MCP Integration Guides

Gemini MCP Integration - Gemini setup & usage
Codex MCP Integration - Codex setup & usage

🏗️ Project Structure

tree-of-thought/
├── packages/cli/              # npm package
│   ├── commands/tot.md        # Command definition
│   └── scripts/install.js     # Installation script
└── docs/
    ├── guide/
    │   ├── core/              # 15+ algorithm guides
    │   └── templates/         # 6 problem templates
    ├── examples/              # 6 usage examples
    └── OUTPUT_FORMAT.md

🤝 Contributing

Contributions welcome! Open an issue or pull request.

Local Development

git clone https://github.com/youkchansim/tree-of-thought.git
cd tree-of-thought/packages/cli

# Test locally
npm link

# The /tot command will be available in Claude Code
# Make changes to documentation in docs/guide/

# Publish updates
npm version patch
npm publish

📄 License

MIT License - See LICENSE file.

🙏 Acknowledgments

Based on Princeton NLP's Tree of Thought research:

Tree of Thoughts: Deliberate Problem Solving with Large Language Models (Yao et al., 2023)
Princeton NLP Repository

📧 Support

Issues: github.com/youkchansim/tree-of-thought/issues
Author: @youkchansim

Name		Name	Last commit message	Last commit date
Latest commit History 28 Commits
packages/cli		packages/cli
.eslintrc.js		.eslintrc.js
.gitignore		.gitignore
.prettierrc		.prettierrc
IMPROVEMENTS.md		IMPROVEMENTS.md
LICENSE		LICENSE
README.md		README.md
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

Tree of Thought (ToT)

🌳 What is Tree of Thought?

🚀 Quick Start

What Gets Installed

How It Works

🔧 MCP Setup (Optional but Recommended)

Gemini MCP (Architecture & Design Focus)

Codex MCP (Performance & Optimization Focus)

Verify Installation

📖 Example Usage

Debug a Memory Leak

Design System Architecture

Optimize Performance

🎯 Core Methodology

AI Role Differentiation

⚡ Execution Modes

Performance Comparison

Mode Details

🌟 Multi-AI Mode (Claude + Gemini + Codex) - DEFAULT

🤝 Hybrid Mode (2 AIs)

🚀 Single-AI Mode

Problem Type Examples

Debug Problems

Refactoring

Design & Architecture

Performance Optimization

Custom Problems

When to Choose Which Mode

📊 Algorithm Comparison

📖 Documentation

Core Documentation

MCP Integration Guides

🏗️ Project Structure

🤝 Contributing

Local Development

📄 License

🙏 Acknowledgments

📧 Support

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages