kbwo/ccmanager

README

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.

Screencast.From.2025-06-30.00-39-53.mp4

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:

Through the UI: Select Global Configuration → Configure Shortcuts from the main menu
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.

Config files are read at startup. After editing them outside CCManager (by hand, or from another running CCManager), select Reload Config from Disk in the configuration screen to reload them.

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:

Assistant	Command	Installation
Claude Code (Default)	`claude`	code.claude.com
Gemini CLI	`gemini`	github.com/google-gemini/gemini-cli
Codex CLI	`codex`	github.com/openai/codex
Cursor Agent	`cursor-agent`	cursor.com/cli
Copilot CLI	`copilot`	github.com/github/copilot-cli
Cline CLI	`cline`	github.com/cline/cline
OpenCode	`opencode`	opencode.ai/docs
Kimi CLI	`kimi`	kimi-cli.com
MiniMax Code (MCode)	`mcode`	npmjs.com/package/@minimax-ai/code
Grok Build	`grok`	github.com/xai-org/grok-build

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

Navigate to Global Configuration → Configure Command Presets
Set your desired arguments (e.g., --resume for resuming sessions)
Optionally set fallback arguments
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:

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

Configuration

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

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

Use Cases

Feature Development: Copy session data when creating feature branches to maintain project context
Experimentation: Start fresh when testing unrelated changes
Collaboration: Share session state across team worktrees
Context Preservation: Maintain long conversations across multiple development branches

Copying Gitignored Files into New Worktrees

A new Git worktree contains only tracked files, so gitignored files a project needs in order to run — .env, local certificates, generated local config — do not come along. If the repository root has a .worktreeinclude file (gitignore syntax) listing those files, CCManager copies them into every worktree it creates.

Shared convention: same file name and semantics as Claude Code, Conductor, OpenAI Codex, and git-worktreeinclude, so an existing .worktreeinclude works with CCManager unchanged
No configuration: the copy runs whenever a .worktreeinclude file exists
Safe by construction: a file is copied only if it both matches a pattern and is actually gitignored, so tracked files are never duplicated
Hook-friendly: files are copied before the post-creation worktree hook runs, so hook commands can rely on them

For pattern syntax, the exact selection rule, and troubleshooting, see docs/worktree-include.md.

Restoring Sessions After a Restart

Closing CCManager kills the AI assistant processes it started, so reopening it normally means finding each worktree again and starting each session by hand. To avoid that, CCManager keeps a record of the sessions it currently has open, and on the next start offers to launch them again:

Restore previous sessions

Found 2 sessions from the last time ccmanager ran. Start them again?

  feature-login — Main
  fix-timeout (review) — Codex

> Restore
  Don't restore

What is restored: each session's command preset is run again in its worktree, under the name you had given it. The previous terminal output and the conversation held inside the assistant are not restored — restoring means starting the same command again, not resuming where it left off. (To carry conversation context into a new worktree, see Session Data Copying.)
Survives a crash: the record is written as sessions come and go, not on exit, so a crash, a kill -9, or a closed terminal leaves it intact.
Only sessions that were still open: a session you killed, or one whose command exited on its own, is dropped from the record and is not offered.
Declining is remembered: choosing "Don't restore" forgets those sessions, so the offer does not come back on the next start.
Scope: normally only the repository you are opening is considered. In Multi-Project Mode the sessions of every recorded project are offered together at startup.
Other running instances: sessions belonging to another CCManager that is still open are left alone, so they are not started a second time.

The record lives in ~/.config/ccmanager/sessions.json (%APPDATA%\ccmanager\sessions.json on Windows).

Status Change Hooks

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.

Overview

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.

Worktree Hooks

Worktree hooks execute custom commands when worktrees are created, enabling automation of development environment setup.

Features

Post-creation hook: Run commands after a worktree is created
Environment variables: Access worktree path, branch name, and git root
Non-blocking execution: Hooks run asynchronously without delaying operations
Error resilience: Hook failures don't prevent worktree creation

Use Cases

Set up development dependencies (npm install, bundle install)
Configure IDE settings per branch
Send notifications when worktrees are created
Initialize branch-specific configurations

