kbwo/ccmanager: a TUI session manager for Claude Code and seven other coding agents

The parallel session problem ccmanager targets

Running one AI coding agent in one terminal works until you want two. A second session means a second checkout, or a stash dance, or two agents editing the same files. ccmanager's answer is to treat each session as belonging to a Git worktree, then put a single terminal menu in front of all of them. The README describes it as "a CLI application for managing multiple AI coding assistant sessions across Git worktrees and projects."

The audience is narrow but real: developers who keep three or four agent tasks in flight and lose track of which one is blocked on a confirmation prompt. ccmanager's menu shows a state for each session, which the README splits into Waiting, Busy and Idle. That is the whole pitch. It is not an agent, not a wrapper around the model API, and not a way to make agents smarter. It is a control surface over processes you already run.

The multi-project feature extends this past a single repository. The README lists "Multi-project support: Manage multiple git repositories from a single interface," so the menu is not scoped to one checkout. For anyone juggling a work repo and a side project in the same afternoon, that removes a terminal-tab shuffle.

How ccmanager tracks sessions and worktrees

The repository is a TypeScript project built with Bun. package.json declares `"bin": { "ccmanager": "bin/cli.js" }`, so the published entry point is a launcher that resolves a platform binary. The optionalDependencies block lists five platform packages: `@kodaikabasawa/ccmanager-darwin-arm64`, `darwin-x64`, `linux-arm64`, `linux-x64` and `win32-x64`, all pinned to 4.4.3. That is the architecture in one line: npm installs a thin JS shim, and the shim pulls a prebuilt native binary for your platform.

Session state is not read from the agent's API. The README says each assistant "has its own state detection strategy to properly track" Idle, Busy and Waiting, and points to `docs/gemini-support.md` for Gemini-specific configuration. The README does not document what those strategies parse. Given that the supported tools are terminal programs, the plausible mechanism is terminal output inspection, but the README does not state this, so treat it as unconfirmed. The practical consequence is that detection is per-assistant and configurable, which implies it can be wrong when an assistant changes its output format.

Worktrees are managed inside the app. The feature list includes "Create, merge, and delete worktrees from within the app," and a `.worktreeinclude` file carries gitignored project files such as `.env` and local certificates into newly created worktrees. That last detail matters more than it looks: a fresh worktree is a clean checkout, so any untracked secret your agent needs is missing unless you list it. Configuration lives in `~/.config/ccmanager/config.json` globally, with `.ccmanager.json` in a repository root overriding it.

Installing ccmanager and starting a first session

The README gives a single global install command. It requires Node and npm; the package's optionalDependencies resolve the correct native binary for darwin, linux or win32 at install time.

npm install -g ccmanager

If you would rather not install globally, the README offers a one-shot run through npx. The first invocation downloads the package and its platform binary.

npx ccmanager

Launching with no arguments opens the TUI. From the main menu you select a project, create or pick a worktree, and start a session. The default assistant command is `claude`, and the README's supported-assistants table lists the command name for each alternative: `gemini`, `codex`, `cursor-agent`, `copilot`, `cline`, `opencode`, `kimi` and `mcode`. You should see a menu listing sessions with a state label next to each.

Keyboard handling is worth knowing before you start. Ctrl+E returns to the menu from an active session, and Escape cancels or goes back in dialogs. Both are configurable in `~/.config/ccmanager/config.json`:

{
  "shortcuts": {
    "returnToMenu": {
      "ctrl": true,
      "key": "r"
    },
    "cancel": {
      "key": "escape"
    }
  }
}

