How do I use smart-fork?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@smart-fork find sessions about deployment issues" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

smart-fork

by recursive-vibe

Overview Schema Related Servers Score Discussions

Python

Local

Smart Fork Detection

An MCP (Model Context Protocol) server for Claude Code that enables semantic search of past session transcripts and intelligent session forking. Never lose context again - find and resume from the most relevant previous conversation instantly.

Python 3.10+ License: MIT

Overview

Smart Fork Detection solves the "context loss" problem in AI-assisted development by maintaining a searchable vector database of all your Claude Code sessions. When you need to work on a similar task or continue where you left off, simply search your conversation history and fork from the most relevant session - with full context preserved.

Key Benefits:

Overcome Context Limits: Break free from the 200,000 token limit by intelligent session forking
Instant Context Recovery: Find relevant past conversations in seconds instead of re-explaining everything
Knowledge Reuse: Transform hundreds of isolated sessions into connected, searchable knowledge
Productivity Boost: Reduce context rebuilding time from minutes to seconds

Related MCP server: ClaudeHistoryMCP

Features

Core Capabilities

✅ Semantic Search - AI-powered search across all your Claude Code sessions
✅ Smart Session Forking - Resume from the most relevant conversation
✅ Background Indexing - Automatic real-time indexing of new sessions
✅ Project-Scoped Search - Filter results by project directory
✅ Fork History Tracking - Keep track of recently forked sessions

Performance & Intelligence

✅ Query Result Caching - 50%+ faster repeat searches
✅ Embedding Cache - Skip re-computing embeddings for unchanged content
✅ Preference Learning - Improves results based on your fork selections
✅ Temporal Search - Find sessions by date ("last Tuesday", "2 weeks ago")
✅ Multi-Threaded Indexing - 2-3x faster initial setup with parallel processing

Organization & Analysis

✅ Session Tagging - Organize sessions with custom tags
✅ Topic Clustering - Automatic grouping of related sessions (k-means)
✅ Session Summaries - TF-IDF extractive summaries with key topics
✅ Session Diff Tool - Semantic comparison between sessions
✅ Duplicate Detection - Find similar sessions automatically
✅ Session Archiving - Archive old sessions to separate database

Integrations

✅ MCP Protocol - Native integration with Claude Code
✅ VS Code Extension - Search and fork directly from VS Code (beta)
✅ CLI Tools - Command-line access to all features

Installation

Prerequisites

Python 3.10 or higher
Claude Code (with MCP support)
1GB+ RAM recommended for embedding model
500MB+ disk space for vector database

Install from Source

Clone the repository:

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

Create and activate a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Install the package:

pip install -e .

Install from PyPI (coming soon)

pip install smart-fork

Verify Installation

Run the verification script to ensure everything is set up correctly:

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

Configure Claude Code MCP

Add Smart Fork to your Claude Code MCP configuration file (~/.claude/mcp_servers.json):

{
  "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"
      }
    }
  }
}

Replace /path/to/smart-fork with your actual installation path.

Restart Claude Code (or reload the VSCode window) to load the MCP server.

Quick Start

Start Claude Code - The Smart Fork server will automatically start in the background and begin indexing your existing sessions.
First Run Setup - On first launch, Smart Fork will scan ~/.claude/ for existing session files and build the initial database. This may take a few minutes depending on how many sessions you have.
Manual Initial Indexing (recommended for first run):
```
cd /path/to/smart-fork
source venv/bin/activate

# For small session counts (<100 sessions)
python -m smart_fork.initial_setup

# For large session counts (100+ sessions) - recommended
python -m smart_fork.initial_setup --batch-mode
```
Note:
- Large session files (>1MB) may take longer to process. Sessions with no parseable messages will be skipped.
- By default, sessions that take longer than 30 seconds to process will timeout and be skipped. See Timeout Handling for configuration options.
- For 100+ sessions, use --batch-mode to avoid memory issues. See Batch Mode Setup for details.
Use the Tool - In any Claude Code session, simply describe what you want to do in natural language. Claude Code will automatically invoke the fork-detect tool when appropriate.
Example:
```
You: I want to find my previous work on WebSocket real-time updates

Claude: [Automatically invokes fork-detect tool behind the scenes]
```
Select a Session - Claude will present the top 5 most relevant past sessions. Choose one to fork from, or start fresh.
Fork and Continue - Copy the generated command and paste it in a new terminal to continue from that session with full context.

Usage

Using the fork-detect Tool

Smart Fork provides the fork-detect MCP tool that integrates seamlessly with Claude Code. When you describe a task or problem, Claude Code can automatically invoke this tool to search your session history and find the most relevant previous conversations.

How It Works:

Natural Language Interface - Simply describe your task in the conversation with Claude
Automatic Invocation - Claude Code invokes the fork-detect tool behind the scenes when appropriate
Semantic Search - The tool searches your entire session history using AI-powered semantic matching
Contextual Results - You receive a curated list of the most relevant past sessions

Example Queries:

You can ask Claude to help you with tasks like:

"I want to implement user authentication with JWT like I did before"
"Can you find my previous work on database connection pooling?"
"Show me sessions where I added dark mode to settings"
"Find conversations about refactoring API error handling"
"Help me find my React component optimization work"

Direct Invocation (Optional):

While Claude Code typically invokes the tool automatically, you can also explicitly ask:

You: Use the fork-detect tool to search for "WebSocket real-time updates"

Note: The fork-detect tool is an MCP tool, not a slash command. It's invoked through the Model Context Protocol, either automatically by Claude or when you explicitly request it.

Selecting a Session

After searching, Smart Fork displays exactly 5 options:

Top 3 Results - The most relevant sessions based on composite scoring
None - start fresh - Begin a new session without forking
Type something else - Refine your search with a different query

Each result shows:

Session ID: Unique identifier for the session
Date: When the session was created
Project: Project name (extracted from file path)
Score: Relevance percentage (0-100%)
Preview: Snippet from the most relevant part of the conversation
⭐ Recommended: The highest-scoring result

Example output:

Found 5 relevant sessions:

⭐ [1] Session abc123 (92% match) - Recommended
   Date: 2026-01-15
   Project: my-dashboard
   Preview: "Implemented real-time updates using WebSocket connection with
            automatic reconnection logic..."

[2] Session def456 (81% match)
   Date: 2026-01-10
   Project: my-dashboard
   Preview: "Added dashboard component with live data updates and polling
            fallback..."

[3] Session ghi789 (67% match)
   Date: 2025-12-20
   Project: admin-portal
   Preview: "Created WebSocket handler for server-sent events with proper
            error handling..."

[4] None - start fresh

[5] Type something else

Forking a Session

When you select a session, Smart Fork generates two types of fork commands:

1. New Terminal Fork (Recommended)

claude --resume abc123 --fork-session

Opens a new Claude Code session continuing from the selected conversation.

2. In-Session Fork (Advanced)

/fork abc123 /path/to/project

Forks within the current session (if supported by your Claude Code version).

Simply copy the command and paste it in a new terminal to continue with full context from that session.

Configuration

Smart Fork works out-of-the-box with sensible defaults, but you can customize its behavior.

Configuration Options

Smart Fork uses a configuration file at ~/.smart-fork/config.json. The file is created automatically with default values on first run.

Embedding Model Settings

"embedding": {
  "model_name": "sentence-transformers/all-MiniLM-L6-v2",
  "dimension": 384,
  "batch_size": 32,
  "max_batch_size": 128,
  "min_batch_size": 8
}

model_name: HuggingFace model identifier for embeddings
dimension: Embedding vector dimensions (must match model)
batch_size: Default batch size for embedding generation
max_batch_size: Maximum batch size (auto-adjusted based on RAM)
min_batch_size: Minimum batch size (prevents too-small batches)

Search Parameters

"search": {
  "k_chunks": 200,
  "top_n_sessions": 5,
  "preview_length": 200,
  "similarity_threshold": 0.3,
  "recency_weight": 0.25
}

k_chunks: Number of chunks to retrieve from vector database
top_n_sessions: Number of session results to display
preview_length: Character limit for preview snippets
similarity_threshold: Minimum similarity score (0.0-1.0)
recency_weight: Weight given to recent sessions in scoring

Chunking Settings

"chunking": {
  "target_tokens": 750,
  "overlap_tokens": 150,
  "max_tokens": 1000
}

target_tokens: Target size for each chunk
overlap_tokens: Overlap between adjacent chunks (maintains context)
max_tokens: Maximum chunk size (hard limit)

Background Indexing

"indexing": {
  "debounce_delay": 5.0,
  "checkpoint_interval": 15,
  "enabled": true
}

debounce_delay: Seconds to wait after file modification before indexing
checkpoint_interval: Index after this many new messages (prevents loss)
enabled: Enable/disable background indexing

Timeout Handling

"setup": {
  "timeout_per_session": 30.0
}

timeout_per_session: Maximum time in seconds to process each session file (default: 30.0)

Smart Fork will skip sessions that exceed this timeout and log a warning. Timed-out sessions can be retried later using the retry_timeouts flag.

Handling Large Session Files:

If you have very large session files (>5MB) that timeout during initial setup:

from smart_fork.initial_setup import InitialSetup

# Increase timeout for large files
setup = InitialSetup(timeout_per_session=60.0)
result = setup.run_setup()

# Or retry previously timed-out sessions
if result.get('timeouts'):
    print(f"{len(result['timeouts'])} sessions timed out")
    result = setup.run_setup(resume=True, retry_timeouts=True)

Multi-Threaded Indexing:

Speed up initial setup by processing sessions in parallel:

from smart_fork.initial_setup import InitialSetup

# Use 4 worker threads for parallel processing
setup = InitialSetup(workers=4)
result = setup.run_setup()

print(f"Processed {result['files_processed']} files using {result['workers_used']} workers")
print(f"Elapsed time: {result['elapsed_time']:.1f}s")

# Typical speedup with multiple workers:
# - 2 workers: 1.5-1.8x faster
# - 4 workers: 2-3x faster
# - 8 workers: 3-4x faster (diminishing returns due to I/O)

Batch Mode Setup (Recommended for 100+ Sessions):

For large session counts, batch mode spawns fresh Python processes between batches to fully release memory:

# Run initial setup in batch mode (recommended)
python -m smart_fork.initial_setup --batch-mode

# Custom batch size (default: 5 sessions per batch)
python -m smart_fork.initial_setup --batch-mode --batch-size 10

# Force CPU mode to reduce memory usage
python -m smart_fork.initial_setup --batch-mode --use-cpu

# All batch mode options
python -m smart_fork.initial_setup --batch-mode --batch-size 5 --use-cpu --timeout 60

Batch mode benefits:

Memory Management: Each batch runs in a separate process, ensuring complete memory release
Resumable: State is saved after each session, so you can interrupt and resume anytime
Progress Tracking: Shows current progress and remaining sessions
CPU Mode: --use-cpu disables GPU/MPS acceleration to reduce memory footprint

CLI options:

--batch-mode: Enable subprocess-based batch processing
--batch-size N: Sessions per batch (default: 5)
--use-cpu: Force CPU mode (disable MPS/CUDA)
--timeout N: Timeout per session in seconds (default: 30)
--storage-dir PATH: Custom storage directory (default: ~/.smart-fork)
--claude-dir PATH: Custom Claude sessions directory (default: ~/.claude)

Server Settings

"server": {
  "host": "127.0.0.1",
  "port": 8741
}

host: Bind address (always localhost for security)
port: Port for local REST API server

Memory Management

"memory": {
  "max_memory_mb": 2000,
  "gc_between_batches": true
}

max_memory_mb: Maximum memory usage target in megabytes
gc_between_batches: Run garbage collection between embedding batches

Storage Directory

"storage_dir": "~/.smart-fork"

storage_dir: Directory for database and registry files

Configuration File

Create or edit ~/.smart-fork/config.json:

{
  "embedding": {
    "model_name": "sentence-transformers/all-MiniLM-L6-v2",
    "dimension": 384,
    "batch_size": 32,
    "max_batch_size": 128,
    "min_batch_size": 8
  },
  "search": {
    "k_chunks": 200,
    "top_n_sessions": 5,
    "preview_length": 200,
    "similarity_threshold": 0.3,
    "recency_weight": 0.25
  },
  "chunking": {
    "target_tokens": 750,
    "overlap_tokens": 150,
    "max_tokens": 1000
  },
  "indexing": {
    "debounce_delay": 5.0,
    "checkpoint_interval": 15,
    "enabled": true
  },
  "server": {
    "host": "127.0.0.1",
    "port": 8741
  },
  "memory": {
    "max_memory_mb": 2000,
    "gc_between_batches": true
  },
  "storage_dir": "~/.smart-fork"
}

Changes take effect after restarting Claude Code.

How It Works

Background Indexing

Smart Fork continuously monitors ~/.claude/ for new or modified session files:

File Monitoring: Uses the watchdog library to detect file system changes
Debouncing: Waits 5 seconds after the last modification before indexing (configurable)
Checkpoint Indexing: Indexes sessions every 10-20 messages to prevent data loss
Graceful Processing: Handles rapid successive changes without duplication

Session files are parsed, chunked, embedded, and stored in the vector database automatically.

Semantic Search

When Claude invokes the fork-detect tool, Smart Fork:

Embeds Your Query: Converts your natural language description to a 384-dimensional vector
Vector Search: Finds the 200 most similar chunks using ChromaDB's k-NN search
Groups by Session: Aggregates chunks by their parent session
Scores Sessions: Calculates composite scores for each session
Ranks Results: Returns the top 5 sessions, sorted by relevance

Composite Scoring

Each session receives a composite score based on multiple factors:

Final Score = (best_similarity × 0.40)
            + (avg_similarity × 0.20)
            + (chunk_ratio × 0.05)
            + (recency × 0.25)
            + (chain_quality × 0.10)

Scoring Components:

Best Similarity (40%): Highest similarity score among matched chunks
Average Similarity (20%): Mean similarity across all matched chunks
Chunk Ratio (5%): Proportion of session chunks that matched
Recency (25%): Exponential decay based on session age (30-day half-life)
Chain Quality (10%): Placeholder for future conversation quality metrics (currently 0.5)

Memory Type Boosts:

Sessions containing Claude memory markers receive bonus scores:

PATTERN (e.g., "design pattern", "approach", "architecture"): +5%
WORKING_SOLUTION (e.g., "tested", "verified", "successful"): +8%
WAITING (e.g., "todo", "pending", "in progress"): +2%

These boosts help prioritize sessions with proven solutions and documented patterns.

Troubleshooting

Known Limitations

Large Sessions: Sessions over 1MB may take significantly longer to index. Consider using a timeout-based indexing script for initial setup.
Empty Sessions: Sessions with no parseable messages are skipped automatically.
Claude Code Format: Only Claude Code JSONL format is supported. The parser handles nested message structures with role and content fields.

Common Issues

"No sessions found" error

Cause: Database is empty or hasn't finished initial indexing.

Solutions:

Wait for initial indexing to complete (check ~/.smart-fork/session-registry.json)
Verify session files exist in ~/.claude/
Check logs for indexing errors

Search returns irrelevant results

Cause: Query may be too vague or database needs more sessions.

Solutions:

Use more specific queries with technical terms
Try different phrasing
Use the "Type something else" option to refine
Adjust similarity_threshold in config (lower = more results)

High memory usage

Cause: Embedding model or large batches consuming RAM.

Solutions:

Reduce max_batch_size in config (e.g., to 64 or 32)
Lower max_memory_mb to trigger more aggressive batch sizing
Close other applications to free memory
Enable gc_between_batches if disabled

Slow search performance

Cause: Large database or insufficient resources.

Solutions:

Reduce k_chunks in config (e.g., to 100)
Increase similarity_threshold to filter more aggressively
Check system resources (CPU, RAM, disk I/O)
Consider using a faster machine for large databases

Background indexing not working

Cause: File monitoring may have failed or is disabled.

Solutions:

Check that indexing.enabled is true in config
Verify ~/.claude/ directory exists and is readable
Restart Claude Code to reinitialize the MCP server
Check logs for watchdog errors

Config changes not taking effect

Cause: Configuration is loaded once at startup.

Solutions:

Restart Claude Code after changing config
Verify config file has valid JSON syntax
Check file permissions on ~/.smart-fork/config.json

Performance Tuning

For systems with limited RAM (< 8GB):

{
  "embedding": {
    "batch_size": 16,
    "max_batch_size": 32
  },
  "memory": {
    "max_memory_mb": 1000,
    "gc_between_batches": true
  }
}

