CC Branch restores the working environment around a project: agents, terminals, editors, local folders, SSH machines, and reusable sessions.
- A project may need Codex, Claude Code, dev servers, logs, editors, and multiple tmux windows.
- CC Branch lets you configure that workbench once, then bring it back with one command.
- Agent and tmux sessions may already be running from the last time you worked on the project.
- CC Branch attaches back to those sessions, so returning to a project feels like continuing work instead of starting over.
- A project may span a local repo, SSH machine, GPU box, remote tmux session, and local editor.
- CC Branch keeps local and remote work in one workspace, so returning to the project means continuing instead of rebuilding.
Download the desktop app from the latest GitHub Release.
Use this when you want the native desktop experience.
Install the CLI/backend and packaged browser Web UI:
pip install cc-branchThe pip package does not install the desktop app. Use GitHub Releases for the native desktop build.
Use the source install when you want to develop or inspect the repo locally:
git clone https://github.com/GeminiLight/cc-branch.git
cd cc-branch
pip install .Source checkouts do not build the Web UI automatically. Run python scripts/build-webui.py before cc-branch serve when developing the browser UI.
cc-branch is also available as ccb.
Start the browser Web UI:
cc-branch service startIt runs at http://127.0.0.1:8080 by default.
Create and restore a workspace from a project:
cd /path/to/project
cc-branch init
cc-branch plan
cc-branch start| Command | What it is for |
|---|---|
cc-branch service start |
Start the local Web UI service in the background |
cc-branch serve |
Run the Web UI server in the foreground |
cc-branch init |
Create a starter .cc-branch/config.yaml |
cc-branch plan |
Show the agents, commands, panes, openers, and SSH targets before launch |
cc-branch start |
Start missing targets or reconnect reusable tmux-backed sessions |
cc-branch attach [tab[:pane]] |
Jump into a running tab, pane, or tmux target |
cc-branch send <tab[:pane]> <message> |
Send a message into a running tmux-managed agent pane |
cc-branch open --opener <tool> |
Open the project with VS Code, Cursor, Warp, terminal, Web UI, or desktop |
cc-branch status |
Show runtime status |
cc-branch sync |
Apply config changes to running tmux targets |
cc-branch doctor --fix |
Diagnose and repair low-risk environment, config, or state issues |
cc-branch session list |
List known agent session metadata |
cc-branch session restore |
Scan local agent transcripts and bind resumable sessions back to panes |
cc-branch session hook |
Let agent-native hooks write session IDs and transcript paths back to local state |
cc-branch snapshot create |
Save the current workspace runtime state for later restore |
cc-branch worktree setup <tab[:pane]> |
Create an optional git worktree and branch for one agent |
version: 2
project: my-app
root: .
openWith: cursor
layoutBackend: tmux
tabs:
- name: agents
panes:
- name: planner
agent: codex
- name: review
agent: claude
- name: remote-lab
remote:
host: gpu-dev
cwd: /srv/my-app
panes:
- name: qa
command: npm run qaBuilt-in agent profiles are available automatically. Add an agents section only when you need to override a built-in profile or define a custom local tool.
- Getting Started
- User Guide
- Feature Reference
- SSH Remote Workspaces
- Install Troubleshooting
- Publishing Runbook
This project has been published on the LINUX DO community, and we deeply appreciate the community's support and feedback.
MIT License. See LICENSE for details.