Skip to content

user-guide.md

Latest commit

 

History

History
667 lines (468 loc) · 21.7 KB

user-guide.md

File metadata and controls

667 lines (468 loc) · 21.7 KB
Raw

CC Branch 使用指南

这份文档面向已经准备开始使用 CC Branch 的用户。它重点解释怎么初始化、怎么配置、怎么日常操作，以及出了问题时先看哪里。

安装与环境

环境要求

  • 你会在配置里实际使用到的命令行工具
  • 从源码安装当前 CLI 时需要 Python 3.10 或更高版本
  • 只有使用 layoutBackend: tmux 时才需要 tmux

没有 tmux 时，可以使用默认的 layoutBackend: direct。这些窗格会作为外部终端或编辑器进程打开，不具备 tmux 的复用、后台生命周期或 tmux 级 attach。

安装

从 PyPI 安装 CLI/backend 和打包好的浏览器 Web UI：

pip install cc-branch

需要源码开发时：

git clone https://github.com/GeminiLight/cc-branch.git
cd cc-branch
pip install .

源码 checkout 不会自动构建 Web UI。需要从源码运行 Web UI 时，在 checkout 里先执行 python scripts/build-webui.py。需要原生桌面体验时，从 GitHub Releases 下载桌面端。

验证

cc-branch --help
ccb --help

初始化项目

推荐方式

cc-branch init

这一步通常会完成下面几件事：

  • 检查可选的 tmux
  • 探测常见命令行工具
  • 按模板生成起步配置
  • 创建 .cc-branch/state.yaml
  • 在需要时补齐 session_id
  • 更新 .gitignore

development 是默认模板；检测到可用 Agent CLI 时，session metadata 会自动初始化。研究工作可以用 --profile research，只需要一个窗格时可以用 --profile minimal。

最简方式

cc-branch init --minimal

如果你已经知道自己要写什么配置，只想先拿到基础文件，可以用这个模式。

可选模板

cc-branch init --profile research
cc-branch init --profile minimal

配置文件和状态文件

配置文件

CC Branch 只自动读取 .cc-branch/config.yaml。首次发版不保留旧格式兼容。

两个关键文件

  • .cc-branch/config.yaml：项目配置，适合提交到仓库
  • .cc-branch/state.yaml：本地运行状态，通常不建议提交

状态文件里常见的信息包括：

  • session_id
  • label
  • agent
  • tab
  • pane

配置怎么写

顶层结构

version: 2
project: "my-project"
root: "."

display:
  mode: "grid"
  columns: 2
  rows: 2
  dashboard: true

tabs: []

display

  • mode：总览面板的布局方式
  • columns / rows：grid 模式下的列数和行数；Web UI 会以 n x m 形式显示，Warp opener 会把这个尺寸写进 Launch Configuration
  • dashboard：旧配置字段；当前需要显式运行 dashboard 或 start --dashboard 进入总览面板

agents

agents 是可选的 agent profile 覆盖区，不是每个项目都必须维护的基础配置。

内置 agent profile 默认可用：claude、codex、gemini、cursor、kimi。也就是说，普通项目可以直接在 pane 里写：

tabs:
  - name: "coding"
    panes:
      - name: "planner"
        agent: "codex"

只有在需要覆盖默认启动方式，或添加自定义 agent 时，才需要写 agents。

有效 agent profile 的合并顺序是：

  1. 内置 cc_branch/agents.yaml
  2. 用户全局 ~/.cc-branch/agents.yaml
  3. 工作区 .cc-branch/agents.yaml
  4. 当前 .cc-branch/config.yaml 里的 agents

后面的层级覆盖前面的层级，并且是字段级覆盖。例如只改 command 时，默认的 resume_template、label_template 仍然保留：

agents:
  codex:
    command: "codex --sandbox read-only"

每个 agent 可以声明这些字段：

  • command
  • resume_mode
  • resume_template
  • create_mode
  • create_template
  • label_template
  • label_mode
  • rename_template

如需添加自定义 agent，创建 ~/.cc-branch/agents.yaml：

agents:
  my-agent:
    command: my-agent
    resume_mode: flag
    resume_template: "--restore {session_id}"

可用模板变量：{session_id}、{project}、{tab}、{pane}、{label}。

resume_mode 说明：

  • flag — 启动时附加 flag（如 codex resume <id>）
  • internal — 启动后发送 post-launch 命令恢复
  • none — 不处理恢复，直接运行命令

tabs

