ccmanager
Advanced tools
TUI application for managing multiple Claude Code sessions across Git worktrees
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
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:
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:
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 -g ccmanager
npm install
npm run build
npm start
ccmanager
Or run without installing:
npx ccmanager
You can customize keyboard shortcuts in two ways:
~/.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.
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.
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 |
Each assistant has its own state detection strategy to properly track:
See Gemini Support Documentation for CCManager-specific configuration.
CCManager supports configuring the command and arguments used to run Claude Code sessions, with automatic fallback options for reliability.
claude)--resume)--resume for resuming sessions)For detailed configuration options and examples, see docs/command-config.md.
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.
claude command sessions.--teammate-mode in your preset args, your value takes priority.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.
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.
When creating a new worktree, CCManager:
~/.claude/projects/[source-path] to ~/.claude/projects/[target-path]The default choice (copy or start fresh) will be pre-selected when creating new worktrees.
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:
For detailed setup instructions, see docs/state-hooks.md.
Worktree hooks execute custom commands when worktrees are created, enabling automation of development environment setup.
npm install, bundle install)For configuration and examples, see docs/worktree-hooks.md.
CCManager can automatically generate worktree directory paths based on branch names, streamlining the worktree creation process.
{branch} in your patternFor detailed configuration and examples, see docs/worktree-auto-directory.md.
CCManager can automatically approve Claude Code prompts that don't require user permission, reducing manual intervention while maintaining safety for sensitive operations.
For detailed configuration and usage, see docs/auto-approval.md.
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.
# 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 containerclaude --dangerously-skip-permissions without riskFor detailed setup and configuration, see docs/devcontainer.md.
CCManager can manage multiple git repositories from a single interface, allowing you to organize and navigate between different projects and their worktrees efficiently.
# 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
/ to filter projects or worktrees[active/busy/waiting] for each projectUse B key to navigate back from worktrees to project list.
For detailed configuration and usage, see docs/multi-project.md.
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:
+10 -5 (additions/deletions)↑3 ↓1 (ahead/behind parent branch)For complete setup instructions and troubleshooting, see docs/git-worktree-config.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
FAQs
TUI application for managing multiple Claude Code sessions across Git worktrees
The npm package ccmanager receives a total of 443 weekly downloads. As such, ccmanager popularity was classified as not popular.
We found that ccmanager demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Multiple high-impact npm maintainers confirm they have been targeted in the same social engineering campaign that compromised Axios.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.