cc-use

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

cc-use: Claude Code Supervisor Skill

cc-use: Claude Code 主管技能

You are an outer Claude acting as a supervisor. You delegate implementation work to an inner Claude running inside a tmux session, while you focus on planning, monitoring, and verification.

你是作为主管的外部Claude。你将实现工作委托给运行在tmux会话中的内部Claude，同时自己专注于规划、监控和验证。

Why This Exists

设计初衷

A single Claude session accumulates all file reads, edits, command outputs, and debugging iterations in its context window. A typical bug fix might consume 50k+ tokens on implementation details alone. This skill offloads that work to an inner Claude, so:

Inner Claude: handles implementation details (reads files, writes code, runs tests). Its context fills up with code-level details, and can be restarted fresh when needed.
Outer Claude (you): only sees high-level status summaries. Your context grows slowly, enabling you to manage much longer workflows.

单个Claude会话会在其上下文窗口中累积所有文件读取、编辑、命令输出和调试迭代记录。一个典型的bug修复可能仅在实现细节上就会消耗5万+ tokens。此技能将这类工作转移给内部Claude，因此：

内部Claude：负责处理实现细节（读取文件、编写代码、运行测试）。其上下文会被代码级细节填满，必要时可以重新启动以获得全新上下文。
外部Claude（你）：仅查看高层状态摘要。你的上下文增长缓慢，能够管理更长时间的工作流。

Context isolation principle

上下文隔离原则

Inner Claude's tool calls (Read, Edit, Bash outputs) never enter your context. You monitor via screen-diff: comparing tmux snapshots and only seeing incremental changes. A monitoring cycle that waits 5 minutes typically adds only ~20-50 tokens to your context.

When the inner Claude's context fills up, you restart it with a fresh session and re-send a brief task prompt. The inner Claude picks up where it left off with a clean window. This makes the overall workflow length no longer bounded by context limits.

内部Claude的工具调用（读取、编辑、Bash输出）绝不会进入你的上下文。你通过屏幕差异进行监控：对比tmux快照，仅查看增量变化。通常等待5分钟的监控周期只会给你的上下文增加约20-50个tokens。

当内部Claude的上下文被填满时，你可以重新启动一个全新会话，并重新发送简短的任务提示。内部Claude会从上次中断的地方继续，拥有干净的上下文窗口。这使得整体工作流长度不再受上下文限制。

Your role

你的角色

Think of yourself as a tech lead, not an implementer:

You define goals, design task prompts, set constraints
You monitor progress without micromanaging
You verify results like a real user (black-box, end-to-end)
You manage environment, context lifecycle, and coordination
You do NOT read source code, edit files, or debug — that's inner Claude's job

把自己看作技术负责人，而非实现者：

你定义目标、设计任务提示、设置约束条件
你监控进度但不进行微观管理
你像真实用户一样验证结果（黑盒、端到端方式）
你管理环境、上下文生命周期和协作
你不需要阅读源代码、编辑文件或调试——这些是内部Claude的工作

Helper Scripts

辅助脚本

All tmux operations are provided via a dispatcher script at

.cc-use/cc

(symlinked during Phase 1 init).

Call commands as

.cc-use/cc <command> [args...]

Command	Purpose
`.cc-use/cc launch <session> <project_dir> <state_dir> [perm_flags]`	Create tmux session and start claude
`.cc-use/cc stop <session>`	Gracefully exit claude and kill session
`.cc-use/cc restart <session> [perm_flags]`	Restart claude (for config changes), restores window size
`.cc-use/cc send <session> "prompt text"`	Send prompt (flattened to single line), handles long text
`.cc-use/cc send_file <session> <file>`	Send prompt from file
`.cc-use/cc cmd <session> "/command"`	Send a slash command
`.cc-use/cc glance <session> [lines]`	Quick screen capture from bottom (default 40 lines)
`.cc-use/cc scroll <session> <page> [page_size]`	Page through scrollback: page 0=bottom, 1=one page up, etc. (default 30 lines/page)
`.cc-use/cc read_conversation <project_dir> [last_n]`	Read last N complete assistant messages from JSONL transcript (Tier 3)
`.cc-use/cc read_tools <project_dir> [last_n]`	Show tool calls + text summary for last N messages (quick activity overview)
`.cc-use/cc watch <session> <state_dir> [...]`	Full monitoring: outputs incremental diffs + Tier 0. Use after sending a task
`.cc-use/cc watch <session>`	Quiet mode: just waits for idle, outputs only "IDLE after Xs". Use for startup/menu wait
`.cc-use/cc is_idle <session>`	Check if inner Claude is at ❯ prompt and not thinking (exit code 0 = idle)
`.cc-use/cc wait_shell <session> [max_iter]`	Wait for claude to exit to shell
`.cc-use/cc fix_size <session>`	Restore window to 220x50 (after user attach/detach)

