Maestro

Maestro

[](https://nodejs.org/) [](https://www.npmjs.com/package/@camoneart/maestro) [](https://opensource.org/licenses/MIT)

English | [Japanese](/README.ja.md)

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

Table of Contents

• [Overview](#overview)
• [Key Features](#key-features)
• [Installation](#installation)
• [Updating](#updating)
• [Requirements](#requirements)
• [Quick Start](#quick-start)
• [Command Reference](#command-reference)
• [Advanced Features](#advanced-features)
• [Configuration](#configuration)
• [Troubleshooting](#troubleshooting)
• [Contributing](#contributing)
• [License](#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 developmentFrequent branch switches, stashes and context switching | Automatic Worktree managementEach feature lives in its own directory | Zero branch-switch cost, smooth multitasking | | Hard to keep track of tasks | CLI list & statusVisualise all performers (worktrees) | Instantly know where you are and the current progress | | Heavy review / merge workload | Claude Code integrationAI 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](#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 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 /--tmux-v-panes creates multiple horizontal/vertical panes with specified count, all displaying consistent branch name titles.
• --tmux-layout 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-mdmst 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](./docs/COMMANDS.md).

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](./docs/COMMANDS.md).

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 | 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 --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 c

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: kaijutale
• Source: kaijutale/maestro
• License: MIT

Install and usage instructions live in the source repository linked above.