ccmanager tracks nine coding agents across git worktrees

Three states, and only one of them needs you

The feature the project leads with is not parallel sessions, it is knowing which session is blocked. Each assistant has its own state detection strategy, and every session resolves to one of three values: idle, meaning ready for new input; busy, meaning processing a request; and waiting, meaning awaiting user confirmation.

Waiting is the state that matters, because a coding agent sitting on a permission prompt looks identical to one thinking, and the cost of guessing wrong is a stalled worktree and an afternoon of wondering why nothing moved. The menu shows the state directly rather than inferring it from process activity.

Detection is per tool rather than generic, which is why the supported list matters more than the count. The table names the command each assistant is launched with: claude for Claude Code as the default, gemini, codex, cursor-agent, copilot, cline, opencode, kimi, and mcode for MiniMax Code. That is nine rows. The repository description and the opening paragraph both list only eight, omitting MiniMax Code, so the description is out of date rather than the table. Gemini has its own support document for CCManager-specific configuration.

The tool is a terminal UI rather than a daemon, which is why the session model is interactive: you pick a session from a menu, work in it, and press Ctrl+E to come back.

Worktrees are created, merged and deleted from the menu

Git worktree management is built in rather than delegated. You can create, merge and delete worktrees from within the app, and multiple repositories can be managed from a single interface, which covers the common case of a service plus its frontend plus its library living in three checkouts.

Two features exist specifically because a worktree is a clean checkout. The first is copying Claude Code session data between worktrees, so conversation context follows you instead of resetting. The second is .worktreeinclude, which carries gitignored project files into newly created worktrees, with .env files and local certificates given as the examples. Without it a fresh worktree is missing exactly the files that make the project runnable, which is a reliable way to lose ten minutes per branch.

Sessions also survive the manager rather than the terminal. On restart, CCManager reopens the sessions that were running when it last exited or crashed, so closing the TUI is not the same as killing the work. The feature list also covers configurable keyboard shortcuts, command presets with automatic fallback, status change hooks for automation and notifications, and devcontainer integration.

One entry is marked experimental and deserves its own attention: Auto Approval, which automatically approves prompts judged safe using AI verification. That is a second agent deciding what your first agent is allowed to do, and the README offers no threshold, audit log or opt-out detail for it.

The Claude Squad case is written by CCManager

The README contains a section arguing for CCManager over Claude Squad, and it is worth reading as advocacy rather than as a measurement. The stated position is that both tools solve the same problem of managing multiple Claude Code sessions by different means, and that anyone who likes tmux-based workflows should stay with Claude Squad. CCManager's argument is that it has no tmux dependency, being self-contained, and that it shows real-time session state in its menu.

The specific criticism is about AutoYes. The claim is that Claude Squad's AutoYes feature bypasses Claude Code's built-in security confirmations, which the README calls not recommended for safe operation, and that Claude Squad does not surface session states in its menu.

Neither claim is tested or sourced in the documentation, so treat them as the maintainer's reading. The AutoYes point is the sharper of the two and deserves your own attention, with a caveat that cuts the other way: CCManager ships an experimental Auto Approval feature that approves prompts automatically using AI verification. If bypassing a security confirmation is the concern, an AI gate in front of that confirmation is a mitigation rather than a refutation, but it is a different mechanism and one the documentation does not describe in enough detail to evaluate. Decide for yourself which you trust more.

The documented config example is not valid JSON

Shortcuts default to Ctrl+E to return to the menu from an active session and Escape to cancel or go back in dialogs. They can be changed from the main menu under Global Configuration, then Configure Shortcuts, or through a file at ~/.config/ccmanager/config.json, with .ccmanager.json doing the same job per project.

The example given for the config file carries a comment on its first line, which JSON does not allow:

// config.json (new format)
{
  "shortcuts": {
    "returnToMenu": {
      "ctrl": true,
      "key": "r"
    },
    "cancel": {
      "key": "escape"
    }
  }
}

Copy it without that line and it is a valid document. It is a small thing, but it is the kind that produces a parse error with no useful message.