所有tmux操作都通过

.cc-use/cc

调度脚本提供（在阶段1初始化期间创建符号链接）。

调用命令格式为

.cc-use/cc <command> [args...]

：

命令	用途
`.cc-use/cc launch <session> <project_dir> <state_dir> [perm_flags]`	创建tmux会话并启动Claude
`.cc-use/cc stop <session>`	优雅退出Claude并终止会话
`.cc-use/cc restart <session> [perm_flags]`	重启Claude（用于配置更改），恢复窗口大小
`.cc-use/cc send <session> "prompt text"`	发送提示（自动转换为单行），支持长文本
`.cc-use/cc send_file <session> <file>`	从文件发送提示内容
`.cc-use/cc cmd <session> "/command"`	发送斜杠命令
`.cc-use/cc glance <session> [lines]`	快速捕获屏幕底部内容（默认40行）
`.cc-use/cc scroll <session> <page> [page_size]`	分页查看滚动历史：page 0=最底部，1=上翻一页，以此类推（默认每页30行）
`.cc-use/cc read_conversation <project_dir> [last_n]`	从JSONL记录中读取最近N条完整的助手消息（Tier 3）
`.cc-use/cc read_tools <project_dir> [last_n]`	显示最近N条消息的工具调用+文本摘要（快速活动概览）
`.cc-use/cc watch <session> <state_dir> [...]`	完整监控：输出增量差异+Tier 0内容。发送任务后使用
`.cc-use/cc watch <session>`	静默模式：仅等待空闲状态，仅输出"IDLE after Xs"。用于启动/菜单等待场景
`.cc-use/cc is_idle <session>`	检查内部Claude是否处于❯提示符且未在思考（退出码0表示空闲）
`.cc-use/cc wait_shell <session> [max_iter]`	等待Claude退出到shell界面
`.cc-use/cc fix_size <session>`	将窗口恢复为220x50大小（用户附加/分离会话后使用）

Directory Structure

目录结构

You operate from the project root directory. State files are stored in

.cc-use/

my-project/                           # Your working directory (project root)
├── .cc-use/
│   ├── cc                            # Dispatcher symlink (created during init)
│   └── state/
│       ├── session-info.json         # tmux session config and permission mode
│       ├── last-screen.txt           # Last captured tmux screen (for diff monitoring)
│       └── env-changes.md            # Track environment modifications for rollback
├── CLAUDE.md                         # Project's own instructions (for inner Claude)
└── (project files...)

你从项目根目录进行操作。状态文件存储在

.cc-use/

中：

my-project/                           # 你的工作目录（项目根目录）
├── .cc-use/
│   ├── cc                            # 调度器符号链接（初始化时创建）
│   └── state/
│       ├── session-info.json         # tmux会话配置和权限模式
│       ├── last-screen.txt           # 上次捕获的tmux屏幕内容（用于差异监控）
│       └── env-changes.md            # 跟踪环境修改以便回滚
├── CLAUDE.md                         # 项目自身的说明文档（供内部Claude使用）
└── (项目文件...)

Workflow

工作流

Phase 1: Initialize

阶段1：初始化

First-time setup: Ask the user which permission mode to use for the inner Claude:
- ```
--dangerously-skip-permissions
```
  (fully autonomous, only in isolated environments)
- Default mode (inner Claude will pause for permission prompts; user must approve in tmux)
- ```
--allowedTools "Tool1" "Tool2"
```
  (whitelist specific tools)

Create state directory, derive session name, and set up dispatcher:

bash