For high-performance systems (16GB+ RAM):

{
  "embedding": {
    "batch_size": 64,
    "max_batch_size": 256
  },
  "search": {
    "k_chunks": 300
  },
  "memory": {
    "max_memory_mb": 4000
  }
}

For faster search at the cost of accuracy:

{
  "search": {
    "k_chunks": 100,
    "similarity_threshold": 0.5
  }
}

Privacy & Security

Data Storage

All data is stored locally on your machine:

Vector Database: ~/.smart-fork/vector_db/ (ChromaDB)
Session Registry: ~/.smart-fork/session-registry.json
Configuration: ~/.smart-fork/config.json

No data is ever sent to external servers (except for downloading the embedding model on first run).

Network Security

The REST API server binds exclusively to 127.0.0.1 (localhost)
No external network access is possible
Only processes on your local machine can access the API

Session Privacy

Session files in ~/.claude/ may contain sensitive information
The vector database stores embeddings (semantic representations) but not full text
Session metadata (project, timestamps, chunk counts) is stored in the registry
Preview snippets are generated on-demand from matched chunks

Best Practices

Secure Your Machine: Use full-disk encryption and strong user passwords
Backup Carefully: If backing up ~/.smart-fork/, treat it as sensitive data
Review Before Forking: Check preview snippets to avoid leaking sensitive context
Clean Old Sessions: Periodically delete session files you no longer need
Environment Variables: Avoid storing secrets in sessions (use .env files instead)

Data Deletion

To completely remove Smart Fork data:

# Stop Claude Code first
rm -rf ~/.smart-fork/

This deletes the vector database, session registry, and configuration. Your original session files in ~/.claude/ remain untouched.

Example Usage Scenarios

Scenario 1: Implementing a Similar Feature

Context: You previously built a real-time dashboard with WebSockets. Now you need to add live notifications to a different project.

You: I need to implement real-time notifications with WebSocket.
     Can you help me find my previous work on this?

Claude: [Invokes fork-detect tool automatically]

Fork Detection Results:
⭐ [1] Session abc123 (94% match) - Recommended
   Date: 2026-01-10
   Project: my-dashboard
   Preview: "Set up WebSocket connection with automatic reconnection,
            heartbeat ping/pong, and exponential backoff..."

[2] Session def456 (81% match)
   ...

To fork from the recommended session, run:
Terminal command: claude --resume abc123 --fork-session

You: (paste command in new terminal)
Claude: (continues with full context from the dashboard implementation)

Result: You save 20+ minutes of re-explaining WebSocket setup, reconnection logic, error handling, etc.

Scenario 2: Debugging a Recurring Issue

Context: You fixed a memory leak in your app 3 weeks ago. A similar issue appeared in a different component.

You: I'm seeing a memory leak in React components again.
     Can you find my previous debugging session on this?

Claude: [Invokes fork-detect tool]

Fork Detection Results:
⭐ [1] Session def456 (89% match) - Recommended
   Date: 2025-12-28
   Project: web-app
   Preview: "Identified memory leak caused by missing cleanup in useEffect.
            Added return function to cancel subscriptions and clear intervals..."

To fork from this session, run:
claude --resume def456 --fork-session

You: (pastes command to continue)

Result: Claude remembers the exact debugging approach, tools used, and solution pattern from the previous fix.

Scenario 3: Continuing After Context Limit

Context: You're in a long refactoring session that hit the 200k token limit.

You: I need to continue refactoring the authentication module from my
     previous session. Can you find where I left off?

Claude: [Invokes fork-detect tool]

Fork Detection Results:
⭐ [1] Session ghi789 (98% match) - Recommended
   Date: Today, 2 hours ago
   Project: api-server
   Preview: "Refactoring auth module: completed user service, working on
            token validation. Next: implement refresh token rotation..."

To continue from where you left off, run:
claude --resume ghi789 --fork-session

You: (continues seamlessly)

Result: Seamlessly continue refactoring with all architectural decisions and progress context intact.

Scenario 4: Testing Multiple Approaches

Context: You want to try different UI frameworks for the same feature.

# First approach
You: Find my work on implementing settings page with form validation

Claude: [Shows results, you fork to session with React + Formik]

# Later, try another approach
You: Find that same settings page session again, I want to try
     a different approach

Claude: [Shows same results]

You: Let's fork from that session but use Vue 3 with Vuelidate instead

Result: Test multiple approaches from the same baseline without losing context or duplicating setup work.

Scenario 5: Onboarding to a New Project

Context: A new team member needs to understand your project's patterns.

You: Can you help me understand this project's structure and coding patterns?
     Find any sessions where the architecture was discussed.

Claude: [Invokes fork-detect tool]

Fork Detection Results:
⭐ [1] Session jkl012 (85% match) - Recommended
   Date: 2025-11-15
   Project: api-server
   Preview: "Explained project architecture: 3-tier design with controllers,
            services, and repositories. Error handling uses custom exception
            classes..."

To review this architectural discussion, run:
claude --resume jkl012 --fork-session

Result: New developers can fork from architecture discussions to get context-aware guidance.

Advanced Topics

Manual Session Indexing

To manually trigger indexing of a specific session:

from smart_fork.background_indexer import BackgroundIndexer
from smart_fork.embedding_service import EmbeddingService
from smart_fork.vector_db_service import VectorDBService
from smart_fork.session_registry import SessionRegistry

# Initialize services
embedding_service = EmbeddingService()
vector_db = VectorDBService()
registry = SessionRegistry()

# Create indexer
indexer = BackgroundIndexer(
    embedding_service=embedding_service,
    vector_db=vector_db,
    registry=registry
)