For configuration and examples, see docs/worktree-hooks.md.

Automatic Worktree Directory Generation

CCManager can automatically generate worktree directory paths based on branch names, streamlining the worktree creation process.

Auto-generate paths: No need to manually specify directories
Customizable patterns: Use placeholders like {branch} in your pattern
Smart sanitization: Branch names are automatically made filesystem-safe

For detailed configuration and examples, see docs/worktree-auto-directory.md.

Auto Approval (Experimental)

CCManager can automatically approve Claude Code prompts that don't require user permission, reducing manual intervention while maintaining safety for sensitive operations.

Features

Automatic decision: Uses Claude (Haiku) to analyze prompts and determine if they need manual approval
Custom commands: Replace the default verifier with your own script or different AI model
Safe fallback: Always defaults to manual approval on errors or timeouts
Interruptible: Press any key to cancel auto-approval and review manually

Quick Start

Navigate to Global Configuration → Other & Experimental
Enable Auto Approval (experimental)
(Optional) Configure a custom command for verification

For detailed configuration and usage, see docs/auto-approval.md.

Devcontainer Integration

CCManager supports running AI assistant sessions inside devcontainers while keeping the manager itself on the host machine. This enables sandboxed development environments with restricted network access while maintaining host-level notifications and automation.

Features

Host-based management: CCManager runs on your host machine, managing sessions inside containers
Seamless integration: All existing features (presets, status hooks, etc.) work with devcontainers
Security-focused: Compatible with Anthropic's recommended devcontainer configurations
Persistent state: Configuration and history persist across container recreations

Usage

# Start CCManager with devcontainer support
npx ccmanager --devc-up-command "<your devcontainer up command>" \
              --devc-exec-command "<your devcontainer exec command>"

The devcontainer integration requires both commands:

--devc-up-command: Any command to start the devcontainer
--devc-exec-command: Any command to execute inside the container

Benefits

Safe experimentation: Run commands like claude --dangerously-skip-permissions without risk

For detailed setup and configuration, see docs/devcontainer.md.

Multi-Project Mode

CCManager can manage multiple git repositories from a single interface, allowing you to organize and navigate between different projects and their worktrees efficiently.

Quick Start

# Set the root directory containing your git projects
export CCMANAGER_MULTI_PROJECT_ROOT="/path/to/your/projects"

# Run CCManager in multi-project mode
npx ccmanager --multi-project

Features

Automatic project discovery: Recursively finds all git repositories
Recent projects: Frequently used projects appear at the top
Vi-like search: Press / to filter projects or worktrees
Session persistence: Sessions remain active when switching projects
Visual indicators: See session counts [active/busy/waiting] for each project

Navigation

Project List: Select from all discovered git repositories
Worktree Menu: Manage worktrees for the selected project
Session View: Interact with your AI assistant

Use B key to navigate back from worktrees to project list.

For detailed configuration and usage, see docs/multi-project.md.

Git Worktree Configuration

CCManager can display enhanced git status information for each worktree when Git's worktree configuration extension is enabled.

# Enable enhanced status tracking
git config extensions.worktreeConfig true

With this enabled, you'll see:

File changes: +10 -5 (additions/deletions)
Commit tracking: ↑3 ↓1 (ahead/behind parent branch)
Parent branch context: Shows which branch the worktree was created from

For complete setup instructions and troubleshooting, see docs/git-worktree-config.md.

Development

# Install dependencies
npm install

# Run in development mode
bun run dev

# Build
bun run build

# Run tests
npm test

# Run linter
bun run lint

# Run type checker
bun run typecheck

README

CCManager - AI Code Agent Session Manager

Screencast.From.2025-06-30.00-39-53.mp4

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

👁️ 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

🎯 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:

Through the UI: Select Global Configuration → Configure Shortcuts from the main menu
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

Config files are read at startup. After editing them outside CCManager (by hand, or from another running CCManager), select Reload Config from Disk in the configuration screen to reload them.

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:

Assistant	Command	Installation
Claude Code (Default)	`claude`	code.claude.com
Gemini CLI	`gemini`	github.com/google-gemini/gemini-cli
Codex CLI	`codex`	github.com/openai/codex
Cursor Agent	`cursor-agent`	cursor.com/cli
Copilot CLI	`copilot`	github.com/github/copilot-cli
Cline CLI	`cline`	github.com/cline/cline
OpenCode	`opencode`	opencode.ai/docs
Kimi CLI	`kimi`	kimi-cli.com
MiniMax Code (MCode)	`mcode`	npmjs.com/package/@minimax-ai/code
Grok Build	`grok`	github.com/xai-org/grok-build

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

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

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

Claude Code Teammate Mode

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

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:

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

Configuration

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

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

Use Cases

Feature Development: Copy session data when creating feature branches to maintain project context
Experimentation: Start fresh when testing unrelated changes
Collaboration: Share session state across team worktrees
Context Preservation: Maintain long conversations across multiple development branches

Copying Gitignored Files into New Worktrees

Shared convention: same file name and semantics as Claude Code, Conductor, OpenAI Codex, and git-worktreeinclude, so an existing .worktreeinclude works with CCManager unchanged
No configuration: the copy runs whenever a .worktreeinclude file exists
Safe by construction: a file is copied only if it both matches a pattern and is actually gitignored, so tracked files are never duplicated
Hook-friendly: files are copied before the post-creation worktree hook runs, so hook commands can rely on them

For pattern syntax, the exact selection rule, and troubleshooting, see docs/worktree-include.md.

Restoring Sessions After a Restart

Restore previous sessions

Found 2 sessions from the last time ccmanager ran. Start them again?

  feature-login — Main
  fix-timeout (review) — Codex

> Restore
  Don't restore

What is restored: each session's command preset is run again in its worktree, under the name you had given it. The previous terminal output and the conversation held inside the assistant are not restored — restoring means starting the same command again, not resuming where it left off. (To carry conversation context into a new worktree, see Session Data Copying.)
Survives a crash: the record is written as sessions come and go, not on exit, so a crash, a kill -9, or a closed terminal leaves it intact.
Only sessions that were still open: a session you killed, or one whose command exited on its own, is dropped from the record and is not offered.
Declining is remembered: choosing "Don't restore" forgets those sessions, so the offer does not come back on the next start.
Scope: normally only the repository you are opening is considered. In Multi-Project Mode the sessions of every recorded project are offered together at startup.
Other running instances: sessions belonging to another CCManager that is still open are left alone, so they are not started a second time.

The record lives in ~/.config/ccmanager/sessions.json (%APPDATA%\ccmanager\sessions.json on Windows).

Status Change Hooks

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.

Overview

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.

Worktree Hooks

Worktree hooks execute custom commands when worktrees are created, enabling automation of development environment setup.

Features

Post-creation hook: Run commands after a worktree is created
Environment variables: Access worktree path, branch name, and git root
Non-blocking execution: Hooks run asynchronously without delaying operations
Error resilience: Hook failures don't prevent worktree creation

Use Cases

Set up development dependencies (npm install, bundle install)
Configure IDE settings per branch
Send notifications when worktrees are created
Initialize branch-specific configurations

For configuration and examples, see docs/worktree-hooks.md.

Automatic Worktree Directory Generation

CCManager can automatically generate worktree directory paths based on branch names, streamlining the worktree creation process.

Auto-generate paths: No need to manually specify directories
Customizable patterns: Use placeholders like {branch} in your pattern
Smart sanitization: Branch names are automatically made filesystem-safe

For detailed configuration and examples, see docs/worktree-auto-directory.md.

Auto Approval (Experimental)

CCManager can automatically approve Claude Code prompts that don't require user permission, reducing manual intervention while maintaining safety for sensitive operations.

Features

Automatic decision: Uses Claude (Haiku) to analyze prompts and determine if they need manual approval
Custom commands: Replace the default verifier with your own script or different AI model
Safe fallback: Always defaults to manual approval on errors or timeouts
Interruptible: Press any key to cancel auto-approval and review manually

Quick Start

Navigate to Global Configuration → Other & Experimental
Enable Auto Approval (experimental)
(Optional) Configure a custom command for verification