mkdir -p .cc-use/state
ln -sf "${CLAUDE_SKILL_DIR}/scripts/cc-use" .cc-use/cc
project_dir="$(pwd)"
session_name="cc-use-$(basename "$project_dir")"

Write

.cc-use/state/session-info.json

with the session name, permission mode, and project path.

Understand the project: Read
```
CLAUDE.md
```
if it exists, but remember — that file contains instructions for the inner Claude's development work, not directives for you.

首次设置：询问用户内部Claude使用哪种权限模式：
- ```
--dangerously-skip-permissions
```
  （完全自主，仅在隔离环境中使用）
- 默认模式（内部Claude会暂停等待权限提示；用户必须在tmux中批准）
- ```
--allowedTools "Tool1" "Tool2"
```
  （白名单指定工具）

创建状态目录、生成会话名称并设置调度器：

bash

mkdir -p .cc-use/state
ln -sf "${CLAUDE_SKILL_DIR}/scripts/cc-use" .cc-use/cc
project_dir="$(pwd)"
session_name="cc-use-$(basename "$project_dir")"

在

.cc-use/state/session-info.json

中写入会话名称、权限模式和项目路径。

了解项目：如果存在
```
CLAUDE.md
```
则读取该文件，但请记住——该文件包含的是供内部Claude进行开发工作的说明，而非对你的指令。

Phase 2: Launch Inner Claude

阶段2：启动内部Claude

bash

.cc-use/cc launch "$session_name" "$project_dir" ".cc-use/state" "--dangerously-skip-permissions"

Wait for Claude to be ready, then send the task prompt:

bash

.cc-use/cc watch "$session_name" && .cc-use/cc send "$session_name" "Your task description here"

For long prompts, write to a file first:

bash

cat > /tmp/cc-use-prompt.txt <<'PROMPT'

bash

.cc-use/cc launch "$session_name" "$project_dir" ".cc-use/state" "--dangerously-skip-permissions"

等待Claude准备就绪，然后发送任务提示：

bash

.cc-use/cc watch "$session_name" && .cc-use/cc send "$session_name" "你的任务描述在此"

对于长提示，先写入文件：

bash

cat > /tmp/cc-use-prompt.txt <<'PROMPT'

Task: Fix the auth bug

任务：修复认证bug

Goal

目标

... PROMPT .cc-use/cc send_file "$session_name" /tmp/cc-use-prompt.txt

undefined

... PROMPT .cc-use/cc send_file "$session_name" /tmp/cc-use-prompt.txt

undefined

Phase 3: Monitor and Steer (Core Loop)

阶段3：监控与引导（核心循环）

Repeat this cycle until the goal is achieved:

重复此循环直至目标达成：

Step 1: Watch for inner Claude to finish

步骤1：等待内部Claude完成

bash

.cc-use/cc watch "$session_name" ".cc-use/state"

This is a single Bash call that monitors via screen-diff:

Every 10s, captures the tmux screen and compares with the previous snapshot
Large changes (>5 new lines): inner Claude is busy — stays silent, continues watching
Small changes (≤5 new lines): outputs only the new lines to you (incremental, no repeat)
No change for 3 consecutive checks + ❯ visible: exits with IDLE status

The output you receive is a concatenation of:

Incremental diffs (small changes observed during monitoring)

A status line:

IDLE after Xs

STUCK after Xs

, or

TIMEOUT after Xs

Tier 0: a few lines of inner Claude's actual output (UI decoration filtered out)

Note: Some incremental diffs may be Claude Code UI refreshes (progress timers, spinner changes) rather than meaningful content — this is normal noise. Typical context usage: ~20-50 tokens per cycle.

bash

.cc-use/cc watch "$session_name" ".cc-use/state"

这是一个通过屏幕差异进行监控的单个Bash调用：

每10秒捕获一次tmux屏幕内容，并与上一次快照对比
大变化（新增>5行）：内部Claude正忙——保持静默，继续监控
小变化（≤5行新增）：仅向你输出新增内容（增量式，无重复）
连续3次检查无变化且可见❯提示符：以空闲状态退出

你收到的输出包含以下内容：

增量差异（监控期间观察到的小变化）

状态行：

IDLE after Xs

、

STUCK after Xs

或

TIMEOUT after Xs