# Index a specific file
indexer.index_file("/path/to/session.jsonl")

Querying the Database Programmatically

from smart_fork.search_service import SearchService

# Initialize search service
search_service = SearchService(
    embedding_service=embedding_service,
    vector_db=vector_db,
    scoring_service=scoring_service,
    registry=registry
)

# Search for sessions
results = search_service.search(
    query="implement user authentication",
    k_chunks=200,
    top_n_sessions=5
)

for result in results:
    print(f"{result.session_id}: {result.score:.2%} - {result.preview[:100]}")

Custom Embedding Models

To use a different embedding model, update your config:

{
  "embedding": {
    "model_name": "sentence-transformers/all-MiniLM-L6-v2",
    "dimension": 384
  }
}

Note: Changing the model requires re-indexing all sessions (the dimension must match).

Database Statistics

Check database statistics:

from smart_fork.vector_db_service import VectorDBService

vector_db = VectorDBService()
stats = vector_db.get_stats()

print(f"Total chunks: {stats['total_chunks']}")
print(f"Total sessions: {stats['total_sessions']}")

Roadmap

Latest Release (v1.0)

All Phase 1-3 features are complete and production-ready:

Phase 1 (MVP): ✅ Complete

Semantic search, background indexing, MCP integration

Phase 2 (Enhancements): ✅ Complete

Progress display, timeout handling, session preview

Phase 3 (Advanced Features): ✅ Complete

Caching, fork history, project filters, temporal search, tagging
Clustering, summarization, diff tool, archiving, VS Code extension

Future Enhancements (v1.1+)

Chain Quality Tracking: Track success rates of forked sessions to improve recommendations
Advanced Search Filters: Boolean operators, regex patterns, metadata filters
Team Features: Shared session libraries with privacy controls
More IDE Plugins: JetBrains, Cursor, other Claude-compatible editors
Session Analytics: Usage patterns, productivity metrics, knowledge graphs
Cloud Sync: Optional encrypted sync across devices (privacy-first)

Want to contribute? See the Contributing section below!

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Areas for contribution:

Additional embedding models support
Performance optimizations
UI/UX improvements
Documentation enhancements
Bug fixes and testing

License

This project is licensed under the MIT License - see the LICENSE file for details.

Troubleshooting? Check the Troubleshooting section above or open an issue.

Questions? Join our discussions or reach out on GitHub.

Available Tools

13 tools

add-session-tagB

Add a tag to a session for organization and categorization

ParametersJSON Schema

Name	Required	Description	Default
`session_id`	Yes	The session ID to tag
`tag`	Yes	Tag name (will be normalized to lowercase)

TDQS

B3.2/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description bears full burden. It does not disclose key behaviors like whether adding an existing tag is idempotent or duplicates, or any side effects. Normalization is only mentioned in the parameter schema, not the description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence with no redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple mutation tool with no output schema and no annotations, the description lacks critical details such as idempotency, error conditions, and prerequisites. It is insufficient for an agent to use correctly without additional inference.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already defines both parameters. The description adds no extra meaning beyond what is in the schema, warranting a baseline score of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action 'Add a tag to a session' and the purpose 'for organization and categorization'. It distinguishes from sibling tools like remove-session-tag and list-session-tags.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool vs alternatives (e.g., remove-session-tag). No prerequisites (e.g., session existence) or conditions for effective use are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

cluster-sessionsB

Automatically cluster sessions by topic using k-means on session embeddings

ParametersJSON Schema

Name	Required	Description	Default
`num_clusters`	No	Number of clusters to create (default: 10, auto-adjusted based on available sessions)

TDQS

B3.1/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided. The description does not disclose whether clustering is idempotent, overwrites previous results, or requires pre-existing embeddings. Lack of behavioral details.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, no wasted words. Could be more structured but efficient. Lacks bullet points or formatting.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema, missing details on return value or side effects. Does not explain prerequisites (e.g., sessions must have embeddings). Incomplete for a clustering tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and describes 'num_clusters' with default and auto-adjustment. The description adds no further meaning beyond the schema. Baseline 3 appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool clusters sessions by topic using k-means on embeddings. It distinguishes from siblings like 'get-session-clusters' which retrieves existing clusters.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives such as 'get-session-clusters' or 'get-similar-sessions'. Preconditions or side effects are not mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

compare-sessionsA

Compare two sessions to identify common content, unique messages, and differences in topics/technologies

ParametersJSON Schema

Name	Required	Description
`session_id_1`	Yes	First session ID to compare
`session_id_2`	Yes	Second session ID to compare
`include_content`	No	Whether to include message content snippets in the output (default: false)

TDQS

A3.5/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden. It does not disclose behavioral traits such as whether the operation is read-only, destructive, or requires authentication. The description only covers purpose, not side effects or constraints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that encapsulates the core purpose without extraneous words. It is front-loaded with the key action and resource. Slightly more structure (e.g., listing outputs) could improve scannability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description provides a reasonable overview of expected returns (common content, unique messages, differences). It covers the main aspects but could be more detailed about the format or limitations. For a comparison tool with 3 simple parameters, it is mostly complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents parameters adequately. The description adds no further parameter meaning beyond what is in the schema, but the parameter descriptions are clear. Description mentions output aspects but not parameter usage details.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (compare), the resource (two sessions), and the specific outputs (common content, unique messages, differences in topics/technologies). It distinguishes from sibling tools like cluster-sessions or get-similar-sessions by specifying the exact comparative analysis.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use (when needing to compare sessions), but does not explicitly state when not to use or provide alternatives. Without explicit guidance, the agent must infer usage context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

fork-detectB

