cc-branch 1.0.0__tar.gz

cc_branch-1.0.0/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-06-01
+
+### Added
+- First public baseline for CC Branch.
+- CLI, Web UI, and desktop shell for restoring multi-agent terminal workspaces.
+- App-scoped Web UI service commands: `cc-branch service start`, `status`, `stop`, `restart`, and `logs`.
+- Project-level foreground Web UI command: `cc-branch serve`.
+- Config editor and dashboard support for enabling or disabling individual windows.
+- Tmux and direct-layout workspace execution, SSH targets, opener integrations, diagnostics, and local project index.
+- Desktop release packaging with bundled backend sidecar and GitHub release verification.
+
+[1.0.0]: https://github.com/GeminiLight/cc-branch/releases/tag/v1.0.0

cc_branch-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,76 @@
+# Contributing to CC Branch
+
+Thanks for contributing to CC Branch.
+
+The canonical contributor guide lives in [`docs/contributing.md`](docs/contributing.md). Keep that file as the source of truth for architecture boundaries, test commands, and documentation expectations.
+
+## Quick Setup
+
+Requirements:
+
+- Python 3.10+
+- Node.js/npm for Web UI work
+- `tmux` when testing `layoutBackend: tmux`
+- Git
+
+Install locally:
+
+```bash
+pip install -e .
+```
+
+Editable installs do not build Web UI assets. Build them when you need to test `cc-branch serve`:
+
+```bash
+python scripts/build-webui.py
+```
+
+## Quality Checks
+
+Run the relevant checks before opening a pull request:
+
+```bash
+python -m unittest discover tests
+python -m ruff check .
+python -m mypy cc_branch
+npm --prefix apps/web run lint
+npm --prefix apps/web test -- --run
+npm --prefix apps/web run build
+```
+
+For package validation:
+
+```bash
+python -m build --sdist --wheel
+python -m twine check dist/*
+```
+
+## Pull Requests
+
+- Keep each PR focused.
+- Add or update tests for behavior changes.
+- Update user-facing docs when behavior changes.
+- Use clear commit messages that describe the real change.
+- Include rollout or release notes when touching packaging, desktop, or publishing behavior.
+
+## Documentation
+
+When behavior changes, keep these files aligned as needed:
+
+- [`README.md`](README.md)
+- [`README.zh.md`](README.zh.md)
+- [`docs/README.md`](docs/README.md)
+- [`docs/getting-started.md`](docs/getting-started.md)
+- [`docs/quickstart.md`](docs/quickstart.md)
+- [`docs/user-guide.md`](docs/user-guide.md)
+- [`docs/features.md`](docs/features.md)
+- [`docs/architecture.md`](docs/architecture.md)
+- [`docs/webui-spec.md`](docs/webui-spec.md)
+
+## Security
+
+Report security issues through the process in [`SECURITY.md`](SECURITY.md).
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

cc_branch-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 GeminiLight
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cc_branch-1.0.0/MANIFEST.in

@@ -0,0 +1,17 @@
+# Include important files
+include LICENSE
+include README.md
+include README.zh.md
+include CHANGELOG.md
+include CONTRIBUTING.md
+include pyproject.toml
+include cc_branch/agents.yaml
+recursive-include cc_branch/webui/static *
+prune cc_branch/webui/static/__pycache__
+
+# Include examples and docs
+recursive-include examples *.yaml
+recursive-include docs *.md
+recursive-include packaging *.md *.template *.py
+global-exclude *.py[cod]
+global-exclude __pycache__

