English | Japanese

A CLI tool that conducts Git worktrees like an orchestra and accelerates parallel development with Claude Code.

• Overview
• Key Features
• Installation
• Updating
• Requirements
• Quick Start
• Orchestration Mode 🎭
• Command Reference
• Advanced Features
• Configuration
• Troubleshooting
• Contributing
• License

Maestro is a CLI that makes Git worktree management intuitive. When working on multiple branches in parallel you can treat each branch as an independent “orchestra member” without changing directories.

brew install camoneart/tap/maestro

• Homebrew installs completion scripts for zsh / fish / bash automatically.
  
• For bash you also need brew install bash-completion@2. See Shell Completion.

npm install -g @camoneart/maestro

# If pnpm is not installed yet
npm install -g pnpm

pnpm add -g @camoneart/maestro

brew upgrade camoneart/tap/maestro

npm update -g @camoneart/maestro

pnpm update -g @camoneart/maestro

# 1. Install (Homebrew example)
brew install camoneart/tap/maestro

# 2. Move to your Git project
cd ~/path/to/your-repo

# 2.5. Initialize maestro for your project (NEW!)
mst init                                      # Interactive setup with language selection (English/Japanese)
# or: mst init --yes                          # Quick setup with defaults (auto-detects language)

# 3. Create a performer (worktree)
mst create feature/awesome-feature            # create only

# 4. Jump into the performer’s shell
mst shell feature/awesome-feature             # open a shell inside

# ── one-liner (tmux + Claude) ──
# Create the worktree, prompt for tmux session attachment, and set up Claude Code workspace
mst create feature/awesome-feature --tmux --claude-md

• mst shell <branch> lets you enter any performer after creation (fzf prompt when omitted).
• --tmux creates a dedicated tmux session with branch name title and prompts for attachment (automatically attaches in non-TTY environments); combine with --claude-md to set up Claude Code workspace files.
• --tmux-h/--tmux-v splits the current tmux pane horizontally/vertically with improved focus management (focuses first pane) and unified pane titles.
• --tmux-h-panes <number>/--tmux-v-panes <number> creates multiple horizontal/vertical panes with specified count, all displaying consistent branch name titles.
• --tmux-layout <type> applies specific tmux layout (even-horizontal, even-vertical, main-horizontal, main-vertical, tiled).

When you use --tmux-h-panes or --tmux-v-panes, Maestro creates ONE tmux session with multiple panes, all working in the SAME worktree directory. This is perfect for parallel development workflows:

# Creates 1 tmux session with 4 panes, all in the same feature/api worktree
mst create feature/api --tmux-h-panes 4 --tmux-layout tiled

Common Use Cases for Multiple Panes:

• Pane 1: Code editor (vim/nvim)
• Pane 2: Test runner (npm test --watch)
• Pane 3: Development server (npm run dev)
• Pane 4: Git operations and general commands

All panes share the same worktree directory, so you're always working on the same feature branch. Navigate between panes with Ctrl+B then arrow keys. Detach from the session with Ctrl+B, D (the session continues running in the background).

NEW in v5.2.0: Enhanced tmux Experience & Complete i18n 🎯

• Automatic Help Display: When creating multi-pane sessions or attaching, Maestro shows tmux navigation tips
• Easy Session Management: Use mst tmux-attach (or mst ta) to easily reconnect to any tmux session
• Built-in Cheat Sheet: Run mst ta --help-tmux to see the full tmux reference anytime
• Fixed Detachment: When you detach (Ctrl+B, D), Maestro continues running and completes setup tasks
• Session Persistence: Your tmux session remains active and can be re-attached with mst ta <branch-name>
• Complete i18n: All hardcoded text replaced with proper translations (English/Japanese)

Maestro supports both English and Japanese interfaces:

• First-time setup: mst init prompts for your preferred language
• Auto-detection: Detects language from system locale if not specified
• Persistent: Language preference is saved in .maestro.json and global config
• Complete translations: All commands, messages, and errors fully translated

Language priority order:

1. Project .maestro.json setting
2. Global ~/.maestro/config.json setting
3. System locale ($LANG environment variable)
4. Default: English (follows system locale)

See the full Command Reference.

All sub-commands and options are documented in the Command Reference.

These commands serve completely different purposes:

Quick Examples:

# ATTACH: Create a new worktree from an existing branch
mst attach feature/existing-branch    # Creates worktree from existing branch
mst attach                            # Interactive selection of existing branches

# TMUX-ATTACH: Reconnect to a running tmux session
mst ta                                # Interactive selection of running sessions
mst ta feature/my-branch              # Reconnect to specific session
mst ta --list                         # List all running tmux sessions
mst ta --help-tmux                    # Show tmux navigation help

