CC Branch restores the working environment around a project: agents, terminals, editors, local folders, SSH machines, and reusable sessions.

Why Developers Use It

1. Restore the full project workbench

• 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.

2. Continue from existing sessions

• 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.

3. Work across local and SSH machines

• 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.

Install

Desktop app

Download the desktop app from the latest GitHub Release.

Use this when you want the native desktop experience.

CLI and Web UI with pip

Install the CLI/backend and packaged browser Web UI:

pip install cc-branch

The pip package does not install the desktop app. Use GitHub Releases for the native desktop build.

From source

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.

Quick Use

Start the browser Web UI:

cc-branch service start

It 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

Daily Commands

Example Config

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 qa

Built-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.

Documentation

• Getting Started
• User Guide
• Feature Reference
• SSH Remote Workspaces
• Install Troubleshooting
• Publishing Runbook

🙏 Acknowledgements

This project has been published on the LINUX DO community, and we deeply appreciate the community's support and feedback.

License

MIT License. See LICENSE for details.