Context Tools Plugin - Usage Guide

Dynamic Directory Support (v0.8.0+)

GOOD NEWS: MCP tools automatically adapt to the current working directory!

How it works:

cd /home/user/project-a
# MCP tools query/index project-a/.claude/repo-map.db

cd /home/user/project-b
# MCP tools now query/index project-b/.claude/repo-map.db ✅

Behavior:

• Tools check current working directory on each call
• If .claude/repo-map.db exists: query it
• If not: trigger indexing for current directory
• Logs show which directory is being queried

Benefits:

• No need to restart session when changing projects
• Can work with multiple projects in one session
• Each project maintains its own index
• Tools "just work" wherever you are

Plugin Installation and Updates

CRITICAL: When the user runs /plugin install or /plugin update:

The MCP server configuration changes immediately, but the MCP server itself does not restart automatically. The new plugin features (especially MCP tools like search_symbols) will NOT be available until the session restarts.

YOU MUST tell the user:

The plugin has been installed/updated successfully. To use the MCP tools (search_symbols, get_file_symbols, etc.), you need to restart the session:

1. Exit this session (Ctrl+C or type 'exit')
2. Start a new session with: claude continue

The MCP server will restart with the new plugin configuration.

When to give this instruction:

• Immediately after the user runs /plugin install context-tools
• Immediately after the user runs /plugin update context-tools
• When the user tries to use MCP tools but they're not available (and you suspect they just installed)

Why this matters:

• MCP servers are started when Claude Code starts
• Plugin installation modifies MCP server configuration
• Changes only take effect on next Claude Code startup
• Users will be confused if tools don't work after installation

Available MCP Tools

Once the session has been restarted after installation, the following MCP tools are available:

mcp__repo-map__search_symbols

Search for symbols (functions, classes, methods) by name pattern.

Faster than Grep/Search - uses pre-built SQLite index.

Parameters:

• pattern (required): Glob pattern like get_*, *Handler, Config*
• kind (optional): Filter by "class", "function", or "method"
• limit (optional): Max results (default: 20)

Example:

{
  "pattern": "parse_*",
  "kind": "function",
  "limit": 10
}

mcp__repo-map__get_file_symbols

Get all symbols defined in a specific file.

Parameters:

• file (required): Relative path from project root (e.g., "src/models/user.py")

mcp__repo-map__get_symbol_content

Get the source code content of a symbol by exact name.

Faster than Grep/Search+Read - directly retrieves function/class source code.

Parameters:

• name (required): Exact symbol name (e.g., "MyClass", "User.save")
• kind (optional): Filter by type if name is ambiguous

mcp__repo-map__reindex_repo_map

Trigger a reindex of the repository symbols.

Parameters:

• force (optional): Force reindex even if cache is fresh (default: false)

mcp__repo-map__repo_map_status

Get the current status of the repo map index.

Shows:

• Index status: idle, indexing, completed, or failed
• Symbol count
• Last indexed time
• Whether index is stale
• Indexing errors (if any)

mcp__repo-map__wait_for_index

Wait for indexing to complete.

Parameters:

• timeout_seconds (optional): How long to wait (default: 60)

Note: Most tools automatically wait for indexing to complete, so this is rarely needed.

Database Schema (.claude/repo-map.db)

symbols table:

• name (TEXT): Symbol name
• kind (TEXT): class, function, or method
• file_path (TEXT): Relative path from project root
• line_number (INTEGER): Start line (1-indexed)
• end_line_number (INTEGER): End line (nullable)
• parent (TEXT): Parent class/module (nullable)
• docstring (TEXT): First line of docstring (nullable)
• signature (TEXT): Function/method signature (nullable)
• language (TEXT): python, cpp, or rust

metadata table (v0.7.0+):

• key (TEXT PRIMARY KEY): Metadata key
• value (TEXT): Metadata value

Keys:

• status: idle | indexing | completed | failed
• index_start_time: ISO8601 timestamp when indexing started
• last_indexed: ISO8601 timestamp when last completed
• symbol_count: Total symbols indexed (string)
• error_message: Error message if status='failed'

Indexing Status and Auto-Wait (v0.7.0+)

First Use Behavior:

• On first use, indexing starts automatically in background
• Tools automatically wait (up to 60s) if indexing is in progress
• If timeout, tools return helpful error asking user to retry

Watchdog (v0.7.0+):

• Detects hung indexing processes (>10 minutes)
• Automatically resets status to 'failed'
• Can be manually recovered with reindex_repo_map

Multiprocess Architecture (v0.8.0+):

• Indexing runs in separate subprocess
• MCP server remains responsive even if indexing hangs
• Watchdog can kill hung subprocess without affecting MCP server
• Resource limits (Unix/macOS): 4GB memory, 20 min CPU time

When to Use MCP Tools vs Other Tools

Use MCP repo-map tools when:

• Searching for symbols by name pattern (faster than Grep)
• Getting all symbols in a file (faster than Read + parsing)
• Getting source code of a specific function/class (faster than Grep + Read)
• Need to search across multiple languages (Python, C++, Rust)

Use other tools when:

• Searching file contents (not symbol names) - use Grep
• Reading entire files - use Read
• Need to search files that aren't Python/C++/Rust
• Searching for non-code patterns (comments, strings, etc.)

Project-Specific Files

Automatically generated at session start:

• .claude/project-manifest.json - Project structure and build commands
• .claude/repo-map.md - Human-readable code structure with duplicate detection
• .claude/repo-map.db - SQLite database for fast symbol queries (MCP server)

Optional (created manually):

• .claude/learnings.md - Project-specific learnings and discoveries

Logs:

• .claude/logs/repo-map-server.log - MCP server rotating log (1MB per file, 3 backups)
  • Tool calls and results
  • Indexing events and performance
  • Watchdog actions and resource limit violations
  • Server startup/shutdown
• Session start hook outputs are also logged for debugging