每个 tab 是工作区里的一个顶层上下文。layoutBackend 决定它由普通本地进程承载，还是由 tmux 承载。

常见字段有：

  • name
  • layoutBackend
  • opener
  • cwd
  • env
  • remote
  • panes
  • command
  • title
  • agent
  • session
  • label

panes

窗格层常见字段有：

  • name
  • agent
  • command
  • cwd
  • env
  • remote
  • session
  • label
  • label_template
  • resume_mode
  • resume_template
  • create_mode
  • create_template
  • label_mode
  • rename_template

计划和运行时规则

direct 布局会被归一化

tabs:
  - name: "scratch"
    layoutBackend: "direct"
    panes:
      - name: "scratch"
        command: "zsh"

这类写法会通过本机终端或编辑器 opener 打开。它不会创建 tmux 会话，也不会被 stop 当作可持久化的 tmux 目标。

路径如何解析

  • tab 的 cwd 相对于 root
  • pane 的 cwd 相对于 tab 的 cwd
  • 绝对路径会保持不变

环境变量如何合并

  • tab 的 env 和 pane 的 env 会合并
  • pane 同名字段会覆盖 tab
  • 最终会注入到实际启动命令前

SSH 远程执行

remote 可以写在 tab、pane 或嵌套 tmux window 上。tab 级 remote 会向下继承，pane/window 可以覆盖其中一部分字段。

tabs:
  - name: "gpu"
    layoutBackend: "tmux"
    remote:
      host: "gpu-dev"
      user: "ubuntu"
      cwd: "/srv/app"
      args:
        - "-A"
    panes:
      - name: "train"
        command: "uv run python train.py"
      - name: "logs"
        remote:
          cwd: "/var/log/app"
        command: "tail -f app.log"

上面的 train 会在 ubuntu@gpu-dev:/srv/app 执行，logs 会继承同一个主机但切到 /var/log/app。CC Branch 只负责把命令包装成 ssh；认证、密钥、跳板机和 agent forwarding 交给本机 SSH 配置处理。Web/Desktop 的添加 SSH 项目流程可以选择 SSH config、密钥文件或密码提示；密码不会写入项目索引。远程文件同步不在这个功能范围内。

如果某个 pane 位于远程 tab 下面，但需要强制在本机运行，可以写 remote: false。

创建和恢复如何处理

CC Branch 会根据配置和本地状态，生成最终 launch_command 与 post_launch_commands。

Agent 会话只需要一个字段：

session: auto   # 默认，可省略；已有绑定就恢复，没有就启动新会话并尽量记住
session: fresh  # 每次启动都开新会话，不复用 state
session: "..."  # 显式恢复这个真实 session id

真实的运行时会话 ID 保存在 .cc-branch/state.yaml，不需要写进项目配置。对于 Codex、Claude、Gemini、Cursor、Kimi 等可扫描本地会话的 Agent，session: auto 启动后会尝试把新创建的 session 绑定回 state；如果暂时识别不到，状态会显示为等待识别，后续仍可手动选择历史会话。

Agent hook 回写

Agent pane 启动时，CC Branch 会自动注入一组环境变量，方便 Codex、Claude 等工具自己的 hook 脚本把真实 session 信息写回 .cc-branch/state.yaml：

  • CC_BRANCH_SESSION_TARGET，例如 dev:planner
  • CC_BRANCH_SESSION_KEY，例如 dev.planner
  • CC_BRANCH_AGENT，例如 codex
  • CC_BRANCH_PROJECT
  • CC_BRANCH_PROJECT_DIR

Agent hook 拿到真实 session id 或 transcript 路径后，可以调用：

cc-branch --project "$CC_BRANCH_PROJECT_DIR" session hook "$CC_BRANCH_SESSION_TARGET" \
  --event started \
  --agent "$CC_BRANCH_AGENT" \
  --session-id "$AGENT_SESSION_ID" \
  --transcript "$AGENT_TRANSCRIPT_PATH"

退出时可以继续记录生命周期：

cc-branch --project "$CC_BRANCH_PROJECT_DIR" session hook "$CC_BRANCH_SESSION_TARGET" \
  --event exited \
  --agent "$CC_BRANCH_AGENT" \
  --exit-code "$EXIT_CODE"

支持的事件包括 started、updated、exited 和 error。只要 hook 写回了 session_id，下一次 cc-branch plan、open、start 或 GUI 状态刷新都会把这个 pane 当作已绑定会话处理，并优先生成恢复命令。没有 hook 时，CC Branch 仍会保留原来的本地会话扫描和手动选择能力。