For detailed configuration and usage, see docs/auto-approval.md.

Devcontainer Integration

Features

Host-based management: CCManager runs on your host machine, managing sessions inside containers
Seamless integration: All existing features (presets, status hooks, etc.) work with devcontainers
Security-focused: Compatible with Anthropic's recommended devcontainer configurations
Persistent state: Configuration and history persist across container recreations

Usage

# Start CCManager with devcontainer support
npx ccmanager --devc-up-command "<your devcontainer up command>" \
              --devc-exec-command "<your devcontainer exec command>"

The devcontainer integration requires both commands:

--devc-up-command: Any command to start the devcontainer
--devc-exec-command: Any command to execute inside the container

Benefits

Safe experimentation: Run commands like claude --dangerously-skip-permissions without risk

For detailed setup and configuration, see docs/devcontainer.md.

Multi-Project Mode

CCManager can manage multiple git repositories from a single interface, allowing you to organize and navigate between different projects and their worktrees efficiently.

Quick Start

# Set the root directory containing your git projects
export CCMANAGER_MULTI_PROJECT_ROOT="/path/to/your/projects"

# Run CCManager in multi-project mode
npx ccmanager --multi-project

Features

Automatic project discovery: Recursively finds all git repositories
Recent projects: Frequently used projects appear at the top
Vi-like search: Press / to filter projects or worktrees
Session persistence: Sessions remain active when switching projects
Visual indicators: See session counts [active/busy/waiting] for each project

Navigation

Project List: Select from all discovered git repositories
Worktree Menu: Manage worktrees for the selected project
Session View: Interact with your AI assistant

Use B key to navigate back from worktrees to project list.

For detailed configuration and usage, see docs/multi-project.md.

Git Worktree Configuration

CCManager can display enhanced git status information for each worktree when Git's worktree configuration extension is enabled.

# Enable enhanced status tracking
git config extensions.worktreeConfig true

With this enabled, you'll see:

File changes: +10 -5 (additions/deletions)
Commit tracking: ↑3 ↓1 (ahead/behind parent branch)
Parent branch context: Shows which branch the worktree was created from

For complete setup instructions and troubleshooting, see docs/git-worktree-config.md.

Development

# Install dependencies
npm install

# Run in development mode
bun run dev

# Build
bun run build

# Run tests
npm test

# Run linter
bun run lint

# Run type checker
bun run typecheck

kbwo/ccmanager(opens in a new tab)

README

CCManager - AI Code Agent Session Manager

Features

Why CCManager over Claude Squad?

🚀 No tmux dependency

👁️ Real-time session monitoring

🎯 Simple and intuitive interface

Install

Local Development

Usage

Keyboard Shortcuts

Default Shortcuts

Customizing Shortcuts

Restrictions

Per-Project Configuration

Configuring with an AI coding agent

Supported AI Assistants

Command Configuration

Features

Quick Start

Claude Code Teammate Mode

Creating Worktrees in the Background

Session Data Copying

Features

How It Works

Configuration

Use Cases

Copying Gitignored Files into New Worktrees

Restoring Sessions After a Restart

Status Change Hooks

Overview

Worktree Hooks

Features

Use Cases

Automatic Worktree Directory Generation

Auto Approval (Experimental)

Features

Quick Start

Devcontainer Integration

Features

Usage

Benefits

Multi-Project Mode

Quick Start

Features

Navigation

Git Worktree Configuration

Development

README

CCManager - AI Code Agent Session Manager

Features

Why CCManager over Claude Squad?

🚀 No tmux dependency

👁️ Real-time session monitoring

🎯 Simple and intuitive interface

Install

Local Development

Usage

Keyboard Shortcuts

Default Shortcuts

Customizing Shortcuts

Restrictions

Per-Project Configuration

Configuring with an AI coding agent

Supported AI Assistants

Command Configuration

Features

Quick Start

Claude Code Teammate Mode

Creating Worktrees in the Background

Session Data Copying

Features

How It Works

Configuration

Use Cases

Copying Gitignored Files into New Worktrees

Restoring Sessions After a Restart

Status Change Hooks

Overview