CCManager - AI Agent Session Manager
Manage sessions for Claude Code, Gemini CLI, Codex CLI, and other AI coding assistants across Git worktrees and projects.
- Source repo
- kbwo/ccmanager
- Stars
- ★ 1.3k
- Last updated
- 1d ago
- License
- MIT
- Primary language
- TypeScript
- FA score
- 52/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformChatGPT · Codex · Claude Code
- Cost
- Free software; you pay for model usage
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- Developers who want to manage multiple Claude Code sessions without tmux, using a self-contained solution.
- Not a fit if
- Teams not using Git worktrees
- Developers avoiding a Node.js/Bun toolchain
- Source review
- 52/100 · Major gaps
What does this agent do, and when should you use it?
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. It enables running multiple AI assistant sessions in parallel, with seamless switching between them. The tool provides visual status indicators (busy, waiting, idle), supports creating, merging, and deleting worktrees, and can copy Claude Code session data to preserve conversation context. It also offers configurable keyboard shortcuts, command presets with fallback, status change hooks for automation, devcontainer integration, and an experimental auto-approval feature.
CCManager is a terminal UI that orchestrates AI coding assistant sessions. It runs multiple sessions in parallel using Git worktrees, displaying each session's state (busy, waiting, idle). Users can create, merge, or delete worktrees from the menu, and optionally copy Claude Code session data (from ~/.claude/projects/[source-path]) to the target worktree's corresponding path to keep context. It supports configuring command arguments and fallbacks for different CLIs, and executing custom commands on state changes (e.g., using noti for notifications). Additionally, it offers a multi-project mode (via CCMANAGER_MULTI_PROJECT_ROOT and --multi-project) that auto-discovers git repositories and allows filtering.
- Developers who want to manage multiple Claude Code sessions without tmux, using a self-contained solution.
- Developers working in multi-repo environments who need a single interface to manage AI assistant sessions across projects.
- Developers who need to maintain conversation context across branches by copying session data when creating new worktrees.
- Users who want automated notifications or logging when AI sessions change state, using status hooks.
- Developers who want to use devcontainers for isolation while keeping host-level notifications and automation.
How do you install or deploy this agent?
Install globally with npm: npm install -g ccmanager. For local development, use npm install, bun run build, and npm start.
How do you use this agent?
Run ccmanager or npx ccmanager to start. In the menu, choose Global Configuration to adjust shortcuts, command presets, and copy-session defaults. For multi-project mode, set the CCMANAGER_MULTI_PROJECT_ROOT environment variable and run npx ccmanager --multi-project.
What are this agent's strengths and limitations?
- Supports multiple AI coding assistants (Claude Code, Gemini CLI, Codex CLI, etc.), eliminating the need for separate managers.
- Real-time session status display (busy/waiting/idle) is safer than Claude Squad's AutoYes, which bypasses security confirmations.
- Seamless context retention via session data copying and worktree switching.
- Status and worktree hooks enable notifications and automation workflows.
- Devcontainer integration allows sandboxed environments while preserving host management.
- Requires Node.js and Bun for building, which may be a barrier for non-JS developers.
- Depends on Git worktrees, so it only works with Git repositories that support them.
- The auto-approval feature is experimental and may make mistakes, so it should be used cautiously.
- Multi-project mode requires setting an environment variable and may need extra configuration to discover projects correctly.
How does this agent compare with similar options?
Compared to Claude Squad, CCManager avoids a tmux dependency and provides real-time session state monitoring.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| CCManager - AI Agent Session Manager This agent | 52 · Major gaps | CLIFree + model costs | ★ 1.3k | 1d ago | TypeScript | ChatGPT · Codex · Claude Code |
| agmsg Cross-Agent Messaging | 64 · Some gaps | CLIFree | ★ 1.6k | 4d ago | Shell | Codex · Claude Code |
| Agentic Plugin Marketplace | 66 · Some gaps | Agent plugin / skillFree + model costs | ★ 41k | 1d ago | Python | Codex · Claude Code |
| claude-replay | 76 · Good | CLIFree | ★ 846 | 2d ago | JavaScript | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows: The tool executes user-configured commands (e.g., status hooks, worktree hooks, auto-approval verifier), but no explicit permission restrictions or sandboxing. User confirmation exists (e.g., auto-approval defaults to manual, interruptible), but not all operations are detailed. Data flow transparency: Documentation describes session data copying and status hooks, but not data flow and storage details. Sensitive data handling: Involves copying session data under ~/.claude/projects, but no encryption or protection measures. Dependency security: Many dependencies, but no security audit or vulnerability scanning evidence. External effects: Can create/delete worktrees, execute hook commands, but no permission boundaries. Rollback: No rollback mechanism mentioned. Source attribution: Author and repository clear, but publisher unverified. Deductions: Lack of evidence for least privilege, data protection, dependency security.
Evidence shows: README and documentation are consistent, feature descriptions align with code structure (e.g., package.json scripts). Dependencies listed in package.json, but availability not verified. Failure messages: Documentation mentions auto-approval falls back to manual on errors, but no other error handling details. Deductions: No error message examples or troubleshooting guide.
Evidence shows: Clearly targets developers, supports multiple AI assistants and scenarios (multi-project, worktrees, devcontainer). Capability boundaries: Documentation describes supported commands and features, but no explicit limitations. Trigger precision: Triggered via configuration and shortcuts, but not all trigger conditions detailed. Environment fit: Supports multiple platforms (via binary packages), but no system requirements. Deductions: Capability boundaries and trigger conditions not precise.
Evidence shows: README structure clear, with installation instructions, usage examples, configuration doc links. Naming stability: Package name and command name consistent. Examples and FAQ: Multiple doc links, but no FAQ. Known limitations: Not explicitly listed. License: MIT license clear. Versioning and changelog: package.json has version, but no CHANGELOG. Maintenance responsibility: Author and repository clear, but no maintenance commitment. Deductions: Missing known limitations and changelog.
Evidence shows: Output is TUI interface, provides real-time status and shortcuts, improves efficiency. Marginal value: Compared to Claude Squad, offers no-tmux dependency and real-time monitoring. Cost-benefit: Free and open source, but requires configuration and learning. Deductions: No performance benchmarks or user feedback.
Evidence shows: README feature descriptions partially correspond to code structure (e.g., package.json scripts), but no test results or independent verification. Cross-source corroboration: Has Awesome Gemini CLI badge, but no other independent sources. Fact-inference separation: Documentation distinguishes feature descriptions and recommendations, but not explicitly labeled. Deductions: Lack of test evidence and independent verification.
- Auto-approval uses AI to verify prompts, may misjudge, use with caution.
- Session data copying involves sensitive information, ensure trusted environment.
- Status hooks and worktree hooks execute arbitrary commands, be mindful of command sources.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
What's Changed * feat: detect opencode question prompts as waiting_input by @kbwo in https://github.com/kbwo/ccmanager/pull/346 * feat: detect Cursor plan "Ready to build?" prompt as waiting_input by @kbwo in https://github.com/kbwo/ccmanager/pull/347 Full Changelog: https://github.com/kbwo/ccmanager/compare/v4.4.8...v4.4.9View on GitHub ↗ -
Release notes excerpt
What's Changed * feat: show number shortcuts in new worktree preset selection by @kbwo in https://github.com/kbwo/ccmanager/pull/344 * feat: add Reload Config from Disk to the configuration screen by @kbwo in https://github.com/kbwo/ccmanager/pull/343 * fix: reject invalid generated branch names instead of crashing by @kbwo in https://github.com/kbwo/ccmanager/pull/345 Full Changelog: https://github.com/kbwo/ccmanager/compare/v4.4.7...v4.4.8View on GitHub ↗ -
Release notes excerpt
What's Changed * feat: advance cursor to next row after space toggle in delete worktree list by @kbwo in https://github.com/kbwo/ccmanager/pull/342 * feat: add Grok Build support by @kbwo in https://github.com/kbwo/ccmanager/pull/341 Full Changelog: https://github.com/kbwo/ccmanager/compare/v4.4.6...v4.4.7View on GitHub ↗