Skip to content
Back to search

ccmanager

MarketplaceWorks with Claude CodeGitHub

Plugins that help you work with CCManager, the TUI session manager for AI coding agents across git worktrees

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/kbwo-ccmanager/badge.svg)](/listings/kbwo-ccmanager)

HTML

<a href="/listings/kbwo-ccmanager"><img src="/api/listings/kbwo-ccmanager/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

npm install -g ccmanager

Local Development

npm install
bun run build
npm start

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 18 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  3. "name": "ccmanager",
  4. "description": "Plugins that help you work with CCManager, the TUI session manager for AI coding agents across git worktrees",
  5. "owner": {
  6. "name": "kbwo",
  7. "url": "https://github.com/kbwo"
  8. },
  9. "plugins": [
  10. {
  11. "name": "ccmanager-config",
  12. "description": "Writes, reviews, and fixes CCManager configuration files (.ccmanager.json and the global config.json): command presets, status/worktree hooks, worktree auto-directory patterns, merge arguments, shortcuts, and auto-approval.",
  13. "source": "./plugins/ccmanager-config",
  14. "category": "productivity",
  15. "homepage": "https://github.com/kbwo/ccmanager/tree/main/plugins/ccmanager-config"
  16. }
  17. ]
  18. }
README.md · README · 435 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # CCManager - AI Code Agent Session Manager
  2. [![Mentioned in Awesome Gemini CLI](https://awesome.re/mentioned-badge.svg)](https://github.com/Piebald-AI/awesome-gemini-cli)
  3. 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.
  4. https://github.com/user-attachments/assets/15914a88-e288-4ac9-94d5-8127f2e19dbf
  5. ## Features
  6. - Run multiple AI assistant sessions in parallel across different Git worktrees
  7. - **Multi-project support**: Manage multiple git repositories from a single interface
  8. - Support for multiple AI coding assistants (Claude Code, Gemini CLI, Codex CLI, Cursor Agent, Copilot CLI, Cline CLI, OpenCode, Kimi CLI)
  9. - Switch between sessions seamlessly
  10. - Visual status indicators for session states (busy, waiting, idle)
  11. - Create, merge, and delete worktrees from within the app
  12. - **Restore sessions after a restart**: reopen the sessions that were running when CCManager last exited or crashed
  13. - **Copy Claude Code session data** between worktrees to maintain conversation context
  14. - **`.worktreeinclude` support**: carry gitignored project files (`.env`, local certs) into newly created worktrees
  15. - Configurable keyboard shortcuts
  16. - Command presets with automatic fallback support
  17. - Configurable state detection strategies for different CLI tools
  18. - Status change hooks for automation and notifications
  19. - Devcontainer integration
  20. - **Auto Approval (experimental)**: Automatically approve safe prompts using AI verification
  21. ## Why CCManager over Claude Squad?
  22. Both tools solve the same problem - managing multiple Claude Code sessions - but take different approaches.
  23. **If you love tmux-based workflows, stick with Claude Squad!** It's a great tool that leverages tmux's power for session management.
  24. CCManager is for developers who want:
  25. ### 🚀 No tmux dependency
  26. 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.
  27. ### 👁️ Real-time session monitoring
  28. CCManager shows the actual state of each Claude Code session directly in the menu:
  29. - **Waiting**: Claude is asking for user input
  30. - **Busy**: Claude is processing
  31. - **Idle**: Ready for new tasks
  32. 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.
  33. ### 🎯 Simple and intuitive interface
  34. 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.
  35. ## Install
  36. ```bash
  37. npm install -g ccmanager
  38. ```
  39. ### Local Development
  40. ```bash
  41. npm install
  42. bun run build
  43. npm start
  44. ```
  45. ## Usage
  46. ```bash
  47. ccmanager
  48. ```
  49. Or run without installing:
  50. ```bash
  51. npx ccmanager
  52. ```
  53. ## Keyboard Shortcuts
  54. ### Default Shortcuts
  55. - **Ctrl+E**: Return to menu from active session
  56. - **Escape**: Cancel/Go back in dialogs
  57. ### Customizing Shortcuts
  58. You can customize keyboard shortcuts in two ways:
  59. 1. **Through the UI**: Select **Global Configuration** → **Configure Shortcuts** from the main menu
  60. 2. **Configuration file**: Edit `~/.config/ccmanager/config.json` or `.ccmanager.json` for per-project settings (see [Per-Project Configuration](#per-project-configuration))
  61. Example configuration:
  62. ```json
  63. // config.json (new format)
  64. {
  65. "shortcuts": {
  66. "returnToMenu": {
  67. "ctrl": true,
  68. "key": "r"
  69. },
  70. "cancel": {
  71. "key": "escape"
  72. }
  73. }
  74. }
  75. ```
  76. Note: Shortcuts from `shortcuts.json` will be automatically migrated to `config.json` on first use.
  77. ### Restrictions
  78. - Shortcuts must use a modifier key (Ctrl) except for special keys like Escape
  79. - The following key combinations are reserved and cannot be used:
  80. - Ctrl+C
  81. - Ctrl+D
  82. - Ctrl+[ (equivalent to Escape)
  83. ## Per-Project Configuration
  84. 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.
  85. 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.
  86. For detailed configuration options and examples, see [docs/project-config.md](docs/project-config.md).
  87. ### Configuring with an AI coding agent
  88. 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:
  89. ```bash
  90. # Claude Code
  91. claude plugin marketplace add kbwo/ccmanager
  92. claude plugin install ccmanager-config@ccmanager
  93. # Codex CLI
  94. codex plugin marketplace add kbwo/ccmanager
  95. codex plugin add ccmanager-config@ccmanager
  96. ```
  97. 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](plugins/ccmanager-config/README.md).
  98. ## Supported AI Assistants
  99. CCManager supports multiple AI coding assistants with tailored state detection for each:
  100. | Assistant | Command | Installation |
  101. |-----------|---------|--------------|
  102. | Claude Code (Default) | `claude` | [code.claude.com](https://code.claude.com/docs/en/setup) |
  103. | Gemini CLI | `gemini` | [github.com/google-gemini/gemini-cli](https://github.com/google-gemini/gemini-cli) |
  104. | Codex CLI | `codex` | [github.com/openai/codex](https://github.com/openai/codex) |
  105. | Cursor Agent | `cursor-agent` | [cursor.com/cli](https://cursor.com/docs/cli/overview) |
  106. | Copilot CLI | `copilot` | [github.com/github/copilot-cli](https://github.com/github/copilot-cli) |
  107. | Cline CLI | `cline` | [github.com/cline/cline](https://github.com/cline/cline) |
  108. | OpenCode | `opencode` | [opencode.ai/docs](https://opencode.ai/docs) |
  109. | Kimi CLI | `kimi` | [kimi-cli.com](https://www.kimi-cli.com/en/) |
  110. | MiniMax Code (MCode) | `mcode` | [npmjs.com/package/@minimax-ai/code](https://www.npmjs.com/package/@minimax-ai/code) |
  111. | Grok Build | `grok` | [github.com/xai-org/grok-build](https://github.com/xai-org/grok-build) |
  112. Each assistant has its own state detection strategy to properly track:
  113. - **Idle**: Ready for new input
  114. - **Busy**: Processing a request
  115. - **Waiting**: Awaiting user confirmation
  116. See [Gemini Support Documentation](docs/gemini-support.md) for CCManager-specific configuration.
  117. ## Command Configuration
  118. ![Screenshot From 2025-06-18 16-43-27](https://github.com/user-attachments/assets/47d62483-ce81-4340-8687-8afcae93d5db)
  119. CCManager supports configuring the command and arguments used to run Claude Code sessions, with automatic fallback options for reliability.
  120. ### Features
  121. - Configure the main command (default: `claude`)
  122. - Set primary arguments (e.g., `--resume`)
  123. - Define fallback arguments if the primary configuration fails
  124. - Automatic retry with no arguments as final fallback
  125. ### Quick Start
  126. 1. Navigate to **Global Configuration** → **Configure Command Presets**
  127. 2. Set your desired arguments (e.g., `--resume` for resuming sessions)
  128. 3. Optionally set fallback arguments
  129. 4. Save changes
  130. For detailed configuration options and examples, see [docs/command-config.md](docs/command-config.md).
  131. ## Claude Code Teammate Mode
  132. 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.
  133. - **Automatic**: No configuration needed. CCManager injects the flag for all `claude` command sessions.
  134. - **Override**: If you explicitly specify `--teammate-mode` in your preset args, your value takes priority.
  135. - **Non-claude commands**: Other AI assistants (Gemini, Codex, etc.) are not affected.
  136. 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.
  137. ## Creating Worktrees in the Background
  138. 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:
  139. - **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.
  140. - **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.
  141. ## Session Data Copying
  142. 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.
  143. ### Features
  144. - **Seamless Context Transfer**: Continue conversations in new worktrees without losing context
  145. - **Configurable Default**: Set whether to copy session data by default
  146. - **Per-Creation Choice**: Decide on each worktree creation whether to copy data
  147. - **Safe Operation**: Copying is non-fatal - worktree creation succeeds even if copying fails
  148. ### How It Works
  149. When creating a new worktree, CCManager:
  150. 1. Asks whether to copy session data from the current worktree
  151. 2. Copies all session files from `~/.claude/projects/[source-path]` to `~/.claude/projects/[target-path]`
  152. 3. Preserves conversation history, project context, and Claude Code state
  153. 4. Allows immediate continuation of conversations in the new worktree
  154. ### Configuration
  155. 1. Navigate to **Global Configuration** → **Configure Worktree**
  156. 2. Toggle **Copy Session Data** to set the default behavior
  157. 3. Save changes
  158. The default choice (copy or start fresh) will be pre-selected when creating new worktrees.
  159. ### Use Cases
  160. - **Feature Development**: Copy session data when creating feature branches to maintain project context
  161. - **Experimentation**: Start fresh when testing unrelated changes
  162. - **Collaboration**: Share session state across team worktrees
  163. - **Context Preservation**: Maintain long conversations across multiple development branches
  164. ## Copying Gitignored Files into New Worktrees
  165. 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.
  166. - **Shared convention**: same file name and semantics as Claude Code, Conductor, OpenAI Codex, and `git-worktreeinclude`, so an existing `.worktreeinclude` works with CCManager unchanged
  167. - **No configuration**: the copy runs whenever a `.worktreeinclude` file exists
  168. - **Safe by construction**: a file is copied only if it both matches a pattern and is actually gitignored, so tracked files are never duplicated
  169. - **Hook-friendly**: files are copied before the post-creation worktree hook runs, so hook commands can rely on them
  170. For pattern syntax, the exact selection rule, and troubleshooting, see [docs/worktree-include.md](docs/worktree-include.md).
  171. ## Restoring Sessions After a Restart
  172. 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:
  173. ```
  174. Restore previous sessions
  175. Found 2 sessions from the last time ccmanager ran. Start them again?
  176. feature-login — Main
  177. fix-timeout (review) — Codex
  178. > Restore
  179. Don't restore
  180. ```
  181. - **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](#session-data-copying).)
  182. - **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.
  183. - **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.
  184. - **Declining is remembered**: choosing "Don't restore" forgets those sessions, so the offer does not come back on the next start.
  185. - **Scope**: normally only the repository you are opening is considered. In [Multi-Project Mode](#multi-project-mode) the sessions of every recorded project are offered together at startup.
  186. - **Other running instances**: sessions belonging to another CCManager that is still open are left alone, so they are not started a second time.
  187. The record lives in `~/.config/ccmanager/sessions.json` (`%APPDATA%\ccmanager\sessions.json` on Windows).
  188. ## Status Change Hooks
  189. 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.
  190. ### Overview
  191. Status hooks allow you to:
  192. - Get notified when Claude needs your input
  193. - Track time spent in different states
  194. - Trigger automations based on session activity
  195. - Integrate with notification systems like [noti](https://github.com/variadico/noti)
  196. For detailed setup instructions, see [docs/state-hooks.md](docs/status-hooks.md).
  197. ## Worktree Hooks
  198. Worktree hooks execute custom commands when worktrees are created, enabling automation of development environment setup.
  199. ### Features
  200. - **Post-creation hook**: Run commands after a worktree is created
  201. - **Environment variables**: Access worktree path, branch name, and git root
  202. - **Non-blocking execution**: Hooks run asynchronously without delaying operations
  203. - **Error resilience**: Hook failures don't prevent worktree creation
  204. ### Use Cases
  205. - Set up development dependencies (`npm install`, `bundle install`)
  206. - Configure IDE settings per branch
  207. - Send notifications when worktrees are created
  208. - Initialize branch-specific configurations
  209. For configuration and examples, see [docs/worktree-hooks.md](docs/worktree-hooks.md).
  210. ## Automatic Worktree Directory Generation
  211. CCManager can automatically generate worktree directory paths based on branch names, streamlining the worktree creation process.
  212. - **Auto-generate paths**: No need to manually specify directories
  213. - **Customizable patterns**: Use placeholders like `{branch}` in your pattern
  214. - **Smart sanitization**: Branch names are automatically made filesystem-safe
  215. For detailed configuration and examples, see [docs/worktree-auto-directory.md](docs/worktree-auto-directory.md).
  216. ## Auto Approval (Experimental)
  217. CCManager can automatically approve Claude Code prompts that don't require user permission, reducing manual intervention while maintaining safety for sensitive operations.
  218. ### Features
  219. - **Automatic decision**: Uses Claude (Haiku) to analyze prompts and determine if they need manual approval
  220. - **Custom commands**: Replace the default verifier with your own script or different AI model
  221. - **Safe fallback**: Always defaults to manual approval on errors or timeouts
  222. - **Interruptible**: Press any key to cancel auto-approval and review manually
  223. ### Quick Start
  224. 1. Navigate to **Global Configuration** → **Other & Experimental**
  225. 2. Enable **Auto Approval (experimental)**
  226. 3. (Optional) Configure a custom command for verification
  227. For detailed configuration and usage, see [docs/auto-approval.md](docs/auto-approval.md).
  228. ## Devcontainer Integration
  229. 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.
  230. ### Features
  231. - **Host-based management**: CCManager runs on your host machine, managing sessions inside containers
  232. - **Seamless integration**: All existing features (presets, status hooks, etc.) work with devcontainers
  233. - **Security-focused**: Compatible with Anthropic's recommended devcontainer configurations
  234. - **Persistent state**: Configuration and history persist across container recreations
  235. ### Usage
  236. ```bash
  237. # Start CCManager with devcontainer support
  238. npx ccmanager --devc-up-command "<your devcontainer up command>" \
  239. --devc-exec-command "<your devcontainer exec command>"
  240. ```
  241. The devcontainer integration requires both commands:
  242. - `--devc-up-command`: Any command to start the devcontainer
  243. - `--devc-exec-command`: Any command to execute inside the container
  244. ### Benefits
  245. - **Safe experimentation**: Run commands like `claude --dangerously-skip-permissions` without risk
  246. For detailed setup and configuration, see [docs/devcontainer.md](docs/devcontainer.md).
  247. ## Multi-Project Mode
  248. CCManager can manage multiple git repositories from a single interface, allowing you to organize and navigate between different projects and their worktrees efficiently.
  249. ### Quick Start
  250. ```bash
  251. # Set the root directory containing your git projects
  252. export CCMANAGER_MULTI_PROJECT_ROOT="/path/to/your/projects"
  253. # Run CCManager in multi-project mode
  254. npx ccmanager --multi-project
  255. ```
  256. ### Features
  257. - **Automatic project discovery**: Recursively finds all git repositories
  258. - **Recent projects**: Frequently used projects appear at the top
  259. - **Vi-like search**: Press `/` to filter projects or worktrees
  260. - **Session persistence**: Sessions remain active when switching projects
  261. - **Visual indicators**: See session counts `[active/busy/waiting]` for each project
  262. ### Navigation
  263. 1. **Project List**: Select from all discovered git repositories
  264. 2. **Worktree Menu**: Manage worktrees for the selected project
  265. 3. **Session View**: Interact with your AI assistant
  266. Use `B` key to navigate back from worktrees to project list.
  267. For detailed configuration and usage, see [docs/multi-project.md](docs/multi-project.md).
  268. ## Git Worktree Configuration
  269. CCManager can display enhanced git status information for each worktree when Git's worktree configuration extension is enabled.
  270. ```bash
  271. # Enable enhanced status tracking
  272. git config extensions.worktreeConfig true
  273. ```
  274. With this enabled, you'll see:
  275. - **File changes**: `+10 -5` (additions/deletions)
  276. - **Commit tracking**: `↑3 ↓1` (ahead/behind parent branch)
  277. - **Parent branch context**: Shows which branch the worktree was created from
  278. For complete setup instructions and troubleshooting, see [docs/git-worktree-config.md](docs/git-worktree-config.md).
  279. ## Development
  280. ```bash
  281. # Install dependencies
  282. npm install
  283. # Run in development mode
  284. bun run dev
  285. # Build
  286. bun run build
  287. # Run tests
  288. npm test
  289. # Run linter
  290. bun run lint
  291. # Run type checker
  292. bun run typecheck
  293. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.