The README states that shortcuts must use a modifier key except for special keys like Escape, and that Ctrl+C, Ctrl+D and Ctrl+[ are reserved and cannot be reassigned. A legacy `shortcuts.json` is migrated into `config.json` on first use.

Where ccmanager gets in the way

The tmux-free design is the selling point, and it is also the constraint. Claude Squad, which the README names directly, builds on tmux, so its sessions are ordinary tmux panes you can attach to from any terminal, script, or remote SSH session. ccmanager is a self-contained TUI, which means the session view exists only inside ccmanager. The README does not document a way to attach to a running session from outside the app, and it does not document rollback or undo for worktree merge and delete operations. If you delete a worktree with uncommitted agent work in it, the README gives no recovery path.

The state detection is the second soft spot. Because each assistant has a separate strategy, a tool update that changes prompt text or spinner output can flip a session from Waiting to Idle or leave it stuck. The README describes the strategies as configurable but does not publish the detection rules, so debugging a misreported state means reading source. For a tool whose entire value proposition is knowing which session needs you, that is a real exposure.

Finally, the Auto Approval feature is flagged experimental in the README itself. It "automatically approve[s] safe prompts using AI verification." The README's own comparison section criticizes Claude Squad's AutoYes for bypassing Claude Code's security confirmations. An AI verifier deciding which prompts are safe is a different mechanism, but it lands in the same territory, and the experimental label is the project's own.

Claude Squad, Agentree and the alternatives worth comparing

The README devotes a section to Claude Squad and is unusually direct about it: "If you love tmux-based workflows, stick with Claude Squad!" The difference is architectural rather than feature-level. Claude Squad delegates session persistence, pane management and attach/detach to tmux, which is a decades-old, well understood process model. ccmanager reimplements the multiplexing inside a Node process and presents its own menu. You get no tmux install step and no interference with an existing tmux config; you give up tmux's scripting surface and remote attach.

Agentree and Nimbalyst appear in the search data alongside ccmanager, and both are worktree-oriented tools in the same space, but the README does not describe their internals, so a mechanism-level comparison is not possible from what is documented. The honest framing is that ccmanager's distinguishing choice is the bundled TUI plus multi-assistant state detection, and the cost of that choice is a session model you cannot reach from outside the app.

On assistant coverage, ccmanager is broader than a Claude-only tool. The supported table spans Claude Code, Gemini CLI, Codex CLI, Cursor Agent, Copilot CLI, Cline CLI, OpenCode, Kimi CLI and MiniMax Code. If your team mixes assistants, that breadth is the reason to pick it over a single-vendor manager.

Configuration, the plugin skill and upgrade cost

Configuration is layered: `~/.config/ccmanager/config.json` for global settings and `.ccmanager.json` at a repository root for per-project settings, with project values taking priority. The README also describes command presets with fallback arguments, so a primary invocation that fails can retry with different arguments and finally with none.

The repository doubles as a plugin marketplace. It ships a `ccmanager-config` skill that teaches Claude Code or Codex the configuration schema and includes a validator. The README gives these commands:

# 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

Upgrade cost is low on paper. The package is MIT licensed, published to npm, and the optionalDependencies pin platform binaries to the same version as the parent package, so a normal `npm install -g ccmanager` moves everything together. The maintenance signal is current: the last push was on 2026-09-13, and v4.4.3 was released the same day, following v4.4.2 on 2026-09-09. The licence permits commercial use and modification; it does not cover the AI assistants ccmanager launches, each of which carries its own terms, and nothing here is legal advice.

One upgrade caveat: because the app shells out to external CLIs, a ccmanager upgrade and an assistant CLI upgrade are independent events. A change in either can affect state detection without the other changing.

Editorial conclusion

Adopt ccmanager if you already run several Claude Code or Gemini CLI sessions and want worktree creation, session state and restart recovery in one terminal UI without a tmux layer. Skip it if your workflow is already built around tmux panes, or if you need the tool to manage non-Git directories, since the README ties worktree handling to Git repositories. Before committing, verify first that your chosen assistant's state detection behaves as you expect: run ccmanager against one repository, start a session, and confirm the menu shows Waiting, Busy and Idle at the right moments, because the README describes per-assistant detection strategies without documenting how each one is implemented.

Frequently asked questions

Official sources

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