Maestro

August 5, 2025 · View on GitHub

English | Japanese

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

https://github.com/user-attachments/assets/6415804a-3dd0-48ac-91eb-1c3adad70ae7

Overview
Key Features
Installation
Updating
Requirements
Quick Start
Command Reference
Advanced Features
Configuration
Troubleshooting
Contributing
License

Overview

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.

Why Maestro?

Pain Point	Maestro’s Approach	Benefit
Inefficient parallel development Frequent branch switches, stashes and context switching	Automatic Worktree management Each feature lives in its own directory	Zero branch-switch cost, smooth multitasking
Hard to keep track of tasks	CLI list & status Visualise all performers (worktrees)	Instantly know where you are and the current progress
Heavy review / merge workload	Claude Code integration AI diff reviews & automated PR flow	Drastically reduces review time

Key Features

Feature	Description
🎼 Orchestra UI	Operate worktrees as performers in an intuitive way
🤖 Claude AI	AI diff reviews & code suggestions
🔗 GitHub integration	Reliable worktree creation from Issues / PRs with rich metadata
🎯 tmux / fzf	Keyboard-only, lightning-fast switching
📊 Status	Real-time worktree status and health monitoring
🔄 Auto Sync	Propagate file changes in real time
📸 Snapshot	Save / restore any state with one command
🏥 Health Check	Detect & auto-fix orphaned / conflicting branches
🛡️ Auto Rollback	Intelligent cleanup prevents orphaned worktrees

Installation

Homebrew (recommended)

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

npm install -g @camoneart/maestro

pnpm

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

pnpm add -g @camoneart/maestro

Updating

Homebrew

brew upgrade camoneart/tap/maestro

npm

npm update -g @camoneart/maestro

pnpm

pnpm update -g @camoneart/maestro

Requirements

Requirement	Version	Purpose	Install Command
Node.js	>=20.0.0	JavaScript runtime	nodejs.org
Git	>=2.22	Worktree support	`brew install git`
tmux (optional)	Any	Session management	`brew install tmux`
fzf (optional)	Any	Fuzzy finding	`brew install fzf`
GitHub CLI (optional)	Any	GitHub integration	`brew install gh`

Quick Start

# 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
# or: mst init --yes                          # Quick setup with defaults

# 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

Tips

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).

Basic Usage Examples

Goal	Command Example
Parallel dev Feature + bugfix	`mst create feature/auth --tmux --claude-md` `mst create bugfix/login-issue`
List performers	`mst list`
List with GitHub metadata	`mst list --metadata`
Fast switch via tmux	`mst tmux`
Create from GitHub Issue	`mst create 123`
Create from PR	`mst github checkout 456`
Create from PR with tmux	`mst github checkout 456 --tmux-h`
List GitHub issues/PRs	`mst github list`
Push with PR	`mst push --pr`
Push with draft PR	`mst push --draft-pr`
Auto review & merge	`mst review --auto-flow`

Command Reference

See the full Command Reference.

Main Commands

Command	Description	Example
`init`	Initialize project config	`mst init --yes`
`create`	Create a new worktree	`mst create feature/login`
`list`	List worktrees	`mst list`
`delete`	Orchestra members exit the stage with automatic tmux session cleanup	`mst delete feature/old --keep-session`
`tmux`	Open in tmux	`mst tmux`
`sync`	Real-time file sync	`mst sync --auto`
`push`	Push and create PR	`mst push --pr`
`github`	GitHub integration	`mst github checkout 123`
`health`	Health check	`mst health --fix`
`where`	Show current performer	`mst where`

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

One-line Cheat Sheet

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
mst list                                       # list performers
mst tmux                                       # switch via fzf
mst push --pr                                  # push with PR
mst review --auto-flow                         # auto review & merge

Advanced Features

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

Feature	Command Example	What It Automates
Auto Review & Merge 🚀	`mst review --auto-flow`	Fetch → rebase → AI review → Conventional Commit → open PR — all in one go
GitHub Integration 🔗	`mst github list` `mst github checkout 123 --tmux-h` `mst list --metadata`	List and checkout GitHub issues/PRs with reliable worktree creation, comprehensive metadata storage, and tmux integration
Snapshot 📸	`mst snapshot -m "before-refactor"` `mst snapshot --restore <id>`	Save / restore any working state instantly
Health Check 🏥	`mst health` `mst health --fix`	Detects stale / orphaned / conflicted branches and fixes them automatically

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

Configuration

📁 Project Configuration `.maestro.json`

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

⚙️ Configuration Management

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

Category	Key	Purpose	Default / Example
worktrees	`path`	Where to store performers	`../maestro-{branch}`
	`directoryPrefix`	Prefix for worktree directories	`""` (empty string)
	`branchPrefix`	Prefix for new branches	`feature/`