Two restrictions are documented alongside. A shortcut must include a modifier key, Ctrl, except for special keys such as Escape. And three combinations are reserved and cannot be bound at all: Ctrl+C, Ctrl+D, and Ctrl+[ , which is the terminal's equivalent of Escape and would make cancel unreachable.

Migration is handled for you. Shortcuts stored in shortcuts.json are moved into config.json automatically on first use, and a shortcuts.example.json sits at the repository root as a starting point.

Project config always beats global config

Per-project settings come from a .ccmanager.json file in the root of your git repository. Those settings are merged with the global config at ~/.config/ccmanager/config.json, and the rule is unambiguous: project settings always take priority.

That ordering is what makes a repository portable. A worktree created from a repository that carries its own configuration gets the same behaviour as the original without anyone editing a home directory, which is the whole point of running several copies of a project in parallel. The same file also carries shortcuts, tying back to the previous section.

The README points to docs/project-config.md for the detailed option list and examples rather than duplicating it, which is a reasonable choice for a file with this many keys. If you are configuring from an agent rather than by hand, there is a separate route described below.

Session data is scoped the same way in spirit, though not through this file: copying Claude Code conversation data between worktrees is an explicit action rather than something configured, so a worktree does not silently inherit another worktree's history.

The repository doubles as a plugin marketplace

CCManager is also a distribution point for its own configuration schema. A skill named ccmanager-config teaches Claude Code or Codex the full configuration format and ships a validator for it, installed through the plugin marketplace mechanism of whichever agent you use:

# 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

The two agent CLIs take parallel commands, which is convenient given the project's premise that you may well have both installed. After installation you are meant to ask in natural language, with the README suggesting requests such as setting this repository up to run codex in ccmanager, asking to be notified when a session is waiting for input, or asking why a .ccmanager.json file is being ignored.

Shipping a validator with the schema is the part that matters. Configuration drift is the failure mode nobody notices until a worktree behaves differently from its sibling, and a validator plus a language model that has read the schema is a reasonable answer to that. The plugin's own README lives under plugins/ccmanager-config, and the marketplace layout is visible in the repository as .claude-plugin/, plugins/ and .claude/ at the top level.

Command presets fall back three times before giving up

The command used to launch a session is configurable, with a chain of fallbacks rather than a single setting. You can set the main command, which defaults to claude, and primary arguments, with --resume given as the example for continuing an existing session. You can then define fallback arguments used when the primary configuration fails. Finally there is an automatic retry with no arguments at all as the last resort.

The reason for the chain is agent CLIs that change their own command-line surface between versions. A flag that worked last month can become invalid, and with a single hardcoded argument set that failure takes down every session at once. Degrading to a bare launch is a better outcome than nothing working.

The configuration is reached through Global Configuration, then Configure Command Presets, where you set the desired arguments, optionally set fallback arguments, and save. That is a menu path rather than a config file key, which is consistent with the rest of the tool: keyboard shortcuts have both a UI and a file route, while command presets are described only through the interface.

The experimental Auto Approval feature and these presets are the two places where CCManager second-guesses the agent it launches. Both change what happens when an agent asks permission, and both are worth understanding before you leave them enabled across nine assistants.

Development runs on Bun, installation runs on npm

The distribution and the development toolchain are not the same thing, which shows up in package.json. Consumers install with npm install -g ccmanager, or run npx ccmanager without installing at all. Contributors instead clone and run npm install, bun run build, npm start. The start script invokes the built entry through bun with the --no-env-file flag, so the local run path expects the Bun runtime even though the package is published to npm.

Prebuilt native binaries are published per platform as optional dependencies, and every one is pinned to the exact same version as the package: ccmanager-darwin-arm64, ccmanager-darwin-x64, ccmanager-linux-arm64, ccmanager-linux-x64 and ccmanager-win32-x64, all at 4.4.4 under the @kodaikabasawa scope rather than the package's own name. That exact pinning is the right call, since a mismatched binary would fail at runtime rather than at install. The set covers five targets, with no Linux musl build and no Windows on ARM.

The release path is gated. prepublishOnly runs lint, typecheck, test and build in that order before anything is published, and the scripts cover building binaries for a native target or for all targets, plus a dry-run mode for the package publish step. Version 4.4.4 in the manifest matches the newest tag, and the recent history is three patch releases inside three weeks: v4.4.2, v4.4.3 and v4.4.4. The project is MIT licensed, authored by Kodai Kabasawa, with 1,256 stars, 93 forks and 9 open issues, and the last push to main was on 2026-09-27.

Editorial conclusion

ccmanager fits a workflow built on parallel worktrees where you lose track of which agent is stuck on a prompt, since the waiting state is the whole point and the alternative is scrolling terminals. Read the Claude Squad comparison as a project claim rather than a benchmark, since it is written by CCManager and the AutoYes criticism there does not apply cleanly to its own experimental AI-verified Auto Approval feature, which is worth evaluating on its own terms. Copy the shortcut config carefully, because the documented example has a comment line that is not valid JSON. And note that package.json still describes the tool as a Claude Code session manager while the README covers nine assistants.

Frequently asked questions

Official sources

1. Issues
2. kbwo/ccmanager on GitHub
3. License: MIT
4. README
5. Releases