常见模式包括：

  • resume_mode = flag
  • resume_mode = internal
  • create_mode = generated_uuid

常用命令

plan

cc-branch plan [--write-state] [--json]

适合在正式启动前先确认：

  • 命令是否正确
  • 目录是否正确
  • agent session 是自动、每次新建，还是显式恢复
  • label 和附加命令是否符合预期

start

cc-branch start [--prepare] [--detach] [--dashboard]

它会按配置创建可复用 tmux 会话或直接启动本地命令，并默认进入第一个可 attach 的标签页。--detach 只创建 tmux session，不会 attach，也不会打开 direct 布局的外部进程。

需要总览面板时，使用 cc-branch dashboard 或 cc-branch start --dashboard。start 不会因为 display.dashboard 配置而静默切换到面板。

open

cc-branch open [tab[:pane]] [--opener auto-terminal|warp|vscode|cursor]
cc-branch open --project-dir [--opener auto-terminal|warp|vscode|cursor]

它是“打开可见工作空间”的统一入口。open 会按 opener 适配 Terminal、Warp、VS Code、Cursor；打开 tmux 标签页时会先确保 tmux session 存在，打开 direct 布局窗格时会启动外部终端或编辑器进程。--project-dir 不会 attach workspace：终端类工具会在项目目录打开一个交互 shell，编辑器类工具会打开项目文件夹。

status

cc-branch status [--write-state] [--json]

常见输出包括：

  • tab 是否在运行
  • pane 是否存在
  • 当前 session_id
  • 当前 label
  • agent 名称
  • 顶层 agents 状态中心数据，包括 Agent 位置、session、transcript、最近活动、inbox 和可用操作

send

cc-branch send dev:planner "看一下 reviewer 的输出，整理最关键的风险。"

send 会把消息发送到正在运行的 tmux 托管 pane。它适合在不切换终端的情况下调度某个 Agent。当前版本不向 direct 布局的外部进程发送消息。

发送记录会写入本机 Agent Bus 事件日志，Web UI 的 Agent 状态中心会显示每个 Agent 的 inbox 未读数和最近消息。标为已读时，CC Branch 会追加一条 read receipt；原始消息事件仍保留在本地日志里。

snapshot

cc-branch snapshot create --name before-refactor
cc-branch snapshot create --name before-refactor --include-files
cc-branch snapshot list
cc-branch snapshot show <id-or-name>
cc-branch snapshot preview <id-or-name>
cc-branch snapshot restore <id-or-name> --dry-run
cc-branch snapshot restore <id-or-name>
cc-branch snapshot restore <id-or-name> --state-only
cc-branch snapshot export <id-or-name> --output snapshot.json
cc-branch snapshot import snapshot.json --name restored-copy

Snapshot 会保存当前 workspace 的配置引用、state、tabs/panes 运行状态、Agent session 绑定、SSH target、tmux session、最近状态和 git branch/worktree 信息。保存位置是本机 ~/.cc-branch/app/snapshots.json，不会默认提交到项目 git。

加 --include-files 时，snapshot 还会保存工作区文件内容。恢复这种 snapshot 会把被修改的文件写回、把被删除的文件恢复、把快照之后新增的文件删除；--state-only 可只恢复运行态，不碰文件。文件捕获会跳过 .git、.cc-branch/app、node_modules、dist、build、虚拟环境和缓存目录，默认单文件 2MB、总量 50MB，适合本机短期回滚，不替代 git、系统备份或远程同步。

preview 和 restore --dry-run 会对比当前 state 和 snapshot state，先显示 windows/slots/files 的新增、删除、改变和不变数量；真正 restore 才会写回 state.yaml 和可选文件内容。export/import 使用 JSON 文件，适合归档或把本地运行现场迁移到另一台机器。

worktree

cc-branch worktree setup dev:planner --branch cc-branch/dev-planner --copy .env
cc-branch worktree status
cc-branch worktree finish dev:planner
cc-branch worktree cleanup dev:planner

Worktree 是可选能力，用来给单个 Agent 分配独立 git worktree 和 branch。--copy 和 --symlink 可用于把 .env 这类 gitignored 文件带进 agent worktree；finish 只标记完成状态，cleanup 才会移除 worktree。Web UI 会在工作空间配置页检测这些 worktree，允许把某个 agent pane 的工作目录切到对应 worktree，并在工作空间画布和 Dashboard 中显示 branch、dirty/clean 和变更数量。

attach