development	`autoSetup`	Auto-run `npm install` after `create`	`true`
	`syncFiles`	Files to sync across worktrees	`[".env", ".env.local"]`
	`defaultEditor`	Default editor for opening	`cursor`
tmux	`enabled`	Enable tmux integration	`false`
	`openIn`	Open in window or pane	`window` (`window` or `pane`)
	`sessionNaming`	Session naming pattern	`{branch}`
claude	`markdownMode`	CLAUDE.md file management mode	`shared` (`shared` or `split`)
github	`autoFetch`	Auto-fetch before operations	`true`
	`branchNaming.prTemplate`	PR branch naming template	`pr-{number}`
	`branchNaming.issueTemplate`	Issue branch naming template	`issue-{number}`
ui	`pathDisplay`	Path display format in all commands that show paths	`absolute` (`absolute` or `relative`)
hooks	`afterCreate`	Command after creation	`npm install`
	`beforeDelete`	Command before deletion	`echo "Deleting $ORCHESTRA_MEMBER"`

Full Example with Default Values

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

📋 Complete Configuration Reference

All available configuration options for .maestro.json:

Category	Key	Type	Default	Description
worktrees				Worktree location and naming
	`path`	string	`"../maestro-{branch}"`	Directory pattern for worktrees (`{branch}` is replaced with branch name)
	`directoryPrefix`	string	`""`	Prefix added to all worktree directory names
	`branchPrefix`	string	`""`	Default prefix for new branch names
development				Development environment settings
	`autoSetup`	boolean	`true`	Auto-run setup commands after worktree creation
	`syncFiles`	string[]	`[".env", ".env.local"]`	Files to sync across worktrees
	`defaultEditor`	string	`"cursor"`	Default editor (`vscode`, `cursor`, `none`)
postCreate			(not in defaults)	Post-creation automation
	`copyFiles`	string[]	-	Files to copy from main worktree after creation
	`commands`	string[]	-	Commands to execute after worktree creation
tmux				tmux integration settings
	`enabled`	boolean	`false`	Enable tmux integration
	`openIn`	string	`"window"`	Open in `window` or `pane`
	`sessionNaming`	string	`"{branch}"`	Session naming pattern
claude				Claude Code integration
	`markdownMode`	string	`"shared"`	CLAUDE.md mode: `shared` (symlink) or `split` (independent)
github				GitHub integration settings
	`autoFetch`	boolean	`true`	Auto-fetch before operations
	`branchNaming.prTemplate`	string	`"pr-{number}"`	PR branch naming template
	`branchNaming.issueTemplate`	string	`"issue-{number}"`	Issue branch naming template
ui				User interface settings
	`pathDisplay`	string	`"absolute"`	Path display format: `absolute` or `relative`
hooks				Lifecycle hooks
	`afterCreate`	string \| string[]	-	Commands to run after worktree creation
	`beforeDelete`	string	-	Command to run before worktree deletion

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

🤖 MCP Integration Setup

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

Local Scope (Default - only for current project, private to you)

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

User Scope (available across all projects on the machine)

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

For global installation users

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.

🐚 Shell Completion

Maestro provides completion scripts for bash / zsh / fish.

Install Method	bash	zsh / fish
Homebrew	Auto (bash requires `bash-completion@2`)	Auto
npm / pnpm	Manual (below)	Manual (below)

bash manual setup (npm / pnpm installs)

brew install bash-completion@2  # if not installed

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

zsh manual setup

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

fish manual setup

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

Troubleshooting

🛡️ Automatic Rollback Protection

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

❓ Common Errors and Fixes

Error	Likely Cause	One-line Fix
Git is too old `fatal: unknown option`	Git < 2.22	`brew install git`
fzf not found	fzf not installed	`brew install fzf`
tmux not found	tmux not installed	`brew install tmux`
Too many tmux panes `Unable to create session with N panes due to terminal size`	Terminal window too small for requested panes	Resize window or reduce panes (max: 10 horizontal, 15 vertical)
GitHub PR/Issue not found `Error: PR/Issue #999 が見つかりません`	Specified non-existent Issue/PR number	Check correct number or verify repository

Other error codes

Code	Cause	Fix
`ENOENT`	Git binary not found	Check PATH or reinstall Git

⚠️ CLI Option Validation and Error Handling

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

⚠️ Directory Existence Checking and Interactive Handling

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

⚠️ tmux Multi-Pane Validation and Error Handling

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.

🔍 Debug Mode

# 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

Contributing

🤝 Contribution Workflow

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

See the Contributing Guide and Code of Conduct for details.

License

Licensed under the MIT License.