AI Integration

This guide explains how to integrate Phantom with AI assistants using the Model Context Protocol (MCP) for enhanced development workflows.

Table of Contents

• Overview
• What is MCP?
• Supported AI Assistants
• Available Tools
• Setup
• Usage Examples
• Advanced Workflows
• Troubleshooting

Overview

Phantom v2.0 provides AI assistant integration through MCP (Model Context Protocol), enabling AI assistants to directly manage phantom worktrees and development workflows.

Key Benefits

• Direct Phantom Management: AI can create, list, and delete phantoms
• GitHub Integration: AI can checkout PRs and issues automatically
• Seamless Workflow: Natural language commands for complex operations
• Safe Environment: Controlled operations through MCP protocol
• Multiple AI Support: Works with Claude Desktop, Cursor, and other MCP clients

What is MCP?

Model Context Protocol (MCP) is a standardized way for AI assistants to securely access local tools and resources.

MCP Advantages

1. Security: Explicit permission management
2. Standardization: Unified tool interface across AI assistants
3. Extensibility: Easy addition of new capabilities
4. Transparency: All operations are logged and traceable

Supported AI Assistants

Claude Desktop

• Status: Full support
• Setup: Configuration via claude_desktop_config.json
• Features: All phantom tools available

Cursor

• Status: Full support
• Setup: Configuration via settings
• Features: Integrated development environment with phantom management

Other MCP Clients

• Status: Compatible with any MCP client
• Setup: Standard MCP server configuration
• Features: All tools available through MCP protocol

Available Tools

Phantom's MCP server provides 4 tools for AI assistants:

1. phantom_create_worktree

Creates a new phantom worktree.

Parameters:

• name (string, required): Phantom name
• baseBranch (string, optional): Base branch

Example:

{
  "name": "phantom_create_worktree",
  "arguments": {
    "name": "feature-ai-integration",
    "baseBranch": "develop"
  }
}

2. phantom_list_worktrees

Lists all existing phantom worktrees.

Parameters: None

Returns: Information about all phantoms (name, branch, path)

3. phantom_delete_worktree

Deletes a specified phantom worktree.

Parameters:

• name (string, required): Phantom name to delete
• force (boolean, optional): Force deletion

Example:

{
  "name": "phantom_delete_worktree",
  "arguments": {
    "name": "completed-feature",
    "force": false
  }
}

4. phantom_github_checkout

Checks out a GitHub PR or issue to a phantom worktree.

Parameters:

• number (string, required): PR or issue number
• base (string, optional): Base branch for issues

Example:

{
  "name": "phantom_github_checkout",
  "arguments": {
    "number": "123",
    "base": "main"
  }
}

Setup

Claude Desktop Setup

macOS Configuration

Edit the configuration file:

~/Library/Application Support/Claude/claude_desktop_config.json

Windows Configuration

Edit the configuration file:

%APPDATA%\Claude\claude_desktop_config.json

Configuration Content

{
  "mcpServers": {
    "phantom": {
      "command": "phantom",
      "args": ["mcp", "start"]
    }
  }
}

Cursor Setup

Add to Cursor settings:

{
  "mcp.servers": {
    "phantom": {
      "command": "phantom",
      "args": ["mcp", "start"]
    }
  }
}

Verification

Test the MCP server manually:

# Start MCP server
phantom mcp start

# In another terminal, verify phantom works
phantom list

Usage Examples

Basic Phantom Management

User: Create a new phantom for feature development

AI: I'll create a new phantom worktree for feature development.

[Executes phantom_create_worktree]
- Name: "feature-development"
- Base: current branch

Phantom worktree "feature-development" has been created successfully.

GitHub PR Review

User: I need to review PR #456

AI: I'll check out PR #456 into a phantom worktree for review.

[Executes phantom_github_checkout]
- PR number: "456"

Phantom "pulls/456" has been created with the PR code checked out.
You can now review the changes.

Workflow Automation

User: Set up phantoms for the three highest priority bugs

AI: I'll check your issue tracker and set up phantoms for the top bugs.

[Executes multiple phantom_github_checkout calls]
1. Created phantom for issue #789 (high priority memory leak)
2. Created phantom for issue #790 (critical security bug) 
3. Created phantom for issue #791 (performance regression)