cc_branch-1.0.0/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: cc-branch
+Version: 1.0.0
+Summary: Multi-agent workspace orchestrator for shell and tmux runtimes
+Author-email: GeminiLight <wtfly2018@gmail.com>
+Maintainer-email: GeminiLight <wtfly2018@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/GeminiLight/cc-branch
+Project-URL: Documentation, https://github.com/GeminiLight/cc-branch/blob/main/docs
+Project-URL: Repository, https://github.com/GeminiLight/cc-branch
+Project-URL: Issues, https://github.com/GeminiLight/cc-branch/issues
+Project-URL: Changelog, https://github.com/GeminiLight/cc-branch/blob/main/CHANGELOG.md
+Keywords: tmux,cli,agents,orchestrator,ai,workspace,automation
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: System :: Shells
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Environment :: Console
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: Microsoft :: Windows
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: rich>=13.0.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.18.0; extra == "dev"
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: types-PyYAML>=6.0.12; extra == "dev"
+Provides-Extra: desktop
+Requires-Dist: pyinstaller>=6.0.0; extra == "desktop"
+Dynamic: license-file
+
+<div align="center">
+
+# CC Branch
+
+### Restore your multi-agent CLI workbench in one command
+
+English | [中文](README.zh.md)
+
+[![CI](https://github.com/GeminiLight/cc-branch/actions/workflows/ci.yml/badge.svg)](https://github.com/GeminiLight/cc-branch/actions/workflows/ci.yml)
+![Python](https://img.shields.io/badge/python-3.10%2B-blue)
+![Status](https://img.shields.io/badge/status-v1.0.0-green)
+![License](https://img.shields.io/badge/license-MIT-green)
+
+</div>
+
+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](https://github.com/GeminiLight/cc-branch/releases/latest).
+
+Use this when you want the native desktop experience.
+
+### CLI and Web UI with pip
+
+Install the CLI/backend and packaged browser Web UI:
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+cc-branch service start
+```
+
+It runs at `http://127.0.0.1:8080` by default.
+
+Create and restore a workspace from a project:
+
+```bash
+cd /path/to/project
+cc-branch init
+cc-branch plan
+cc-branch start
+```
+
+## Daily Commands
+
+| 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 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 |
+
+## Example Config
+
+```yaml
+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
+    ssh:
+      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](docs/getting-started.md)
+- [User Guide](docs/user-guide.md)
+- [Feature Reference](docs/features.md)
+- [SSH Remote Workspaces](docs/ssh-remote-workspaces.md)
+- [Install Troubleshooting](docs/install-troubleshooting.md)
+- [Publishing Runbook](docs/publishing.md)
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

cc_branch-1.0.0/README.md

@@ -0,0 +1,140 @@
+<div align="center">
+
+# CC Branch
+
+### Restore your multi-agent CLI workbench in one command
+
+English | [中文](README.zh.md)
+
+[![CI](https://github.com/GeminiLight/cc-branch/actions/workflows/ci.yml/badge.svg)](https://github.com/GeminiLight/cc-branch/actions/workflows/ci.yml)
+![Python](https://img.shields.io/badge/python-3.10%2B-blue)
+![Status](https://img.shields.io/badge/status-v1.0.0-green)
+![License](https://img.shields.io/badge/license-MIT-green)
+
+</div>
+
+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](https://github.com/GeminiLight/cc-branch/releases/latest).
+
+Use this when you want the native desktop experience.
+
+### CLI and Web UI with pip
+
+Install the CLI/backend and packaged browser Web UI:
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+cc-branch service start
+```
+
+It runs at `http://127.0.0.1:8080` by default.
+
+Create and restore a workspace from a project:
+
+```bash
+cd /path/to/project
+cc-branch init
+cc-branch plan
+cc-branch start
+```
+
+## Daily Commands
+
+| 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 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 |
+
+## Example Config
+
+```yaml
+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
+    ssh:
+      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](docs/getting-started.md)
+- [User Guide](docs/user-guide.md)
+- [Feature Reference](docs/features.md)
+- [SSH Remote Workspaces](docs/ssh-remote-workspaces.md)
+- [Install Troubleshooting](docs/install-troubleshooting.md)
+- [Publishing Runbook](docs/publishing.md)
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

cc_branch-1.0.0/README.zh.md

@@ -0,0 +1,140 @@
+<div align="center">
+
+# CC Branch
+
+### 一键恢复多 Agent CLI 工作台
+
+[English](README.md) | 中文
+
+[![CI](https://github.com/GeminiLight/cc-branch/actions/workflows/ci.yml/badge.svg)](https://github.com/GeminiLight/cc-branch/actions/workflows/ci.yml)
+![Python](https://img.shields.io/badge/python-3.10%2B-blue)
+![Status](https://img.shields.io/badge/status-v1.0.0-green)
+![License](https://img.shields.io/badge/license-MIT-green)
+
+</div>
+
+CC Branch 恢复一个项目周围的工作环境：Agent、终端、编辑器、本机目录、SSH 机器和可复用会话。
+
+## 为什么用它
+
+### 1. 恢复完整的项目工作台
+
+- 一个项目可能同时需要 Codex、Claude Code、dev server、日志、编辑器和多个 tmux 窗口。
+- CC Branch 让这套工作台只配置一次，之后一条命令就能恢复。
+
+### 2. 回到已有会话继续
+
+- 上次开的 Agent 会话和 tmux 会话，很多时候其实还在继续运行。
+- CC Branch 可以直接接回这些会话，回到项目就是继续工作，而不是重新开始。
+
+### 3. 同时处理本机和 SSH 机器
+
+- 一个项目可能横跨本机仓库、SSH 机器、GPU 机器、远程 tmux 会话和本机编辑器。
+- CC Branch 把本机和远程工作放进同一个 workspace，回到项目就是继续，而不是重新搭环境。
+
+## 安装
+
+### 桌面端
+
+从 [最新 GitHub Release](https://github.com/GeminiLight/cc-branch/releases/latest) 下载桌面端。
+
+需要原生桌面体验时，使用桌面端。
+
+### 用 pip 安装 CLI 和 Web UI
+
+安装 CLI/backend 和打包好的浏览器 Web UI：
+
+```bash
+pip install cc-branch
+```
+
+pip 包不会安装桌面端。需要原生桌面 App 时，从 GitHub Releases 下载。
+
+### 从源码安装
+
+需要本地开发或查看源码时，可以从仓库安装：
+
+```bash
+git clone https://github.com/GeminiLight/cc-branch.git
+cd cc-branch
+pip install .
+```
+
+源码 checkout 不会自动构建 Web UI。开发浏览器 UI 时，先运行 `python scripts/build-webui.py` 再使用 `cc-branch serve`。
+
+`cc-branch` 也可以简写为 `ccb`。
+
+## 快速使用
+
+启动浏览器 Web UI：
+
+```bash
+cc-branch service start
+```
+
+默认运行在 `http://127.0.0.1:8080`。
+
+在项目里创建并恢复 workspace：
+
+```bash
+cd /path/to/project
+cc-branch init
+cc-branch plan
+cc-branch start
+```
+
+## 日常命令
+
+| 命令 | 用途 |
+| --- | --- |
+| `cc-branch service start` | 后台启动本地 Web UI service |
+| `cc-branch serve` | 前台运行 Web UI server |
+| `cc-branch init` | 创建 starter `.cc-branch/config.yaml` |
+| `cc-branch plan` | 启动前展示 Agent、命令、窗格、打开方式和 SSH 目标 |
+| `cc-branch start` | 启动缺失目标，或接回可复用的 tmux 会话 |
+| `cc-branch attach [tab[:pane]]` | 进入正在运行的 tab、pane 或 tmux target |
+| `cc-branch open --opener <tool>` | 用 VS Code、Cursor、Warp、terminal、Web UI 或桌面端打开项目 |
+| `cc-branch status` | 查看 runtime 状态 |
+| `cc-branch sync` | 把配置变更同步到正在运行的 tmux targets |
+| `cc-branch doctor --fix` | 诊断并修复低风险环境、配置或状态问题 |
+| `cc-branch session list` | 列出已知 agent session metadata |
+
+## 配置示例
+
+```yaml
+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
+    ssh:
+      host: gpu-dev
+      cwd: /srv/my-app
+    panes:
+      - name: qa
+        command: npm run qa
+```
+
+内置 agent profiles 会自动可用。只有在需要覆盖内置 profile 或定义自定义本地工具时，才需要添加 `agents` 配置。
+
+## 文档
+
+- [Getting Started](docs/getting-started.md)
+- [User Guide](docs/user-guide.md)
+- [Feature Reference](docs/features.md)
+- [SSH Remote Workspaces](docs/ssh-remote-workspaces.md)
+- [Install Troubleshooting](docs/install-troubleshooting.md)
+- [Publishing Runbook](docs/publishing.md)
+
+## 许可证
+
+本项目采用 MIT 许可证。详情见 [LICENSE](LICENSE)。

cc_branch-1.0.0/cc_branch/__init__.py

@@ -0,0 +1,76 @@
+"""cc-branch — Multi-agent workspace orchestrator."""
+
+from __future__ import annotations
+
+from .adapters import AgentAdapter, get_adapter
+from .backends import Backend, TmuxBackend, get_backend, set_backend
+from .config import init_workspace, load_workspace
+from .context import WorkspaceContext
+from .exceptions import (
+    CcbError,
+    ConfigError,
+    RuntimeError,
+    SlotNotFoundError,
+    StateError,
+    WindowNotFoundError,
+    WorkspaceError,
+)
+from .models import (
+    AgentSpec,
+    DisplayConfig,
+    DoctorReport,
+    Issue,
+    SlotConfig,
+    SlotPlan,
+    WindowConfig,
+    WindowPlan,
+    WorkspaceConfig,
+    WorkspacePlan,
+    WorkspaceState,
+)
+from .planner import plan_workspace
+from .repository import StateRepository
+from .sessions import inspect_session, list_sessions, prune_sessions, restore_session
+from .state import load_state, merge_state, save_state
+
+__version__ = "1.0.0"
+
+
+def main(argv: list[str] | None = None) -> int:
+    from .cli import main as cli_main
+
+    return cli_main(argv)
+
+
+__all__ = [
+    "init_workspace",
+    "__version__",
+    "load_state",
+    "load_workspace",
+    "main",
+    "merge_state",
+    "plan_workspace",
+    "save_state",
+    "AgentAdapter",
+    "AgentSpec",
+    "DisplayConfig",
+    "DoctorReport",
+    "get_adapter",
+    "get_backend",
+    "inspect_session",
+    "Issue",
+    "list_sessions",
+    "prune_sessions",
+    "restore_session",
+    "set_backend",
+    "SlotConfig",
+    "SlotPlan",
+    "WindowConfig",
+    "WindowPlan",
+    "WorkspaceConfig",
+    "WorkspaceContext",
+    "WorkspacePlan",
+    "WorkspaceState",
+    "StateRepository",
+    "TmuxBackend",
+]

cc_branch-1.0.0/cc_branch/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())