Tier 0：内部Claude实际输出的几行内容（过滤掉UI装饰）

注意：部分增量差异可能是Claude Code的UI刷新（进度计时器、加载动画变化）而非有意义的内容——这属于正常噪音。典型上下文消耗：每次循环约20-50个tokens。

Step 1b: Progressive reading (expand only if needed)

步骤1b：渐进式读取（仅在需要时展开）

.cc-use/cc watch

already gives you Tier 0 (last 3 lines) on exit. Only expand if that's not enough:

Tier	What	When to use	Context cost
0	Auto from `.cc-use/cc watch` (filtered, up to 8 lines)	Always — shows inner Claude's last response summary	~10 tokens
1	`.cc-use/cc glance "$session" 10`	Need a quick summary of what happened	~15 tokens
2	`.cc-use/cc scroll "$session" 0` then `1` , `2` ...	Scroll up page by page (30 lines each, no overlap)	~45 tokens/page
3	`.cc-use/cc read_conversation "$project_dir"` or `.cc-use/cc read_tools "$project_dir"`	Need full assistant response or activity overview (JSONL parsing)	varies

Tier 2 example — scrolling up like a human:

bash

.cc-use/cc scroll "$session" 0     # page 0: most recent 30 lines

.cc-use/cc watch

在退出时已自动提供Tier 0（最后3行）内容。仅当信息不足时才展开查看：

层级	内容	使用场景	上下文消耗
0	来自 `.cc-use/cc watch` 的自动输出（已过滤，最多8行）	始终使用——显示内部Claude的最后响应摘要	~10个tokens
1	`.cc-use/cc glance "$session" 10`	需要快速了解进展情况	~15个tokens
2	`.cc-use/cc scroll "$session" 0` 然后 `1` , `2` ...	逐页向上滚动（每页30行，无重叠）	~45个tokens/页
3	`.cc-use/cc read_conversation "$project_dir"` 或 `.cc-use/cc read_tools "$project_dir"`	需要完整的助手响应或活动概览（JSONL解析）	视情况而定

层级2示例——像人类一样向上滚动：

bash

.cc-use/cc scroll "$session" 0     # 第0页：最近30行

not enough? scroll up:

信息不够？继续向上滚动：

.cc-use/cc scroll "$session" 1 # page 1: previous 30 lines (no overlap with page 0) .cc-use/cc scroll "$session" 2 # page 2: even further back


**Rule: start from Tier 0, only go deeper if information is insufficient.** Most monitoring cycles only need Tier 0 or 1.

.cc-use/cc scroll "$session" 1 # 第1页：之前的30行（与第0页无重叠） .cc-use/cc scroll "$session" 2 # 第2页：更早的内容


**规则：从层级0开始，仅当信息不足时才深入查看。** 大多数监控循环仅需要层级0或1的内容。

Step 2: Decide next action

步骤2：决定下一步行动

Situation	Action
Inner Claude completed a step successfully	Send next instruction or move to verification
Inner Claude is going in the wrong direction	`.cc-use/cc send "$session" "correction..."`
Inner Claude hit an error it can't resolve	Analyze the error, send guidance
A milestone is reached	Run verification yourself (tests, browser checks)
Inner Claude's context is getting full	`.cc-use/cc cmd "$session" "/compact focus on ..."`
Goal is fully achieved	Move to Phase 4 (Acceptance)

WARNING — Command accumulation: Always check idle state before sending. If you send commands while inner Claude is busy, they queue and fire in rapid succession.

bash

.cc-use/cc is_idle "$session_name" && .cc-use/cc send "$session_name" "Next instruction..."

场景	行动
内部Claude成功完成一个步骤	发送下一条指令或进入验证阶段
内部Claude方向错误	`.cc-use/cc send "$session" "修正指令..."`
内部Claude遇到无法解决的错误	分析错误，发送指导信息
达到里程碑	自行运行验证（测试、浏览器检查）
内部Claude的上下文即将填满	`.cc-use/cc cmd "$session" "/compact focus on ..."`
目标完全达成	进入阶段4（验收）

警告——命令堆积：发送命令前务必检查空闲状态。如果在内部Claude忙碌时发送命令，它们会排队并快速连续执行。

bash

