CCManager - AI Code Assistant Session Manager

CCManager is a TUI application for managing multiple AI coding assistant sessions across Git worktrees, with optional Zellij integration.

Features

• Run multiple AI coding sessions in parallel across different Git worktrees
• Choose between claude, codex, Codex App, and Cursor
• Open external apps for worktrees on macOS when appropriate
• Switch between sessions seamlessly
• Visual status indicators for busy / waiting / idle states
• Create, merge, and delete worktrees from within the app
• Smart worktree placement outside the main project directory
• Configurable keyboard shortcuts
• Command presets with fallback arguments
• Configurable state detection strategies
• Status change hooks for automation and notifications
• Optional Zellij integration for separate tabs per worktree

Install

npm install
npm run build
npm start

Usage

npx ccmanager

Run without auto-launching Zellij:

npx ccmanager --no-zellij

Environment Variables

CCMANAGER_CLAUDE_ARGS

export CCMANAGER_CLAUDE_ARGS="--resume"
npx ccmanager

CCMANAGER_CODEX_ARGS

export CCMANAGER_CODEX_ARGS="--temperature 0.2"
npx ccmanager

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

Command Selection

When creating a new session, CCManager can choose between several assistants and app targets:

• Claude Code: in-app terminal session using claude
• Codex CLI: in-app terminal session using codex
• Codex App: opens the selected worktree in the Codex desktop app on macOS
• Cursor: opens the selected worktree in the Cursor editor

Notes:

• Cursor falls back to open -a Cursor on macOS when the cursor CLI is unavailable.
• Codex App launches via the macOS app bundle com.openai.codex.

Keyboard Shortcuts

Default Shortcuts

• Ctrl+E: Return to menu from active session
• Escape: Cancel / go back

Shortcuts can be customized from the Configuration menu or via ~/.config/ccmanager/config.json.

Worktree Management

Smart Worktree Placement

By default, CCManager creates worktrees in a sibling directory like:

• ../{project}-worktrees/{project}-{branch}

Examples:

• project A + branch feature/x → ../A-worktrees/A-feature-x
• project myproject + branch bugfix/login-issue → ../myproject-worktrees/myproject-bugfix-login-issue

You can customize the pattern from the Configuration menu.

Supported AI Assistants

CCManager supports configurable state detection strategies for different tools.

Claude Code

• Command: claude
• Default state detection strategy for Claude-style prompts

Codex CLI

• Command: codex
• Codex-specific state detection strategy

Gemini CLI

• Can be configured through command presets
• Gemini-specific state detection strategy is available

See docs/gemini-support.md and docs/command-config.md for details.

Command Configuration

CCManager supports configurable command presets with:

• Main command
• Primary arguments
• Fallback arguments
• Detection strategy
• Optional preset selection on session start

See docs/command-config.md for examples.

Status Change Hooks

CCManager can execute custom commands when a session changes state. This is useful for notifications, logging, and automation.

See docs/status-hooks.md for setup details.

Git Worktree Configuration

CCManager can display enhanced git status information for each worktree when Git worktree config is enabled:

git config extensions.worktreeConfig true

See docs/git-worktree-config.md for details.

Development

npm install
npm run dev
npm run build
npm test
npm run lint
npm run typecheck