cc-branch attach <tab>
cc-branch attach <tab>:<pane>

stop

cc-branch stop
cc-branch stop dev
cc-branch stop dev:planner

restart

cc-branch restart
cc-branch restart dev
cc-branch restart dev:planner --detach

dashboard

cc-branch dashboard [--prepare]

Dashboard 顶部显示 workspace 总览和打开工具；下面的每个 tab/pane 卡片同时展示布局状态和对应 Agent 的动态状态。Agent 正在运行、最近活动、未读消息、worktree 变更和发送消息入口会直接出现在对应 pane/window 内，避免在布局面板外再维护一份独立 Agent 状态列表。

doctor

cc-branch doctor [--write-state] [--fix]

常见检查包括：

  • tmux 是否存在
  • 配置里的命令是否存在
  • 远程 pane 所需的本机 ssh 是否存在
  • SSH 目标上的远程 cwd、tmux 和 pane/agent 命令是否存在
  • 是否有重复的 tmux 会话或窗口
  • agent 名称是否无效
  • 环境变量名是否非法
  • cwd 是否缺失
  • 启动命令是否缺失
  • 需要恢复时是否缺少 session_id

doctor --fix 当前会尝试处理：

  • 创建缺失目录
  • 为支持 generated_uuid 的窗口补写缺失的 session_id
  • 补充 .gitignore

sync

cc-branch sync [tab[:pane]] [--dry-run] [--yes] [--stop-removed]

修改 .cc-branch/config.yaml 后，已经运行的 tmux pane 不会自动换命令。sync --dry-run 会列出需要重启的 tmux target；确认后用 sync --yes 应用。

会话管理

列出会话

cc-branch session list

常见状态包括：

  • running
  • stopped
  • orphaned

查看单条记录

cc-branch session inspect dev:planner

清理孤立记录

cc-branch session prune --dry-run
cc-branch session prune

输出恢复命令

cc-branch session command dev:planner

这个命令会优先返回已经解析好的 launch_command。

扫描并恢复本地 session 绑定

cc-branch session restore
cc-branch session restore --dry-run
cc-branch session restore --target dev:planner --agent claude
cc-branch session restore --target dev:planner --session-id <id>
cc-branch session restore --target dev:planner --session-id <id> --session-scope all
cc-branch session restore --target dev:planner --force

这个命令会扫描本机 Agent transcript/session 文件，把匹配当前项目和 Agent 的 session 绑定回 .cc-branch/state.yaml。默认 --session-scope project，只看当前项目目录相关 session；--session-scope all 会扩大到本机全部已知 Codex、Claude、Gemini、Cursor、Kimi session，适合从其它项目或旧目录找回指定 session。--dry-run 会输出候选 session、计划绑定和跳过原因但不写 state；--target 可只恢复一个 pane；--agent 可限制 Agent 类型；--session-id 可绑定指定 agent-native session；--force 会替换已有绑定。它是 session hook 的兜底路径：hook 是快路径，restore 是本地扫描兜底。

管理桌面/Web UI 项目索引

cc-branch project list
cc-branch project add /path/to/project --name demo
cc-branch project add-remote --host gpu-dev --cwd /srv/app --agent claude --dry-run
cc-branch project add-remote --host gpu-dev --cwd /srv/app --user ubuntu --port 2222 --name remote-app

project 命令管理 ~/.cc-branch/app/projects.yaml，不要求当前目录已经初始化 workspace。add-remote --dry-run 会先检查 SSH 目标上的 cwd、tmux 和指定 Agent 命令，不写本地索引；真正添加后会在本机 app data 下创建一个 metadata workspace，命令仍在远程 cwd 执行。

记录 hook 事件

cc-branch session hook dev:planner --event started --agent codex --session-id <id>
cc-branch session hook dev:planner --event exited --agent codex --exit-code 0

这个入口主要给 agent-native hook 使用。它只更新本地 state，不会启动或停止 agent。

Web UI

启动

cc-branch service start
cc-branch service status
cc-branch service stop
cc-branch serve
cc-branch serve --host 127.0.0.1 --port 8080
cc-branch serve --host 0.0.0.0 --token "$CC_BRANCH_WEB_TOKEN"

service start 是默认推荐入口：它会在后台启动本机 app 级 Web UI，不要求终端一直开着，也不会在当前目录创建 .cc-branch/。项目配置只在用户显式添加项目、保存配置或运行 cc-branch init 时写入。serve 是前台调试入口，可以直接在没有 .cc-branch/config.yaml 的目录中启动；此时 Web UI 会显示 setup 流程，用户选择模板或保存 YAML 后才会写入配置文件。