Search for relevant past Claude Code sessions to fork from

ParametersJSON Schema

Name	Required	Description
`query`	Yes	Natural language description of what you want to do
`project`	No	Optional project name to filter results. Use 'current' to auto-detect from working directory, or specify a project name explicitly.
`scope`	No	Search scope: 'all' searches all sessions (default), 'project' searches only current project
`time_range`	No	Predefined time range (today, yesterday, this_week, last_week, this_month, last_month, this_year) or natural language ('last Tuesday', '2 weeks ago', '3d')
`start_date`	No	Custom start date for filtering (ISO format: 2026-01-01 or natural language)
`end_date`	No	Custom end date for filtering (ISO format: 2026-01-21 or natural language)
`tags`	No	Optional comma-separated list of tags to filter results (e.g., 'bug-fix,urgent' or 'react'). Sessions must have at least one matching tag.
`include_archive`	No	Whether to include archived sessions in search results (default: false)

TDQS

B3.3/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description bears full burden. It discloses the search purpose but omits behavioral details: whether the search is read-only, how results are sorted, pagination, or what 'relevance' means. Eight parameters suggest complexity not addressed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence is concise and front-loaded with the verb, but could be slightly more informative without becoming verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 8 parameters and no output schema, the description is too minimal. It doesn't explain what a 'fork' is, how sessions are matched, or what the output format or behavior of the search entails.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3. The description adds no extra meaning beyond the schema; 'relevant' is vague and does not clarify how query matches sessions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states verb ('Search') and resource ('past Claude Code sessions to fork from'), which distinguishes it from sibling tools like 'get-session-preview' or 'record-fork' that focus on different aspects of sessions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'to fork from' implies the usage context (finding sessions to fork), but no explicit guidance on when to use this tool versus alternatives like 'get-similar-sessions' or 'cluster-sessions', nor any when-not conditions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get-cluster-sessionsB

Get all sessions in a specific cluster

ParametersJSON Schema

Name	Required	Description	Default
`cluster_id`	Yes	Cluster ID to retrieve sessions for

TDQS

B3.1/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. Only states 'Get all sessions' but does not explicitly confirm that it is read-only or disclose any side effects, rate limits, or other behavioral traits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, no filler, front-loaded with purpose. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool is simple with 1 parameter and no output schema, so description is minimally adequate. However, given many sibling tools, more context on what differentiates this tool would improve completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema covers cluster_id with 100% description coverage. Description adds 'all sessions' scope, which is not in schema, but does not provide additional context like return format or pagination.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states verb 'Get' and resource 'all sessions in a specific cluster'. However, it does not differentiate from sibling tool 'cluster-sessions' which might perform a similar function.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives like 'cluster-sessions' or 'get-session-clusters'. No exclusions or prerequisites mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get-fork-historyC

Get history of recently forked sessions

ParametersJSON Schema

Name	Required	Description	Default
`limit`	No	Maximum number of history entries to return (default: 10)

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must fully disclose behavior. It implies a read-only operation but does not mention whether the history includes deleted sessions, the ordering (e.g., most recent first), or if access permissions are required. The short description leaves ambiguity about side effects and data freshness.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single clear sentence with no wasted words. It conveys the core purpose efficiently. However, it could benefit from a brief structured overview of the return value or behavior.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of an output schema, the description should indicate what the returned history contains (e.g., session IDs, timestamps). It does not, leaving the agent uncertain about the data shape. For a tool with one parameter and no output schema, this is a notable gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single parameter 'limit' is fully documented in the schema with a description and default value. The tool description does not add any additional semantics beyond what the schema provides, which is acceptable given the high schema coverage (100%).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves 'history of recently forked sessions', specifying both the action (get) and the resource (history of forked sessions). It distinguishes from sibling tools like 'record-fork' which creates forks, and 'get-similar-sessions' which retrieves similar sessions rather than fork history.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives like 'record-fork' or 'get-session-summary'. The description lacks context such as prerequisites, typical use cases, or exclusion criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get-session-clustersB

Get all session clusters and their metadata

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

B3.2/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden. 'Get all' implies a read operation, but no further traits are disclosed (e.g., authorization, rate limits, or side effects). The minimal description does not add value beyond the tool name.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, clear sentence with no wasted words. It effectively communicates the tool's purpose in a front-loaded manner.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple parameterless retrieval, the description is arguably adequate but lacks detail on what 'metadata' encompasses. Given the presence of sibling tools like 'cluster-sessions' and 'get-cluster-sessions', more context would help an agent choose correctly. The lack of an output schema further reduces completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are no parameters in the input schema (0 params, 100% coverage). The description correctly adds nothing about parameters since none exist. Baseline 4 is appropriate as there is no additional semantic burden.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Get' and the resource 'all session clusters and their metadata'. It distinguishes from siblings like 'get-cluster-sessions' (which likely returns individual sessions in a cluster) by focusing on clusters themselves. However, it does not explicitly differentiate from other cluster-related tools like 'cluster-sessions'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives. The description does not mention any context, exclusions, or prerequisites. For example, it does not clarify whether to use this before 'cluster-sessions' or 'get-cluster-sessions'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get-session-previewB

Get a preview of a session's content before forking

ParametersJSON Schema

Name	Required	Description	Default
`session_id`	Yes	The session ID to preview
`length`	No	Maximum preview length in characters (default: 500)

TDQS