All three bug phantoms are ready for investigation.

Cleanup Management

User: Clean up any completed phantoms

AI: Let me check current phantoms and clean up completed ones.

[Executes phantom_list_worktrees]
[Analyzes phantom status]
[Executes phantom_delete_worktree for completed phantoms]

Cleaned up 3 completed phantoms:
- "feature-auth" (merged to main)
- "bugfix-login" (deployed to production)
- "experiment-cache" (no longer needed)

Advanced Workflows

AI Pair Programming

User: Help me implement user authentication with proper testing

AI: I'll set up a development environment and guide you through implementing authentication.

[Creates phantom for auth feature]
[Sets up testing environment]  
[Guides through implementation]
[Helps write tests]
[Assists with code review]

Complete authentication system implemented with:
- Secure login/logout
- Password hashing
- Session management
- Comprehensive tests

Multi-Feature Development

User: I need to work on frontend, backend, and mobile simultaneously

AI: I'll create separate phantoms for each platform to enable parallel development.

[Creates phantom "frontend-updates"]
[Creates phantom "backend-api"]
[Creates phantom "mobile-features"]

Three development environments ready:
- Frontend phantom with React dev server
- Backend phantom with API server
- Mobile phantom with React Native setup

You can now develop all three platforms in parallel.

Release Preparation

User: Prepare for v2.1.0 release

AI: I'll help prepare the release by setting up testing and validation environments.

[Creates phantom "release-v2.1.0"]
[Sets up integration testing]
[Runs full test suite]
[Validates documentation]
[Prepares changelog]

Release v2.1.0 preparation complete:
- All tests passing
- Documentation updated
- Changelog generated
- Ready for deployment

Advanced Configuration

Project-Specific AI Workflows

Use phantom.config.json to customize AI-assisted development:

{
  "worktreesDirectory": "../ai-phantoms",
  "postCreate": {
    "copyFiles": [".env.ai", "ai-config.json"],
    "commands": [
      "npm install",
      "npm run setup:ai",
      "echo 'AI phantom ready!'"
    ]
  },
  "preDelete": {
    "commands": [
      "npm run ai:cleanup",
      "docker-compose down"
    ]
  }
}

AI Assistant Integration

Configure automatic phantom management:

{
  "ai": {
    "autoCleanup": true,
    "maxPhantoms": 10,
    "defaultBaseBranch": "develop",
    "experimentalFeatures": true
  }
}

Troubleshooting

Common Issues

MCP Server Not Starting

# Check phantom installation
phantom --version

# Verify MCP command
phantom mcp start --debug

# Check logs
tail -f ~/.local/share/phantom/mcp.log

AI Assistant Not Recognizing Tools

1. Restart AI assistant application
2. Verify configuration file syntax
3. Check file paths are correct
4. Test MCP server manually

Permission Errors

# Check phantom permissions
ls -la $(which phantom)

# Verify repository access
git status
phantom list

Debug Mode

Enable debug logging:

phantom mcp start --debug

Check configuration:

# Claude Desktop
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Cursor  
cat ~/.cursor/mcp-config.json

Best Practices

Security Considerations

1. Limited Scope: MCP tools only perform safe phantom operations
2. No Remote Changes: Local worktree management only
3. Explicit Confirmation: Destructive operations require confirmation
4. Audit Trail: All operations are logged

Workflow Optimization

1. Clear Instructions: Give AI specific, actionable requests
2. Context Sharing: Provide relevant project context
3. Regular Cleanup: Ask AI to clean up unused phantoms
4. Batch Operations: Group related requests for efficiency

Integration Tips

1. Start Simple: Begin with basic phantom operations
2. Build Gradually: Add complexity as you become comfortable
3. Document Workflows: Save successful AI interaction patterns
4. Team Standards: Establish common AI workflow practices

Next Steps

• Explore GitHub Integration: Use GitHub Integration with AI
• Advanced Configuration: Set up project-specific AI workflows
• Team Adoption: Share AI integration patterns with your team
• Feedback: Report AI integration experiences to improve the tools

AI integration transforms how you work with phantom worktrees, making complex development workflows feel natural and efficient through conversational interfaces.