cc-use

What this skill does

# cc-use

You are the outer supervisor. Use this skill's `scripts/cc-use` helper as an
implementation detail to start and supervise an inner CC session in tmux.

Here, **CC** means a coding command-line agent. Depending on the host and local
configuration, that can mean Claude Code, Codex CLI, or another compatible
coding CLI.

## When To Use This Skill

Use cc-use for long-term tasks where the outer session should keep the global
state clean and deliberate while an inner interactive session handles focused
execution. The point is not just parallelism; it is supervision. The outer
session keeps the plan, product intent, risks, compatibility concerns, and
acceptance criteria in view while the inner session does bounded work.

This helps when a task is long enough that a single conversation may lose local
details, pollute context with logs, or drift away from the top-level objective.
The inner session can do implementation, command execution, exploration, and
interactive TUI work, while the outer session preserves a compact supervisory
context and performs final judgment.

Do not pass the whole long-term task to the inner session as one giant prompt.
Break it into small, concrete requests, then inspect, steer, and refine like a
human supervisor would:

1. Ask for one focused investigation, implementation step, test case, or
   verification action.
2. Wait for an `inspect` observation.
3. Read the snapshot semantically.
4. Decide the next short request, wait, intervene, ask the user, or verify.
5. Repeat until the outer session has enough evidence to accept or reject the
   work.

Good scenarios:

- **End-to-end verification:** The outer session acts like a tester. It asks the
  inner session to run realistic workflows, edge cases, and command sequences,
  then evaluates the reported result and runs any final checks itself.
- **Task decomposition and implementation:** For a large project with a plan or
  design document, the outer session decomposes the plan into small
  implementation requests and feeds them to the inner session one at a time.
- **Adversarial testing:** The outer session designs high-level adversarial
  cases based on project history, product positioning, architecture,
  compatibility requirements, and likely regressions. The inner session executes
  those cases and reports what happens.
- **Interactive product testing:** For TUI products such as Claude Code, Codex
  CLI, or plugin/skill/MCP workflows, normal one-shot command tests may be
  insufficient. The inner session can install the in-development skill, MCP
  server, or plugin inside an interactive terminal environment, then receive
  follow-up input from the outer session to validate that the integration works
  in the real TUI.

## User Experience

The expected user flow is natural language in the outer TUI:

> Use cc-use to implement this long task: ...

You should then:

1. Start or reuse an inner CC session for the same agent family as the outer
   session.
2. Break the user's request into short, focused inner requests.
3. Send each inner request exactly as written, without wrapper text.
4. Monitor by screen stability, not by parsing agent-specific UI rules.
5. When the screen stays quiet long enough, inspect the saved screen snapshot
   semantically and decide whether to wait, steer, or verify.
6. Run final acceptance checks yourself from the outer session.

## Commands

Run commands from the target project root unless you pass an explicit
`--project DIR`. Use `--agent codex` from Codex and `--agent claude` from
Claude Code. Do not cross-delegate between agent families.

`--project` controls the tmux working directory, the derived session name, and
the `.cc-use/state/` location. If omitted, it defaults to the current directory.
Passing `--project "$PWD"` is recommended when the outer session may change
directories.

### `delegate`

Start or reuse the inner session, send one short request exactly as provided,
and wait until one observation is emitted:

```bash
<skill_dir>/scripts/cc-use delegate "TASK_TEXT" --project "$PWD" --agent codex
```

Important options:

- `--project DIR`: target project root. Also determines state location.
- `--agent codex|claude`: inner agent family. Match the outer agent family.
- `--session NAME`: override the derived tmux session name.
- `--profile NAME`: Codex only; use only if the user explicitly requests an
  inner Codex profile and only when creating the session.
- `--initial-quiet-seconds N`: how long a stable screen must stay quiet before
  an observation is emitted. Default is `30`.
- `--poll-interval N`: seconds between screen captures while waiting. Default
  is `2`.
- `--replace`: kill and recreate an existing session. Use only for recovery or
  an explicit fresh-start decision.

`TASK_TEXT` is passed through unchanged. Keep task decomposition in the outer
session. Do not ask the helper to add role instructions, policy text, or task
wrappers.

For Codex, omit `--profile` by default. Existing tmux/TUI sessions are reused
and do not need the profile on later requests.

### Codex permissions: fully bypassed

cc-use launches the inner Codex with
`--dangerously-bypass-approvals-and-sandbox` — the Codex equivalent of
Claude Code's `--dangerously-skip-permissions`. This matches cc-use's
intent (the inner agent runs unattended automated work) and avoids the
flag-conflict failures the older `--ask-for-approval` / `--sandbox`
combination caused when the user's codex config was already set to a
bypass mode. The `--sandbox` and `--approval` CLI flags to cc-use are
retained for backward compatibility but no longer affect the inner
session.

Expected behavior:

- If the session does not exist, the helper creates a persistent tmux session
  named like `ccu-<project-name>`.
- If the session already exists, the helper reuses it.
- The command normally returns one JSON event after the screen becomes stable.
- If the screen keeps changing, the command may block until the screen becomes
  quiet.

### `monitor`

Observe an existing derived session and wait for one observation:

```bash
<skill_dir>/scripts/cc-use monitor --project "$PWD" --agent codex
```

Use this after a previous observation suggests waiting, after you have waited
based on your own semantic judgment, or after the user asks for status.

Important options:

- `--project DIR`, `--agent codex|claude`, `--session NAME`: identify the target
  session.
- `--initial-quiet-seconds N`, `--poll-interval N`: same meaning as `delegate`.

Expected behavior:

- If the screen changes, the helper resets the quiet timer and continues
  waiting.
- If the screen stays unchanged long enough, the helper saves a snapshot and
  emits an `inspect` observation.
- If the tmux session is gone, the helper emits `session_unavailable`.

### `project-status`

Check the derived project/session status without sending input:

```bash
<skill_dir>/scripts/cc-use project-status --project "$PWD" --agent codex
```

Use `--json` when you need machine-readable output:

```bash
<skill_dir>/scripts/cc-use project-status --project "$PWD" --agent codex --json
```

Expected text output includes:

- `project`: resolved project directory.
- `session`: derived or explicit session name.
- `agent`: selected agent family.
- `session_available`: whether tmux currently has the session.
- `observations`: number of saved observations for this session.
- `silence_seconds`: seconds since the last detected screen change.
- `seconds_until_next_check`: current watch schedule hint from state.

### `scrollback`

If the saved screen snapshot does not include enough context, inspect recent
tmux scrollback on demand. This is a temporary read to stdout, not a persistent
transcript:

```bash
<skill_dir>/scripts/cc-use scrollback --project "$PWD" --agent codex --lines 2000
```

For paged inspection, use tmux line ranges. Negative numbers refer to scrollback
history, `0` is the first visible line, and `-` means the end of the visible
pane:

```bash
<skil