B3.3/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose behavioral traits. It only states it provides a preview but does not explain what the preview contains (e.g., truncated text, format), side effects, or access requirements. This is minimal disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence of 7 words, front-loaded with the verb and resource, no extra words. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema or annotations. The description gives the purpose but lacks details on return format or content of the preview. For a simple tool it is adequate but not complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Both parameters have descriptions in the schema, so schema coverage is 100%. The description adds no new meaning beyond the schema for the parameters. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the specific verb 'get' and resource 'preview of a session's content', and adds the context 'before forking', which distinguishes it from sibling tools like 'get-session-summary' and 'get-cluster-sessions'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage 'before forking' but does not explicitly state when to use this tool vs alternatives like 'get-session-summary', nor does it provide when-not-to-use guidance or compare to siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get-session-summaryA

Get a quick summary of a session's content without reading the full session

ParametersJSON Schema

Name	Required	Description	Default
`session_id`	Yes	The session ID to get summary for

TDQS

A3.6/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose behavioral traits. It states 'quick summary' but does not specify return format, whether it's a read-only operation, or any performance implications. Minimal behavioral context beyond the core function.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, 14 words, front-loaded with the core action. Every word adds value. No redundant or missing elements. Highly efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one parameter and no output schema, the description adequately covers the purpose and basic behavior. It could mention the output format or limitations for completeness, but given the low complexity, it is sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The only parameter, session_id, is fully described in the schema (100% coverage). The description adds context that the summary is 'quick' and avoids reading the full session, which provides some added meaning beyond the schema, but not significantly more.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the verb 'Get', the resource 'summary of a session's content', and distinguishes from siblings like 'get-session-preview' by emphasizing 'quick' and 'without reading the full session'. It is specific and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies using this tool for a quick overview, but does not provide explicit guidance on when to choose it over alternatives like 'get-session-preview' or 'get-similar-sessions'. No exclusions or when-not-to-use are given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get-similar-sessionsB

Find sessions similar to a given session (for detecting duplicates or related work)

ParametersJSON Schema

Name	Required	Description
`session_id`	Yes	Session ID to find similar sessions for
`top_k`	No	Maximum number of similar sessions to return (default: 5)
`include_scores`	No	Whether to include similarity scores in output (default: true)

TDQS

B3.4/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden for behavioral disclosure. It only states the purpose, omitting any details about how similarity is computed, side effects (presumably read-only), or constraints like performance. This is insufficient for an agent to understand the tool's behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that front-loads the action and purpose. Every word adds value, and there is no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite low complexity, the description fails to explain the return format, pagination (top_k), or what 'similar' means. Without an output schema, the description should cover these aspects to be complete. Sibling tool differentiation is absent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, with each parameter having a description in the schema. The tool description does not add any parameter information beyond what the schema already provides, so the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool finds sessions similar to a given session, with a specific use case for duplicates or related work. It uses a specific verb and resource, and it distinguishes from siblings like compare-sessions and cluster-sessions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for detecting duplicates or related work, but it does not explicitly say when to use this tool over alternatives. No exclusions or when-not-to-use guidance are provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list-session-tagsB

List tags for a session or all tags in the system

ParametersJSON Schema

Name	Required	Description	Default
`session_id`	No	Optional session ID to list tags for. If not provided, lists all tags.
`show_all`	No	If true, shows all tags with counts. If false, shows top tags only. (default: false)

TDQS