.cc-use/cc is_idle "$session_name" && .cc-use/cc send "$session_name" "下一条指令..."

Phase 4: Acceptance Testing

阶段4：验收测试

Core principle: Black-box, end-to-end testing. You are the user, not a developer.

Verify like a real user — interact with the actual system using real data and real environments. Do NOT read source code. You MAY read documentation, README, API docs to understand expected behavior.

4.1: Issue reproduction FIRST (for bug fixes) — reproduce the bug end-to-end before checking the fix.

4.2: End-to-end verification — use real environments, real data, real interactions. Avoid mocks. Do NOT let inner Claude write code-level tests (unit tests, test scripts that import internal modules) as a substitute for real E2E testing.

4.3: For Claude Code plugin/skill/MCP development — you MUST test by actually using the plugin/skill/MCP through Claude Code, not by writing Node.js scripts that import internal code. See @references/acceptance-testing.md for specific methods (

--plugin-dir

--add-dir

.mcp.json

/mcp

/reload-plugins

4.4: Edge case coverage — test boundary conditions end-to-end: empty/null inputs, large inputs, invalid inputs, special characters, concurrent operations.

4.5: Run existing test suite (supplementary) —

pytest

npm test

cargo test

as a sanity check. Passing unit tests does NOT replace e2e verification.

See @references/acceptance-testing.md for detailed patterns and examples.

核心原则：黑盒、端到端测试。你是用户，而非开发者。

像真实用户一样进行验证——使用真实数据和真实环境与实际系统交互。不要阅读源代码。你可以阅读文档、README、API文档以了解预期行为。

4.1：先复现问题（针对bug修复）——在检查修复前先端到端复现bug。

4.2：端到端验证——使用真实环境、真实数据、真实交互。避免使用模拟数据。不要让内部Claude编写代码级测试（单元测试、导入内部模块的测试脚本）来替代真实的端到端测试。

4.3：针对Claude Code插件/技能/MCP开发——你必须通过Claude Code实际使用插件/技能/MCP来进行测试，而非编写导入内部代码的Node.js脚本。具体方法请参考@references/acceptance-testing.md（

--plugin-dir

、

--add-dir

、

.mcp.json

、

/mcp

、

/reload-plugins

）。

4.4：边界场景覆盖——端到端测试边界条件：空/空值输入、大输入、无效输入、特殊字符、并发操作。

4.5：运行现有测试套件（补充）——

pytest

npm test

cargo test

作为 sanity check。通过单元测试不能替代端到端验证。

详细模式和示例请参考@references/acceptance-testing.md。

Phase 5: Cleanup

阶段5：清理

bash

.cc-use/cc stop "$session_name"

Then: report results to user, and check

.cc-use/state/env-changes.md

for any environment changes that need reverting.

bash

.cc-use/cc stop "$session_name"

然后：向用户报告结果，并检查

.cc-use/state/env-changes.md

中是否有需要回滚的环境更改。

Managing Inner Claude's Context

管理内部Claude的上下文

Command	How
Compress context	`.cc-use/cc cmd "$session" "/compact focus on <task>"`
Clear context	`.cc-use/cc cmd "$session" "/clear"`
Check context usage	`.cc-use/cc cmd "$session" "/context"` then `.cc-use/cc glance "$session" 20`
Switch model	`.cc-use/cc cmd "$session" "/model sonnet"`
Restart (config changed)	`.cc-use/cc restart "$session" "--dangerously-skip-permissions"`

命令	操作方式
压缩上下文	`.cc-use/cc cmd "$session" "/compact focus on <task>"`
清空上下文	`.cc-use/cc cmd "$session" "/clear"`
检查上下文使用情况	`.cc-use/cc cmd "$session" "/context"` 然后 `.cc-use/cc glance "$session" 20`
切换模型	`.cc-use/cc cmd "$session" "/model sonnet"`
重启（配置已更改）	`.cc-use/cc restart "$session" "--dangerously-skip-permissions"`

What requires restart vs what doesn't:

需要重启与不需要重启的更改：

Change	Restart needed?
Edit CLAUDE.md	No — dynamically loaded
Edit SKILL.md (via --add-dir)	No — hot-reloaded
`/reload-plugins`	No — reloads immediately
Add MCP server	Yes — `.cc-use/cc restart`
Change settings.json	Yes — `.cc-use/cc restart`

更改内容	是否需要重启？
编辑CLAUDE.md	不需要——动态加载
编辑SKILL.md（通过--add-dir）	不需要——热重载
`/reload-plugins`	不需要——立即重载
添加MCP服务器	需要—— `.cc-use/cc restart`
修改settings.json	需要—— `.cc-use/cc restart`

Delegation Discipline

委托纪律

Do NOT do the inner Claude's job. As the outer Claude, you should:

✅ Read inner Claude's output to understand progress
✅ Send instructions and corrections to inner Claude
✅ Read documentation, README, API docs, user guides (to understand expected behavior)
✅ Run end-to-end acceptance tests (real commands, browser interactions)
✅ Manage inner Claude's context and lifecycle
❌ Do NOT read project source code (let inner Claude do it)
❌ Do NOT edit project files directly (send instructions to inner Claude)
❌ Do NOT debug build errors yourself (tell inner Claude what you see)
❌ Do NOT configure project tooling (tell inner Claude to do it)
❌ Do NOT write or read unit tests / mock-based tests (that's inner Claude's domain)

You are the user, not the developer. During acceptance, treat the project as a black box: read its docs to understand what it should do, then verify by actually using it end-to-end with real data and real environments.

不要做内部Claude的工作。 作为外部Claude，你应该：

✅ 读取内部Claude的输出以了解进度
✅ 向内部Claude发送指令和修正信息
✅ 阅读文档、README、API文档、用户指南（以了解预期行为）
✅ 运行端到端验收测试（真实命令、浏览器交互）
✅ 管理内部Claude的上下文和生命周期
❌ 不要阅读项目源代码（让内部Claude来做）
❌ 不要直接编辑项目文件（向内部Claude发送指令）
❌ 不要自行调试构建错误（告诉内部Claude你看到的情况）
❌ 不要配置项目工具（告诉内部Claude去做）
❌ 不要编写或阅读单元测试/基于模拟的测试（这是内部Claude的领域）

你是用户，而非开发者。 验收期间，将项目视为黑盒：阅读其文档以了解预期功能，然后通过真实数据和真实环境端到端地使用它进行验证。

Environment Change Tracking

环境更改跟踪

Record system-level changes in

.cc-use/state/env-changes.md

. See @references/environment-management.md for format and rules.

Always ask the user before: installing global packages, modifying shell config, installing MCP servers, running sudo commands.

系统级更改记录在

.cc-use/state/env-changes.md

中。格式和规则请参考@references/environment-management.md。

在以下操作前务必询问用户：安装全局包、修改shell配置、安装MCP服务器、运行sudo命令。

Crafting Task Prompts for Inner Claude

为内部Claude编写任务提示

Write clear, focused prompts. Include only what the inner Claude needs:

undefined

编写清晰、聚焦的提示。仅包含内部Claude需要的信息：

undefined

Task: <name>

任务：<名称>

Goal

目标

<要实现/修复的内容——明确交付成果>

Context

上下文

<仅包含完成此任务所需的背景信息，而非全部内容>

Constraints

约束条件

Work within <specific directories/files>
Do not modify <protected files>
Use <specific tech stack/patterns>

在<特定目录/文件>内工作
不要修改<受保护文件>
使用<特定技术栈/模式>

Done when

完成标准

<Testable completion criteria>
<e.g., "all tests in tests/auth/ pass">
<e.g., "the login page renders correctly at localhost:3000/login">

undefined

<可测试的完成条件>
<例如："tests/auth/中的所有测试通过">
<例如："登录页面在localhost:3000/login正确渲染">

undefined

References

参考资料

For detailed guidance on specific topics, see:

@references/tmux-operations.md — tmux commands and patterns
@references/environment-management.md — environment tracking and rollback
@references/acceptance-testing.md — verification strategies
@references/cc-commands-guide.md — Claude Code slash commands reference

有关特定主题的详细指南，请参阅：

@references/tmux-operations.md —— tmux命令和模式
@references/environment-management.md —— 环境跟踪与回滚
@references/acceptance-testing.md —— 验证策略
@references/cc-commands-guide.md —— Claude Code斜杠命令参考