CCManager is a TUI application for managing multiple AI coder sessions across Git worktrees.

• Run multiple AI coding sessions in parallel across different Git worktrees
• Command Selection: Choose between Claude Code, Codex, and Cursor for each session
• Switch between sessions seamlessly
• Visual status indicators for session states (busy, waiting, idle)
• Create, merge, and delete worktrees from within the app
• Smart Worktree Placement: Automatically creates worktrees outside the main project to prevent accidental commits
• Configurable keyboard shortcuts
• Status change hooks for automation and notifications

Both tools solve the same problem - managing multiple AI Coder sessions - but take different approaches.

If you love tmux-based workflows, stick with Claude Squad! It's a great tool that leverages tmux's power for session management.

CCManager is for developers who want:

CCManager is completely self-contained. No need to install or configure tmux - it works out of the box. Perfect if you don't use tmux or want to keep your tmux setup separate from Claude Code management.

CCManager shows the actual state of each Claude Code session directly in the menu:

• Waiting: Claude is asking for user input
• Busy: Claude is processing
• Idle: Ready for new tasks

Claude Squad doesn't show session states in its menu, making it hard to know which sessions need attention. While Claude Squad offers an AutoYes feature, this bypasses Claude Code's built-in security confirmations - not recommended for safe operation.

Following Claude Code's philosophy, CCManager keeps things minimal and intuitive. The interface is so simple you'll understand it in seconds - no manual needed.

$ npm install
$ npm run build
$ npm start

$ npx ccmanager

You can pass additional arguments to Claude Code sessions by setting the CCMANAGER_CLAUDE_ARGS environment variable:

# Start Claude Code with specific arguments for all sessions
export CCMANAGER_CLAUDE_ARGS="--resume"
npx ccmanager

# Or set it inline
CCMANAGER_CLAUDE_ARGS="--resume" npx ccmanager

Similarly, you can pass additional arguments to Codex sessions:

# Start Codex with specific arguments for all sessions
export CCMANAGER_CODEX_ARGS="--temperature 0.2"
npx ccmanager

# Or set it inline
CCMANAGER_CODEX_ARGS="--temperature 0.2" npx ccmanager

The arguments are applied to all sessions of the respective type started by CCManager.

When creating a new session, CCManager now allows you to choose between different AI coding assistants:

• 🤖 Claude Code: Advanced AI coding assistant with comprehensive understanding
• ⚡ Codex: Fast AI code completion and generation
• 🖱 Cursor: Open the selected worktree in the Cursor editor (macOS fallback supported)

The command selection interface appears when you select a worktree that doesn't have an active session. Once a session is created with a specific command, that choice is remembered for the session's lifetime.

In the main menu, active sessions display indicators to show which command they're using:

• 🤖: Claude Code session
• ⚡: Codex session

Note: Selecting Cursor opens the worktree in the Cursor editor instead of starting an in-app terminal session. If the cursor CLI is not available, CCManager will try open -a Cursor on macOS as a fallback.

• Ctrl+E: Return to menu from active session
• Escape: Cancel/Go back in dialogs

You can customize keyboard shortcuts in two ways:

1. Through the UI: Select "Configuration" → "Configure Shortcuts" from the main menu
2. Configuration file: Edit ~/.config/ccmanager/config.json (or legacy ~/.config/ccmanager/shortcuts.json)

Example configuration:

// config.json (new format)
{
  "shortcuts": {
    "returnToMenu": {
      "ctrl": true,
      "key": "r"
    },
    "cancel": {
      "key": "escape"
    }
  }
}

// shortcuts.json (legacy format, still supported)
{
  "returnToMenu": {
    "ctrl": true,
    "key": "r"
  },
  "cancel": {
    "key": "escape"
  }
}

Note: Shortcuts from shortcuts.json will be automatically migrated to config.json on first use.

• Shortcuts must use a modifier key (Ctrl) except for special keys like Escape
• The following key combinations are reserved and cannot be used:
  • Ctrl+C
  • Ctrl+D
  • Ctrl+[ (equivalent to Escape)

CCManager automatically creates worktrees in a sibling folder to your project. For example:

• If your project is named A, worktrees are created in ../A-worktrees/
• Branch feature/X becomes ../A-worktrees/A-feature-X
• Branch bugfix/login-issue (project myproject) becomes ../myproject-worktrees/myproject-bugfix-login-issue

By default, automatic placement is enabled and uses the following pattern:

worktrees/{project}-{branch}

This generates paths like myproject/worktrees/myproject-feature-x by replacing:

• {project}: the repository name
• {branch}: the sanitized branch name (slashes replaced with -, special characters removed, lowercased)

You can customize or disable this behavior through the Configuration menu.

You can customize the worktree directory pattern through the Configuration menu:

1. Select "Configuration" → "Configure Worktree Settings"
2. Enable "Auto Directory" to use automatic placement
3. Customize the pattern using placeholders (default shown below):
   • {project} - Your project name (auto-detected from Git repository)
   • {branch} - The branch name (sanitized for filesystem)

Example patterns:

• ../{project}-worktrees/{project}-{branch} (default)
• ../worktrees/{project}/{branch}
• /tmp/{project}-wt/{branch}

CCManager can execute custom commands when Claude Code session status changes. This enables powerful automation workflows like desktop notifications, logging, or integration with other tools.

Status hooks allow you to:

• Get notified when Claude needs your input
• Track time spent in different states
• Trigger automations based on session activity
• Integrate with notification systems like noti

For detailed setup instructions, see docs/state-hooks.md.

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build
npm run build

# Run tests
npm test

# Run linter
npm run lint

# Run type checker
npm run typecheck