B3.4/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, so the description bears full responsibility for behavioral disclosure. It only says 'list tags' without explaining return format, pagination, authentication needs, or whether it shows counts (only the schema's show_all mentions counts). This is insufficient for a tool with no output schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single clear sentence, concise and front-loaded. However, it could be slightly more structured (e.g., split into two conditions). Minimal waste, earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple list tool with two optional parameters and no output schema, the description provides the core functionality but omits details like return format or behavior of 'show_all' beyond schema. It is minimally adequate but not fully comprehensive.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description repeats the schema's info for session_id (optional, lists all if missing) but adds nothing new. For show_all, the description does not elaborate on 'counts' or 'top tags', leaving that solely to schema. No added value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('List') and the resource ('tags'), and distinguishes from sibling tools like add-session-tag and remove-session-tag, which are modifications. The alternative 'all tags' vs 'for a session' is also clear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit when-to-use or when-not-to-use guidance is provided. However, the description implies that this tool is for viewing tags, and the sibling names naturally indicate add/remove for modifications. A higher score would require explicit alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

record-forkB

Record a fork event for history tracking (internal tool, usually auto-called)

ParametersJSON Schema

Name	Required	Description
`session_id`	Yes	The session ID that was forked
`query`	Yes	The query that led to this fork
`position`	No	Result position (1-5 for displayed results, -1 for custom)

TDQS

B3.4/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It only states the action without disclosing side effects, auth requirements, or error behavior, leaving the agent with minimal behavioral insight.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence with a parenthetical clarification. It is front-loaded and efficient, though it could better separate purpose from context.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple recording tool with well-documented required parameters and internal nature, the description is minimally adequate. However, it lacks details on return values or confirmation of success, which could be helpful.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds no extra meaning beyond the schema; it simply restates the tool's purpose without elaborating on parameter usage or constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'record' and resource 'fork event', with purpose 'for history tracking'. It also distinguishes from siblings by noting it's an internal tool usually auto-called, which contrasts with tools like fork-detect.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides implicit usage context ('internal tool, usually auto-called') but lacks explicit guidance on when to use this tool versus alternatives, such as when not to use it or prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

remove-session-tagC

Remove a tag from a session

ParametersJSON Schema

Name	Required	Description	Default
`session_id`	Yes	The session ID to remove tag from
`tag`	Yes	Tag name to remove (case-insensitive)

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided. The description does not disclose behavioral traits such as whether removal is permanent, what happens if the tag does not exist, or any other side effects. Schema mentions case-insensitivity but description adds nothing.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise, using one sentence with no wasted words. However, it could be slightly more informative without losing conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool, the description is minimal but lacks crucial behavioral context (e.g., idempotency, error handling). Given no annotations and no output schema, more completeness is needed to guide the agent effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, with both parameters described clearly. The description adds no additional meaning beyond the schema, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly specifies the verb 'Remove' and the resource 'tag from a session', distinguishing it from sibling tools like add-session-tag. It is straightforward and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool vs alternatives. No mention of prerequisites, error states, or when not to use it. The description is too brief to provide usage context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

13 tool updatesv0.1.0Jun 21, 2026
- First observedadd-session-tag
- First observedcluster-sessions
- First observedcompare-sessions
- First observedfork-detect
- First observedget-cluster-sessions
- First observedget-fork-history
- First observedget-session-clusters
- First observedget-session-preview
- First observedget-session-summary
- First observedget-similar-sessions
- First observedlist-session-tags
- First observedrecord-fork
- First observedremove-session-tag

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.6/5.0

Disambiguation5/5

Each tool targets a distinct operation: tags (add/remove/list), clustering (cluster/get-cluster-sessions/get-session-clusters), forking (detect/record/history), and session details (preview/summary/compare/similar). No two tools have overlapping purposes.

Naming Consistency5/5

All tools use a consistent kebab-case verb-noun pattern, e.g., add-session-tag, cluster-sessions, get-fork-history. The style is uniform and predictable.

Tool Count5/5

With 13 tools, the server covers the core workflows of session forking, clustering, tagging, and comparison without being bloated or sparse.

Completeness4/5

The tool surface covers the main lifecycle: fork detection, recording, history, preview, summary, clustering, tagging, and comparison. A minor gap is the lack of a direct list-all-sessions tool, but sessions can be accessed through clusters or similarity.

Maintenance

ActivityInactive

ResponsivenessSyncing

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

nexsusOAuth
io.github.dbnexsus
Private persistent memory for Claude, ChatGPT & Gemini via MCP - semantic search, zero-code setup.
Knowledge & Memory RAG Systems
2
mcp
dev.augments
Augments MCP Server - A comprehensive framework documentation provider for Claude Code
Developer Tools Documentation Access
2128
Palim A
io.github.joleschmidt
Hosted MCP memory: save sessions/decisions once, search from Claude, Cursor, ChatGPT. EU-hosted FTS.
Knowledge & Memory Search RAG Systems
92
mcpOAuth
ai.butlerbrain
Persistent memory for AI assistants. Save once; recall from Claude, ChatGPT, or any MCP client.
Knowledge & Memory RAG Systems Workplace & Productivity
2

Related MCP Servers

Claude Historian
Developer Tools Code Execution Knowledge & Memory
Vvkmnn
A
license
B
quality
D
maintenance
MCP server that lets you search your Claude Code conversation history to find past solutions, track file changes, and learn from previous work.
Updated 3 months ago (2026-06-15 09:09 UTC)
8
95
178
MIT
ClaudeHistoryMCP
Knowledge & Memory Search Developer Tools
jhammant
A
license
A
quality
D
maintenance
An MCP server that makes Claude Code conversation history searchable and proactively useful by indexing past sessions with hybrid BM25+TF-IDF search, extracting decisions and solutions, and auto-injecting relevant project context at session start.
Updated 6 months ago (2026-02-27 17:15 UTC)
9
12
65
MIT
transcript-search
RAG Systems Vector Databases Search
ttrine
F
license
A
quality
D
maintenance
A semantic search system for Claude Code transcript history, exposed as an MCP server so Claude Code can query its own past sessions.
Updated 7 months ago (2026-02-04 21:40 UTC)
2
-
engram-mcp
Search Knowledge & Memory
lowbridgee
A
license
Not graded
quality
D
maintenance
An MCP server that enables semantic and keyword search over Claude Code conversation history stored locally, using hybrid search, local embeddings, and time-decay scoring.
Updated 5 months ago (2026-03-26 15:33 UTC)
26
MIT

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/recursive-vibe/smart-fork'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

Smart Fork Detection

Overview

Features

Core Capabilities

Performance & Intelligence

Organization & Analysis

Integrations

Table of Contents

Installation

Prerequisites

Install from Source

Install from PyPI (coming soon)

Verify Installation

Configure Claude Code MCP

Quick Start

Usage

Using the fork-detect Tool

Selecting a Session

Forking a Session

Configuration

Configuration Options

Embedding Model Settings

Search Parameters

Chunking Settings

Background Indexing

Timeout Handling

Server Settings

Memory Management

Storage Directory

Configuration File

How It Works

Background Indexing

Semantic Search

Composite Scoring

Troubleshooting

Known Limitations

Common Issues

"No sessions found" error

Search returns irrelevant results

High memory usage

Slow search performance

Background indexing not working

Config changes not taking effect

Performance Tuning

Privacy & Security

Data Storage

Network Security

Session Privacy

Best Practices

Data Deletion

Example Usage Scenarios

Scenario 1: Implementing a Similar Feature

Scenario 2: Debugging a Recurring Issue

Scenario 3: Continuing After Context Limit

Scenario 4: Testing Multiple Approaches

Scenario 5: Onboarding to a New Project

Advanced Topics

Manual Session Indexing

Querying the Database Programmatically

Custom Embedding Models

Database Statistics

Roadmap

Latest Release (v1.0)

Future Enhancements (v1.1+)

Contributing

License

Available Tools

Tool Schema Changelog

Maintenance

Resources

Looking for Admin?

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API