Common Workflow:

1. mst create feature/new --tmux - Creates worktree AND tmux session
2. Work in tmux, then detach with Ctrl+B, D
3. Later: mst ta feature/new - Reconnect to the same session

mst create feature/my-ui --tmux --claude-md   # create + AI + tmux
mst create feature/api --tmux-h-panes 3       # create + 3 horizontal panes (unified titles)
mst create feature/tdd --tmux-h-panes 4 --tmux-layout tiled  # 4-pane grid layout
# Note: Detaching (Ctrl+B, D) now properly returns control to mst without exiting
mst list                                       # list performers
mst tmux                                       # switch via fzf
mst push --pr                                  # push with PR
mst review --auto-flow                         # auto review & merge

Maestro acts as a true "conductor" - using Claude AI to plan and execute entire parallel development workflows with pre-configured prompts for each worktree.

tmux is required for orchestration features:

brew install tmux  # macOS
# or
sudo apt-get install tmux  # Ubuntu/Debian

1. Plan: mst plan - Claude AI helps design your orchestration
2. Implement: mst implement - Execute the plan, creating all worktrees and sessions
3. Orchestra: mst orchestra - Monitor and manage your orchestration

v5.5.0 Update: Orchestration plans now stored in .maestro.json under the orchestration key instead of separate MAESTRO.yml files.

mst plan              # Default: Claude AI assists you
mst plan --manual     # Optional: Use traditional prompts
mst plan --help       # See all options

Claude Mode (Default): When you run mst plan, Claude will:

1. Ask about your goals - Natural conversation about what you want to build
2. Analyze your codebase - Understand project structure and dependencies
3. Suggest parallel workflows - Optimal feature breakdown for parallel development
4. Generate orchestration plan - Saved to .maestro.json

Example Session:

$ mst plan
🎼 Maestro Orchestration Planner
📋 Initiating Claude AI assistance...

[Claude]: What features would you like to implement?
[You]: I need authentication and payment processing
[Claude]: I'll analyze your codebase and create an orchestration plan...
[Claude generates orchestration plan with optimal parallel setup]

The orchestration plan is saved to .maestro.json under the orchestration key.

mst implement
# or
mst implement --all        # Implement all features
mst implement --dry-run    # Preview what would be created

What happens during implementation:

1. Creates Git worktrees for each feature
2. Creates detached tmux sessions (running in background)
3. Injects prompts into each pane but does NOT execute them
4. Creates customized CLAUDE.md files with context
5. Shows summary of created sessions

Important: Sessions are created in the background. You won't see them immediately!

# View all created sessions
mst orchestra

# Attach to a specific session
mst orchestra attach
# or
tmux attach -t feature-backend

# View orchestration status
mst orchestra status

When you attach to a session:

• You'll see pre-filled prompts in each pane
• Press Enter in each pane to execute the commands
• Navigate between panes with Ctrl+B then arrow keys
• Detach with Ctrl+B, D to leave session running

# 1. Plan a microservices architecture
mst plan

# Example responses:
# Project: "E-commerce microservices"
# Feature 1: "auth-service"
#   - Session: backend (3 panes)
#     - Pane 1: "npm run dev"
#     - Pane 2: "npm test --watch"
#     - Pane 3: "tail -f logs/auth.log"
# Feature 2: "payment-service"
#   - Session: backend (2 panes)
#     - Pane 1: "npm run dev"
#     - Pane 2: "npm test --watch"

# 2. Execute the plan
mst implement
# Output:
# ✓ Created worktree for auth-service
# ✓ Created worktree for payment-service
# ✓ Created tmux session: auth-service-backend (3 panes)
# ✓ Created tmux session: payment-service-backend (2 panes)
#
# Next steps:
# 1. Attach to sessions: mst orchestra attach
# 2. Press Enter in each pane to execute commands
# 3. Start developing!

# 3. Start working
mst orchestra attach
# Select: auth-service-backend
# [You're now in tmux with 3 panes]
# [Press Enter in each pane to start services]

# 4. Monitor progress
mst orchestra status
# Shows all features, sessions, and their states

The orchestration plan is stored in .maestro.json under the orchestration key:

{
  "orchestration": {
    "version": "1.0",
    "created": "2024-01-01T00:00:00Z",
    "description": "E-commerce microservices architecture",
    "features": [
      {
        "name": "user-auth",
        "description": "OAuth2 authentication system",
        "base": "main",
        "sessions": [
          {
            "name": "backend",
            "panes": 3,
            "layout": "main-vertical",
            "prompts": [
              "npm run dev",
              "npm test --watch",
              "docker-compose logs -f auth"
            ]
          }
        ],
        "claudeContext": "Use Passport.js for OAuth2\nImplement JWT with refresh tokens",
        "agents": ["code-reviewer", "security-scanner"],
        "dependencies": []
      },
      {
        "name": "payment-service",
        "description": "Payment processing with Stripe",
        "base": "main",
        "sessions": [
          {
            "name": "api",
            "panes": 2,
            "layout": "even-horizontal",
            "prompts": [
              "npm run dev",
              "stripe listen --forward-to localhost:3001/webhook"
            ]
          }
        ],
        "dependencies": ["user-auth"]
      }
    ],
    "settings": {
      "parallel": true,
      "autoAttach": false
    }
  }
}

• Detached Sessions: tmux sessions run in background until you attach
• Prompt Injection: Commands are typed but not executed - you press Enter
• Dependencies: Features can depend on others for ordered execution
• Parallel Creation: Multiple worktrees created simultaneously for speed

Maestro ships with power commands that automate tedious tasks in a single line.

Need more? Run mst <command> --help.

Maestro reads .maestro.json at the project root to customise behaviour.
Key settings are summarised below; a full example follows.

Maestro provides commands to manage configuration settings using dot notation:

# Get configuration values
mst config get ui.pathDisplay                      # Get path display setting
mst config get development.autoSetup               # Get auto-setup setting

# Set configuration values  
mst config set ui.pathDisplay relative             # Auto-detects as user setting
mst config set --user ui.pathDisplay relative     # Explicitly save to user settings
mst config set --project worktrees.path "../"     # Explicitly save to project settings
mst config set development.defaultEditor cursor    # Set default editor (user setting)

# Reset to defaults
mst config reset ui.pathDisplay                    # Reset path display to default
mst config reset development.autoSetup             # Reset auto-setup to default

# View and manage configuration files
mst config show                                    # Show current effective config
mst config path                                    # Show config file locations
mst config init                                    # Create project configuration

Path Display Configuration:
The ui.pathDisplay setting controls how file paths are shown across all commands. When set to "relative", paths are displayed relative to the current working directory. When set to "absolute" (default), full absolute paths are shown. This affects commands like github, review, shell, exec, and health.

Claude Configuration:

• markdownMode: "shared" - Creates symlink to main repository's CLAUDE.md (default)
• markdownMode: "split" - Creates independent CLAUDE.md for each worktree

{
  "worktrees": {
    "path": "../maestro-{branch}",
    "directoryPrefix": "",
    "branchPrefix": "feature/"
  },
  "development": {
    "autoSetup": true,
    "syncFiles": [".env", ".env.local"],
    "defaultEditor": "cursor"
  },
  "tmux": {
    "enabled": false,
    "openIn": "window",
    "sessionNaming": "{branch}"
  },
  "claude": {
    "markdownMode": "shared"
  },
  "github": {
    "autoFetch": true,
    "branchNaming": {
      "prTemplate": "pr-{number}",
      "issueTemplate": "issue-{number}"
    }
  },
  "ui": {
    "pathDisplay": "absolute"
  },
  "hooks": {
    "afterCreate": "npm install",
    "beforeDelete": "echo \\\"Deleting performer: $ORCHESTRA_MEMBER\\\""
  }
}

All available configuration options for .maestro.json:

Note: For detailed configuration examples and advanced usage, see Configuration Guide.

Add Maestro as an MCP server to Claude Code using the modern command:

claude mcp add maestro -s local -- npx -y @camoneart/maestro maestro-mcp-server
# Or without -s flag (local is default)
claude mcp add maestro -- npx -y @camoneart/maestro maestro-mcp-server

claude mcp add maestro -s project -- npx -y @camoneart/maestro maestro-mcp-server

claude mcp add maestro -s user -- npx -y @camoneart/maestro maestro-mcp-server

If you've installed Maestro globally, use:

claude mcp add maestro -s user -- maestro-mcp-server

This will automatically configure Claude Code to use Maestro's MCP server for orchestra management at the chosen scope level.

Note: The traditional manual configuration in .claude/mcp_settings.json is no longer supported. Use the claude mcp add command instead.

Maestro provides completion scripts for bash / zsh / fish.

brew install bash-completion@2  # if not installed

echo 'eval "$(mst completion bash)"' >> ~/.bashrc
source ~/.bashrc

mkdir -p ~/.zsh/completions
mst completion zsh > ~/.zsh/completions/_mst
autoload -U compinit && compinit

mst completion fish > ~/.config/fish/completions/mst.fish

Maestro includes intelligent automatic rollback functionality that prevents orphaned worktrees when creation fails during post-processing steps:

How It Works:

• Tracks Creation State: Monitors whether worktree creation succeeded
• Detects Post-Creation Failures: Catches errors during tmux session creation, environment setup, or other post-processing
• Automatic Cleanup: Immediately removes created worktrees and branches when failures occur
• Clear Feedback: Provides user-friendly messages about cleanup process
• Fallback Instructions: Shows manual cleanup commands if automatic rollback fails

Example:

# If tmux session creation fails:
mst create feature/new-feature --tmux

# Maestro automatically cleans up:
⚠️  An error occurred during post-processing. Cleaning up created resources...
✅ Cleanup completed

Benefits:

• No Orphaned Worktrees: Maintains clean repository state even when errors occur
• Better Error Recovery: Reduces manual cleanup required after failures
• Improved User Experience: Clear feedback and recovery instructions

Maestro now includes strict CLI option validation to prevent execution with invalid options:

Immediate Exit on Invalid Options:

• Early Detection: Commands exit immediately when unknown or invalid options are provided
• Prevents Execution: Commands will not proceed with any operations when invalid options are detected
• Clear Error Messages: Specific feedback about which options are invalid

Example:

# Invalid option provided:
mst create feature/test --invalid-option value

# Output:
error: unknown option '--invalid-option'

# Command exits with error code 1 - no resources created

Benefits:

• Prevents Unintended Operations: Commands won't execute with typos in option names
• Clean Exit: Immediate feedback with error code 1
• Better Developer Experience: Immediate feedback about command usage errors

Maestro includes intelligent directory existence checking with interactive resolution options when creating worktrees:

Smart Directory Management:

• Early Detection: Checks if target directory already exists before worktree creation
• Interactive Resolution: Presents user with multiple resolution options when conflicts occur
• Clean Handling: Ensures consistent behavior across create, github, and review commands
• Safe Operations: All operations include confirmation prompts and clear feedback

Available Resolution Options: When a directory already exists, Maestro offers these interactive choices:

• Delete and Recreate: Removes existing directory and creates fresh worktree
• Use Alternative Name: Automatically generates unique directory name (e.g., branch-name-2)
• Cancel Operation: Safely exits without making any changes

Enhanced User Experience:

# Example interaction when directory exists:
mst create feature/new-feature

⚠️  Directory '../feature/new-feature' already exists

? How would you like to proceed?
❯ Delete existing directory and create new
  Use alternative name (feature/new-feature-2)
  Cancel

Benefits:

• Prevents Conflicts: No more worktree creation failures due to existing directories
• User Control: Clear choices for handling existing directories
• Automatic Alternatives: Smart generation of alternative names when needed
• Safe Cancellation: Easy exit option when conflicts can't be resolved

Maestro also includes early validation for tmux pane creation to prevent resource waste and provide better user experience:

Smart Pre-Validation:

• Early Detection: Validates pane count limits BEFORE creating any resources (worktree, branch, tmux session)
• Prevents Resource Creation: Command exits with error code 1 immediately when validation fails
• No Cleanup Needed: Since no resources are created, no rollback is required
• Maximum Limits: 10 panes for horizontal splits, 15 panes for vertical splits

Enhanced Error Messages:

# Early validation error message:
Error: Unable to create session with 20 panes due to terminal size. Please resize your terminal window or reduce the number of panes. (horizontal split)

# Command exits immediately - no resources created

Quick Solutions:

# If this fails due to pane limit:
mst create feature/api --tmux-h-panes 20

# Reduce to allowed limit:
mst create feature/api --tmux-h-panes 8

# Switch to vertical for higher limits:
mst create feature/api --tmux-v-panes 12 --tmux-layout main-vertical

# Use space-efficient layouts:
mst create feature/api --tmux-h-panes 6 --tmux-layout tiled

Validation Benefits:

• Clean Exit: Command exits with error code 1 when validation fails
• No Resource Waste: Prevents creation of worktrees that would need cleanup
• Better Performance: Immediate feedback without waiting for tmux operations
• Clear Guidance: Specific error messages with actionable solutions

Pane Limits:

• Horizontal splits: Maximum 10 panes (smaller screen space per pane)
• Vertical splits: Maximum 15 panes (more vertical space available)
• Validation triggers: Only for multi-pane options (--tmux-h-panes > 2, --tmux-v-panes > 2)

If the issue persists, search or open a new ticket in the Issues.

# Verbose logs to console
DEBUG=mst:* mst create feature/debug

# Save detailed logs to a file
DEBUG=mst:* mst review --auto-flow &> maestro-debug.log

1. Open an Issue for bugs or feature requests.
2. Fork the repo and create a branch like feat/your-topic.
3. Run pnpm lint && pnpm test and make sure everything passes.
4. Commit with Conventional Commits.
5. Open a Pull Request and fill out the template.

See the Contributing Guide and Code of Conduct for details.

Licensed under the MIT License.