{
  "markdown": "# cc-use\n\ncc-use 是一个面向命令行编码 Agent 的监督式执行 Skill。当前外层 Agent 保留用户目标、任务拆解和最终验收，把耗时的调查、实现、测试或真实 TUI 操作交给 tmux 中的内层 Agent。\n\n这里的 Agent 不限定厂商。外层和内层可以是 OpenAI Codex，也可以是 Claude Code。用户没有明确指定跨 Agent 组合或其他特殊要求时，默认让内外层使用同一个 Agent 家族。\n\n```text\n用户\n  ↓\n外层 Agent：计划、监督、纠偏、验收\n  ↓\ncc-use helper：tmux、输入、抓屏、清理\n  ↓\n内层 Agent：调查、编码、运行命令\n```\n\ncc-use 的重点是监督，不是简单并行。外层 Agent 不把整个长期任务一次性丢给内层，而是不断执行：\n\n```text\n启动并检查 TUI\n      ↓\n发送一个具体请求\n      ↓\n等待屏幕稳定\n      ↓\n读取快照并判断\n      ├── 继续等待\n      ├── 发送修正\n      ├── 询问用户\n      └── 外层验收\n      ↓\n任务结束后销毁 session\n```\n\n## 适用场景\n\n| 场景 | cc-use 的作用 |\n|---|---|\n| 多阶段实现或重构 | 外层保留整体目标和验收标准，内层按顺序完成调查、编码和测试 |\n| 长时间排查 | 内层运行日志分析、复现和实验，外层在稳定快照出现后判断下一步 |\n| 端到端与对抗性测试 | 外层设计真实流程、边界条件和回归场景，内层在项目或 TUI 中执行 |\n| 交互式产品验证 | 在真实 Codex CLI、Claude Code、Skill、插件或 MCP 工作流中连续输入和观察 |\n| 输出很多或等待很久的任务 | 把构建、测试、下载和命令输出留在内层，避免占满外层上下文 |\n\n任务不一定必须很长。用户明确要求使用 cc-use，或短任务必须在真实内层 TUI 中验证时，也可以只发送一次 prompt，完成外层验收后立即关闭 session。\n\n简单问答、一次文件读取、单条低风险命令或外层可以直接快速完成的修改，通常没有必要启动额外 TUI。需要频繁选择账号、输入凭证或持续依赖用户即时决策的任务，也不适合无人监督地交给内层。\n\n## 安装\n\n使用 [npx skills](https://skills.sh) 安装。\n\n安装到所有支持的 Agent：\n\n```bash\nnpx skills add zc277584121/cc-use --all -g\n```\n\n只安装到指定 Agent：\n\n```bash\nnpx skills add zc277584121/cc-use -a claude-code -g\nnpx skills add zc277584121/cc-use -a codex -g\n```\n\n更新全局安装：\n\n```bash\nnpx skills update\n```\n\n## 使用方式\n\n在外层 Agent 的正常对话中直接点名 Skill。\n\nCodex 示例：\n\n```text\n$cc-use 调查这个仓库里偶发失败的测试，让内层 Agent 修复并运行测试，\n最后由外层完成验收。\n```\n\nClaude Code 示例：\n\n```text\n使用 cc-use 重构数据库模块。把实现交给内层 session，\n只有需要我决定或已经可以验收时再回来。\n```\n\n用户面对的是 Skill，不需要手动操作 helper 命令。后面的 CLI 主要供 Skill 和开发调试使用。\n\n## 任务级 session\n\n每个完整的用户任务创建一个唯一 tmux session，而不是每个 prompt 创建一个 session。长程任务可以在同一个内层 Agent 对话中连续发送多个短而明确的 prompt，保留它已经获得的项目上下文。这个 session 可以持续很久，也可以跨越多次外层交互；cc-use 不根据运行时长自动关闭它。\n\n一次调查、实现或验收没有达到预期时，只要整体任务仍在继续，就在原 session 中发送修正 prompt，不要先关闭再重新开始。短任务也使用相同粒度，只是可能发送一次 prompt、完成外层验收后就结束。\n\n只有在以下情况才结束 session：\n\n- 整体任务验收成功；\n- 用户取消或更换任务；\n- 外层确认任务最终失败并停止继续修复；\n- 内层执行或启动过程确认无法继续。\n\n任务结束后，外层 Agent 必须调用 `finish`。session 不会被保留给未来无关任务。\n\n## tmux socket 与命名\n\ncc-use 使用固定的专用 tmux socket 路径：\n\n```text\n~/.cc-use/tmux/cc-use\n```\n\nhelper 内部所有 tmux 操作都通过 `tmux -S ~/.cc-use/tmux/cc-use ...` 完成，因此不会与用户默认 tmux server 中的 session 混在一起，也不会因不同 sandbox 的 `/tmp` mount namespace 而看到不同 server。socket 目录权限固定为 `0700`；需要隔离测试或迁移旧 server 时可以通过 `CC_USE_TMUX_SOCKET_DIR` 覆盖目录。\n\n自动生成的 session 名称使用：\n\n```text\nccu-<agent>-<project>-<timestamp>-<pid>\n```\n\n每个完整任务仍然拥有独立 session；多个任务可以在同一个专用 socket 中并行。用户显式指定 session 名称时，helper 也会保留该名称，`list` 会列出专用 socket 内的全部 session。\n\nhelper 不维护额外的进程锁或文件锁。自动生成的唯一 session 名和精确 tmux target 隔离不同任务；创建 session 的调用者负责顺序执行针对同一 session 的 `send`、`keys`、`monitor` 和 `finish`。\n\n需要直接使用 tmux 诊断或只读 attach 时，必须指定同一个 socket 和精确 target，例如：\n\n```bash\ntmux -S ~/.cc-use/tmux/cc-use attach -r -t '=SESSION_NAME'\n```\n\n## 启动安全\n\n启动和发送任务被拆成两个阶段。\n\n第一阶段只启动内层 TUI：\n\n```bash\nskills/cc-use/scripts/cc-use start --project \"$PWD\" --agent codex\n```\n\n`start` 不发送任务，也不会在 TUI 启动后额外盲按 Enter。屏幕稳定后返回启动快照，由外层 Agent 判断：\n\n- 是否已经进入正常输入界面；\n- 是否出现登录或认证选择；\n- 是否出现升级提示；\n- 是否存在权限、信任或 shell 错误。\n\n外层 Agent 可以处理结果明确、低风险并且不会改变环境的启动交互。例如升级提示提供“暂不升级”“跳过”或“继续使用当前版本”时，外层应选择这类选项，再检查新的屏幕快照。不要接受升级、安装或迁移，也不要替用户选择账号、登录方式或凭证。选项含义不清或可能改变环境时，保存必要证据、清理 session，然后报告阻塞。\n\n启动菜单使用独立的按键命令，例如：\n\n```bash\nskills/cc-use/scripts/cc-use keys Escape \\\n  --project \"$PWD\" \\\n  --session SESSION_NAME\n```\n\n具体发送 `Escape`、方向键、数字还是 `Enter`，必须根据当前快照中明确显示的选项决定。`keys` 只发送外层指定的按键并返回新的稳定快照，不会使用任务文本的多次 Enter 提交流程。\n\n确认启动正常后，第二阶段才发送任务：\n\n```bash\nskills/cc-use/scripts/cc-use send \"Investigate the failing test.\" \\\n  --project \"$PWD\" \\\n  --session SESSION_NAME\n```\n\n## 输入机制\n\nTUI 对回车键的处理在不同版本和终端状态下并不完全一致。cc-use 保留了已经验证过的发送流程：\n\n1. 用 `C-u` 清理当前输入；\n2. 通过 tmux buffer 粘贴完整文本；\n3. 发送 `Enter`；\n4. 发送 `C-m` 作为回车兼容路径；\n5. 再发送一次 `Enter`。\n\n这个流程只用于已经通过启动检查的内层 TUI。启动菜单或普通交互提示使用 `keys`，不会使用这组任务提交按键。\n\n## 屏幕观察\n\ncc-use 不解析某个特定 Agent 的 UI，也不使用关键词猜测任务状态。它只做确定性观察：\n\n1. 抓取当前 tmux pane；\n2. 移除 ANSI 转义和行尾空白；\n3. 计算屏幕哈希；\n4. 屏幕变化时重新开始静默计时；\n5. 屏幕连续稳定到阈值后保存一次快照。\n\n典型事件：\n\n```json\n{\n  \"event\": \"screen_stable\",\n  \"phase\": \"work\",\n  \"session\": \"ccu-codex-project-20260804120000-12345\",\n  \"observed_at\": 1785816000,\n  \"silence_seconds\": 30,\n  \"screen_digest\": \"sha256...\",\n  \"screen_path\": \"/project/.cc-use/state/.../screens/...txt\"\n}\n```\n\n`screen_stable` 只表示现在适合查看。它不表示任务完成、失败、阻塞或仍在运行。\n\n外层 Agent 读取 `screen_path` 后，根据真实内容决定下一步。测试、构建和下载可能长时间没有输出，外层可以自行决定等待多久，然后调用：\n\n```bash\nskills/cc-use/scripts/cc-use monitor \\\n  --project \"$PWD\" \\\n  --session SESSION_NAME\n```\n\nhelper 不提供语义上的下次检查时间。`status` 中的 `seconds_until_stable` 只是静默观察窗口的机械倒计时。\n\n## scrollback\n\n当前屏幕不足以理解上下文时，可以读取 tmux 历史：\n\n```bash\nskills/cc-use/scripts/cc-use scrollback \\\n  --session SESSION_NAME \\\n  --lines 2000\n```\n\n也可以指定不重叠的范围：\n\n```bash\nskills/cc-use/scripts/cc-use scrollback \\\n  --session SESSION_NAME \\\n  --start -4000 \\\n  --end -2001\n```\n\n`screen_path` 保存的是 observation 产生时的当前 pane 快照，不一定包含内层 Agent 的完整回答。最终回答较长、终端高度较小，或者关键调查细节出现在更早位置时，需要使用 scrollback 向前查看。\n\n先读取最近一段；信息仍不够时，再使用不重叠的范围继续向前翻。每次读完后，由外层 Agent 根据内容判断证据是否已经足够、是否还要继续向前以及下一次读取多大范围。不要预先规定固定页数，也不要默认一次读取全部历史。\n\nscrollback 只用于这种渐进式上下文补充。cc-use 不默认保存完整长期 transcript，也不在屏幕快速变化时持续读取。\n\n## 外层验收\n\n内层 Agent 的最终回答不能作为成功证明。外层必须直接检查实际结果，例如：\n\n- 查看代码和 diff；\n- 运行相关测试、构建或静态检查；\n- 执行真实命令流程；\n- 检查 UI 或生成物；\n- 对照用户要求确认行为。\n\n整个用户任务验收结束后清理。一次中间验收失败但仍准备继续修复时，不要执行 `finish`：\n\n```bash\nskills/cc-use/scripts/cc-use finish \\\n  --project \"$PWD\" \\\n  --session SESSION_NAME\n```\n\n外层 Agent 只需要决定任务已经整体结束并调用 `finish`，不需要观察后续退出画面。`finish` 会先用独立输入流程粘贴 `/exit` 并只发送一次 `Enter`，然后等待内部 runner 记录内层 TUI 的真实 exit code。\n\nrunner 是 Codex 或 Claude Code 进程的直接父进程，通过 shell 的等待机制取得子进程退出状态。exit code 为 `0` 时，`finish` 返回 `shutdown: graceful`；非 `0` 时返回 `shutdown: abnormal`；等待 10 秒仍没有退出记录时，才精确关闭目标 tmux session，并返回 `shutdown: forced`。这个判断不依赖屏幕文字、shell prompt 或外层 Agent 的语义分析。\n\n内层 TUI 退出后，登录 shell 可能仍留在 tmux 中，因此 `finish` 最后仍会关闭 session 并删除观察状态。这一步只是清理资源，不会把已经记录为 `graceful` 或 `abnormal` 的结果改成强制退出。10 秒是显式结束后的退出宽限期，与任务已经运行多久无关；cc-use 仍然不会按运行时长自动清理 session，也不会按前缀杀掉其他 session。\n\n## shell 环境\n\ncc-use 让 tmux 先启动正常登录 shell，再启动一个内部 runner。runner 随后执行：\n\n```text\ncommand codex ...\ncommand claude ...\n```\n\nrunner 保持为内层 TUI 的父进程，用于在进程结束时记录真实 exit code。因此 PATH、API Key 和其他设置仍由用户自己的 shell 初始化规则提供。cc-use 不扫描 export 行，不依次 source 各种 rc 文件，也不维护额外环境文件。\n\n`command` 会绕过 alias 和 shell function，避免用户 wrapper 重复添加启动参数，但仍然使用登录 shell 得到的 PATH。\n\n修改正常 shell 启动文件后，新建 session 会重新读取。已经运行的旧 session 和 Agent 进程不会自动刷新环境。\n\n## CLI\n\n核心命令：\n\n```text\ncc-use start\ncc-use send\ncc-use keys\ncc-use monitor\ncc-use status\ncc-use scrollback\ncc-use finish\n```\n\n诊断命令：\n\n```text\ncc-use snapshot\ncc-use list\n```\n\n查看完整用法：\n\n```bash\nskills/cc-use/scripts/cc-use\n```\n\n## TUI 录制\n\n仓库仍保留把 tmux TUI 录制为 GIF 的工作流。只有用户明确要求录制演示时，才读取：\n\n```text\nskills/cc-use/references/tui-recording.md\n```\n\n## 定时任务\n\ncc-use 本身不注册 cron、launchd、systemd timer，也不保存定时规则。需要由外部调度器触发 cc-use 时，先阅读[定时任务参考](skills/cc-use/references/scheduled-tasks.md)。\n\n这份文档只说明环境变量、用户 shell、任务重叠、无人值守交互和 session 清理等设计边界。具体使用哪种调度器、如何提供环境和通知，由用户根据机器环境决定。\n\n## 本地开发\n\n运行回归测试：\n\n```bash\nbash tests/cc-use-regression.sh\n```\n\n测试使用临时目录和 tmux stub，不会启动真实 Codex 或 Claude Code。\n\nSkill 源码位置：\n\n```text\nskills/cc-use/SKILL.md\n```\n\n通过 `npx skills` 全局安装后，修改源码并推送还不会自动改变已经进入的交互式 Agent 会话。同步新版本后，需要退出当前 Agent、重新加载 shell，再进入新的会话。\n",
  "bytes": 7103,
  "sha": "51eca01c5a85639cc3ac9f91e05d23519522d23a24891920a4c47f39529dbe44",
  "repo_slug": "zc277584121/cc-use",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/skl_zc277584121_cc_use_cc_use_cd3ab280/readme"
}