CCManager - AI Code Agent Session Manager

CCManager is a CLI application for managing multiple AI coding assistant sessions (Claude Code, Gemini CLI, Codex CLI, Cursor Agent, Copilot CLI, Cline CLI, OpenCode, Kimi CLI) across Git worktrees and projects.

https://github.com/user-attachments/assets/15914a88-e288-4ac9-94d5-8127f2e19dbf

Features

• Run multiple AI assistant sessions in parallel across different Git worktrees
• Multi-project support: Manage multiple git repositories from a single interface
• Support for multiple AI coding assistants (Claude Code, Gemini CLI, Codex CLI, Cursor Agent, Copilot CLI, Cline CLI, OpenCode, Kimi CLI)
• Switch between sessions seamlessly
• Visual status indicators for session states (busy, waiting, idle)
• Create, merge, and delete worktrees from within the app
• Restore sessions after a restart: reopen the sessions that were running when CCManager last exited or crashed
• Copy Claude Code session data between worktrees to maintain conversation context
• .worktreeinclude support: carry gitignored project files (.env, local certs) into newly created worktrees
• Configurable keyboard shortcuts
• Command presets with automatic fallback support
• Configurable state detection strategies for different CLI tools
• Status change hooks for automation and notifications
• Devcontainer integration
• Auto Approval (experimental): Automatically approve safe prompts using AI verification

Why CCManager over Claude Squad?

Both tools solve the same problem - managing multiple Claude Code 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:

🚀 No tmux dependency

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.

👁️ Real-time session monitoring

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.

🎯 Simple and intuitive interface

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.

Install

npm install -g ccmanager

Local Development

npm install
bun run build
npm start

Usage

ccmanager

Or run without installing:

npx ccmanager

Keyboard Shortcuts

Default Shortcuts

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

Customizing Shortcuts

You can customize keyboard shortcuts in two ways:

1. Through the UI: Select Global Configuration → Configure Shortcuts from the main menu
2. Configuration file: Edit ~/.config/ccmanager/config.json or .ccmanager.json for per-project settings (see Per-Project Configuration)

Example configuration:

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

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

Restrictions

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

Per-Project Configuration

CCManager supports per-project configuration by placing a .ccmanager.json file in your git repository root. Project settings are merged with the global config (~/.config/ccmanager/config.json), with project settings always taking priority.

For detailed configuration options and examples, see docs/project-config.md.

Configuring with an AI coding agent

This repository doubles as a plugin marketplace providing the ccmanager-config skill, which teaches Claude Code or Codex the whole configuration schema and ships a validator for it:

# Claude Code
claude plugin marketplace add kbwo/ccmanager
claude plugin install ccmanager-config@ccmanager

# Codex CLI
codex plugin marketplace add kbwo/ccmanager
codex plugin add ccmanager-config@ccmanager

Then just ask — "set this repo up to run codex in ccmanager", "notify me when a session is waiting for input", "why is my .ccmanager.json being ignored?". See plugins/ccmanager-config/README.md.

Supported AI Assistants

CCManager supports multiple AI coding assistants with tailored state detection for each:

Each assistant has its own state detection strategy to properly track:

• Idle: Ready for new input
• Busy: Processing a request
• Waiting: Awaiting user confirmation

See Gemini Support Documentation for CCManager-specific configuration.

Command Configuration

CCManager supports configuring the command and arguments used to run Claude Code sessions, with automatic fallback options for reliability.

Features

• Configure the main command (default: claude)
• Set primary arguments (e.g., --resume)
• Define fallback arguments if the primary configuration fails
• Automatic retry with no arguments as final fallback

Quick Start

1. Navigate to Global Configuration → Configure Command Presets
2. Set your desired arguments (e.g., --resume for resuming sessions)
3. Optionally set fallback arguments
4. Save changes

For detailed configuration options and examples, see docs/command-config.md.

Claude Code Teammate Mode

When running the claude command with the default (claude) detection strategy, CCManager automatically appends --teammate-mode in-process to the CLI arguments. This prevents conflicts between Claude Code's agent teams feature and ccmanager's PTY-based session management.

• Automatic: No configuration needed. CCManager injects the flag for all claude command sessions.
• Override: If you explicitly specify --teammate-mode in your preset args, your value takes priority.
• Non-claude commands: Other AI assistants (Gemini, Codex, etc.) are not affected.

Setting "teammateMode": "in-process" in Claude Code's settings.json alone is not sufficient when running inside a tmux-like environment, which is why CCManager controls this via the CLI argument.

Creating Worktrees in the Background

Creating a worktree (generating the branch name, git worktree add, copying files, running worktree hooks) can take a while in large repositories. The loading screen shown during creation can be left at any time:

• Wait: stay on the loading screen and everything behaves as before — errors and hook failures are shown right away, and a prompt-first worktree opens its new session automatically.
• Continue in the background: press Enter to return to the menu and keep working. The menu lists the creations still running for the project; when one finishes, the new worktree appears in the list. A prompt-first session is started without switching to it, and any failure is shown as an error on the menu.

Session Data Copying

CCManager can copy Claude Code session data (conversation history, context, and project state) when creating new worktrees, allowing you to maintain context across different branches.

Features

• Seamless Context Transfer: Continue conversations in new worktrees without losing context
• Configurable Default: Set whether to copy session data by default
• Per-Creation Choice: Decide on each worktree creation whether to copy data
• Safe Operation: Copying is non-fatal - worktree creation succeeds even if copying fails

How It Works

When creating a new worktree, CCManager:

1. Asks whether to copy session data from the current worktree
2. Copies all session files from ~/.claude/projects/[source-path] to ~/.claude/projects/[target-path]
3. Preserves conversation history, project context, and Claude Code state
4. Allows immediate continuation of conversations in the new worktree

Configuration

1. Navigate to Global Configuration → Configure Worktree
2. Toggle Copy Session Data to set the default behavior
3. Save changes

The default choice (copy or start fresh) will be pre-selected when creating ne