如果配置了 token，第一次在浏览器打开时使用服务端打印的 /?token=... 链接。验证通过后，服务端会设置 HttpOnly cookie，后续访问根页面和所有 /api/* 请求都会使用这个 cookie。

现在可以做什么

  • 查看状态
  • 查看 Agent 状态中心，并向正在运行的 tmux 托管 Agent 发送消息
  • 查看和保存配置
  • 查看诊断结果
  • 查看可用模板
  • 初始化工作空间
  • 用同一个工具选择器打开工作空间或项目目录
  • 后台启动、重启、停止 tmux 工作空间或标签页

Web UI 中有一个工具选择器和两个主要动作：

  • “打开工作空间”会按所选工具适配：Terminal.app、iTerm2 等终端会运行 dashboard/attach 命令；Warp 会写入稳定的 Launch Configuration 并打开一个布局；VS Code、Cursor 会正常打开项目目录，并通过 .vscode/tasks.json 的 folder-open tasks 创建 integrated terminal 来运行对应命令。
  • “打开项目目录”固定使用系统文件管理器。它不会启动或 attach workspace，只是把项目目录作为普通文件夹打开。
  • Tab 或 pane 旁边的“打开”也使用同一个所选工具。Terminal/Warp 会直接运行 attach 或 direct-layout 命令；VS Code、Cursor 会正常打开项目目录，并通过同一个 task bridge 创建 integrated terminal 运行该目标命令。

layoutBackend: tmux 是可复用的；即使之前已经在另一个 Terminal 或 Warp 窗口打开过，再次打开也会 attach 到同一组 tmux session。layoutBackend: direct 是外部进程，不能被复用或停止；再次打开会启动新的终端进程，需要用户手动关闭窗口。

VS Code 和 Cursor 的 integrated terminal 自动打开不依赖 macOS Accessibility。CC Branch 会写入 .cc-branch/.generated/vscode-tasks.json，再通过 .vscode/tasks.json 桥接给编辑器；如果用户已有 tasks 文件，会尽量合并并保留原任务。如果 tasks 文件无法解析或无法更新，打开动作会返回明确错误。

Warp 通过 Launch Configuration 执行命令；当 opener 支持 layout 时，CC Branch 会把每个 tmux 标签页作为一个 attach 入口放进布局，标签页内部的多个 pane 由 tmux 自己管理和切换；direct 布局窗格会作为单独 pane 展开。如果想打开可见工作空间，使用“打开工作空间”或 cc-branch open。

额外说明

  • 前端资源会随包一起提供
  • 可以通过 project_path 切换目标项目
  • 可以通过 CC_BRANCH_CONFIG 和 CC_BRANCH_STATE 覆盖默认路径
  • 绑定到非本机地址时必须使用 --token 或 CC_BRANCH_WEB_TOKEN；token 模式会保护 Web UI 和所有 API

Python API

如果你要把 CC Branch 接进自己的工具，也可以直接使用这些接口：

from cc_branch import load_workspace, load_state, plan_workspace
from cc_branch import WorkspaceContext, WorkspaceConfig, WorkspacePlan, WorkspaceState

这样你可以直接复用配置装载、状态装载和计划生成逻辑，而不必自己重复实现一遍。

常见工作流

每天进入项目

cc-branch start

如果想在启动前确认会创建哪些 session/pane，可以先运行 cc-branch plan。

看看当前是否健康

cc-branch status
cc-branch session list
cc-branch doctor

清理旧记录

cc-branch session prune --dry-run
cc-branch session prune

用浏览器查看

cc-branch service start

如果你有多个项目，可以结合 project_path 切换不同目标。

如果当前目录还没有配置，Web UI 会进入初始化流程；不需要先在终端里运行 cc-branch init。

常见问题

tmux is required

说明当前操作需要 layoutBackend: tmux，但当前环境里没有找到 tmux。如果不需要 tmux 的复用、后台生命周期或 attach 能力，把对应 tab 改成 layoutBackend: direct 即可。

unknown tab / unknown pane

说明你传给 attach、stop 或 restart 的目标不在当前计划里。

missing session_id

如果某个窗口依赖恢复信息，先运行：

cc-branch plan --write-state

找不到命令行工具

cc-branch doctor

先看具体缺的是哪个 command。

继续阅读

  • docs/features.md
  • docs/architecture.md
  • docs/webui-spec.md