What is Claude Desktop Multi Instance

claude-desktop-multi-instance is a tool that allows users to run multiple instances of the Claude Desktop application simultaneously on macOS, each with its own independent configurations, accounts, and MCP server settings.

Use cases

Use cases include running separate instances for work and personal use, testing different configurations without interference, and facilitating collaboration by allowing multiple users to access different instances on the same machine.

How to use

To use claude-desktop-multi-instance, clone the repository from GitHub, navigate to the project directory, and follow the setup instructions provided in the README. You can launch different instances using Spotlight search or directly from the Launchpad.

Key features

Key features include multi-instance management, custom display names for each instance in the Dock, independent configurations for each instance, app wrappers for easy access, Spotlight integration for quick launching, smart diagnostics for troubleshooting, and a user-friendly interface.

Where to use

claude-desktop-multi-instance is ideal for users who need to manage multiple accounts or configurations of the Claude Desktop application, such as professionals balancing work and personal accounts, or developers testing different setups.

Claude Desktop Multi-Instance Launcher

🚀 Run multiple Claude Desktop instances simultaneously on macOS with independent configurations, accounts, and MCP server settings

📖 Documentation Language / 文档语言:

• English: You are reading the English version
• 中文: 中文文档 (Chinese Documentation)

📸 Screenshots

Multi-Window Running Effect

Spotlight Search Integration

Use Spotlight (⌘+Space) to quickly find and launch different Claude instances. Each app wrapper shows up as a separate application that maintains its login state and configuration.

Custom Display Names in Dock

When hovering over icons in the Dock, each instance displays its own custom name instead of just “Claude”

✨ Features

• 🔄 Multi-Instance Management - Run multiple independent Claude Desktop instances on the same machine
• 🏷️ Custom Display Names - Show different app names in Dock (e.g., “Claude Work”, “Claude Personal”)
• ⚙️ Independent Configurations - Each instance has its own MCP server config and login credentials
• 📱 App Wrappers - Create independent app icons for direct Launchpad access
• 🔍 Spotlight Integration - Find and launch instances quickly using Spotlight search (⌘+Space)
• 🛠️ Smart Diagnostics - Built-in problem diagnosis and repair tools
• 💡 User-Friendly - Both interactive menu and command-line interfaces

📋 System Requirements

• macOS 11 (Big Sur) or later
• Claude Desktop app (download from claude.ai/download)
• Bash shell (built into macOS)

🚀 Quick Start

1. Download and Setup

# Clone the repository
git clone https://github.com/weidwonder/claude-desktop-multi-instance.git
cd claude-desktop-multi-instance

# Make script executable
chmod +x claude_quick.sh

Or download the script directly:

# Download single script file
curl -O https://raw.githubusercontent.com/weidwonder/claude-desktop-multi-instance/main/claude_quick.sh
chmod +x claude_quick.sh

2. First Use

# Run script to show menu
./claude_quick.sh

# Or directly create and launch an instance
./claude_quick.sh work

📖 Usage Guide

Interactive Menu Mode

Run ./claude_quick.sh to display the menu:

======================================
    Claude Desktop Quick Launcher
======================================

Available options:
1. Launch default instance
2. Select existing instance
3. Create new instance
4. Delete specified instance
5. Create app wrapper (independent icon)
6. Restore original configuration
7. Diagnose problems
8. Fix wrappers

Command Line Mode

# Launch or create instance
./claude_quick.sh [instance_name]

# Management commands
./claude_quick.sh list                 # List all instances
./claude_quick.sh delete [instance]    # Delete instance
./claude_quick.sh wrapper [instance]   # Create app wrapper
./claude_quick.sh diagnose             # Diagnose problems
./claude_quick.sh fix                  # Fix wrappers
./claude_quick.sh restore              # Restore original config

💼 Use Cases

Scenario 1: Separate Work and Personal Accounts

# Create work instance
./claude_quick.sh work
# Login with work account, configure work-related MCP servers

# Create personal instance
./claude_quick.sh personal
# Login with personal account, configure personal MCP servers

Scenario 2: Different Project Configurations

# Project A - with filesystem and web search MCP
./claude_quick.sh project-a

# Project B - with database and API MCP
./claude_quick.sh project-b

# Development environment - with Git and testing tools MCP
./claude_quick.sh dev

Scenario 3: Create App Wrappers

# Create independent app icon for work instance
./claude_quick.sh wrapper work
# Enter display name: Claude Work

# Now you can launch "Claude Work" directly from Launchpad or Spotlight
# It will show as "Claude Work" instead of "Claude" in Dock
# Each wrapper maintains its own login state and configuration

📁 File Structure

~/.claude-instances/                    # Instance data directory
├── work/                              # Work instance
│   └── Application Support/Claude/
│       └── claude_desktop_config.json
├── personal/                          # Personal instance
│   └── Application Support/Claude/
│       └── claude_desktop_config.json
└── scripts/                           # Helper scripts
    ├── restore.sh                     # Quick restore config
    └── list.sh                        # List all instances

/Applications/                          # App wrappers
├── Claude.app                         # Original app
├── Claude-work.app                    # Work instance wrapper
└── Claude-personal.app                # Personal instance wrapper

🔧 Troubleshooting

Issue: App wrapper won’t launch

Solution:

# 1. Run diagnostics
./claude_quick.sh diagnose

# 2. Fix wrappers
./claude_quick.sh fix

# 3. If still not working, recreate
rm -rf /Applications/Claude-work.app
./claude_quick.sh wrapper work

Issue: Claude Desktop not found

Solution:

1. Ensure Claude Desktop is downloaded and properly installed from claude.ai/download
2. Confirm the app is located at /Applications/Claude.app
3. Run ./claude_quick.sh diagnose to check installation status

Issue: Instance configuration lost

Solution:

# Restore original configuration
./claude_quick.sh restore

# Check backup files
ls -la ~/Library/Application\ Support/Claude.backup.*

Issue: Icon display problems

Solution:

# Fix icons
./claude_quick.sh fix

# Or recreate app wrapper
./claude_quick.sh wrapper [instance_name]

📊 Command Reference

🔒 Security Considerations

1. Configuration Backup: Script automatically backs up original configs, but manual backups are recommended
2. Sensitive Information: Each instance stores login information independently
3. Permission Control: App wrappers use the same permissions as original Claude app
4. Data Isolation: Different instances’ data is completely isolated

❓ Frequently Asked Questions

Q: Can I run multiple instances simultaneously?
A: No. macOS limits to one Claude Desktop instance at a time, but you can quickly switch between them.

Q: Will chat history sync between instances?
A: No. Different instances use different accounts, so chat history won’t sync.

Q: How do I backup instance configurations?
A: Copy the ~/.claude-instances/[instance_name] directory to backup the entire instance configuration.

Q: Can I import/export MCP configurations?
A: Yes. Copy the claude_desktop_config.json file to share MCP configurations between instances.

🤝 Technical Support

If you encounter issues:

1. First run ./claude_quick.sh diagnose for automatic diagnosis
2. Check the troubleshooting section in this document
3. Ensure Claude Desktop app is the latest version
4. Check macOS system version compatibility

📄 License

MIT License - Free to use and modify

💡 Tip: This tool is especially useful for users who need to manage multiple Claude accounts or different MCP server configurations simultaneously. Each instance is completely independent and can be safely used in different work environments.