cc-use

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. When the inner session is newly created or replaced, treat startup readiness
   as its own supervision step. Inspect the first stable screen semantically and
   confirm the TUI is usable before sending follow-up work.
3. Break the user's request into short, focused inner requests.
4. Send each inner request exactly as written, without wrapper text.
5. Monitor by screen stability, not by parsing agent-specific UI rules.
6. When the screen stays quiet long enough, inspect the saved screen snapshot
   semantically and decide whether to wait, steer, or verify.
7. 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.

Session names use letters, numbers, underscores, and hyphens. They are exact
identifiers: work is distinct from work-review, and every operation targets
only the requested name. Operations that send input or update observation state
are serialized per session; if another supervisor is already operating on that
session, cc-use reports it as busy. Different named sessions can run in
parallel.

delegate

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

<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 it for explicit
  recovery of that named session.

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.

New-session readiness:

• When a session is newly created, choose a deliberately small first request
  when practical, then inspect the returned screen_path before sending more
  work.
• Treat tmux/session creation as proof that a pane exists, not proof that the
  agent is ready. The first stable screen may still show a startup prompt,
  update notice, auth/permission question, shell error, crashed process, or
  another blocked state.
• Do not accept or initiate agent, CLI, or skill updates from the inner TUI
  unless the user explicitly requested that update. If an update prompt blocks
  startup, dismiss or skip it only when that preserves the existing
  environment, then inspect readiness again; otherwise report the blocker.
• Judge readiness semantically from the screen. Do not turn this into
  agent-specific keyword matching in the skill text or in normal supervision.
• Treat a visibly truncated snapshot as incomplete evidence and inspect again
  before concluding that the inner agent did not respond.
• If readiness is unclear, wait and monitor, inspect scrollback, resolve the
  prompt, restart the named session, or report the blocker. Do not keep sending
  task text into an uncertain TUI state.

Agent startup

cc-use launches the inner Codex with
--dangerously-bypass-approvals-and-sandbox and launches the inner Claude Code
with --dangerously-skip-permissions. Inner sessions are unattended and have
the same broad access expectations for both agent families.

When an unattended Codex TUI must use a specific cached authentication mode,
set CODEX_FORCED_LOGIN_METHOD=api or CODEX_FORCED_LOGIN_METHOD=chatgpt in
the caller's environment. cc-use then passes the corresponding
forced_login_method CLI override to new interactive Codex sessions. Leave the
variable unset for the normal interactive login selection behavior.

The agent starts from the pane's interactive shell so local startup files can
populate PATH, API keys, and other environment settings. cc-use prefixes the
launch with the shell builtin command, making startup independent of aliases
and shell functions while retaining the interactive shell environment.

Keep two startup concerns separate:

• Command resolution: the launch uses the shell's PATH without applying
  aliases or functions.
• Path and environment source: bypassing wrappers does not prove the executable
  is available in every context. Cron jobs, scheduled runs, and nested tmux
  sessions may have a thinner PATH than the outer interactive shell. Verify
  command resolution in the same execution context or use an explicit, intended
  environment override instead of adding host-specific fallback paths to the
  generic skill.

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:

<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:

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

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

<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:

<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:

<skill_dir>/scripts/cc-use scrollback --project "$PWD" --agent codex --start -4000 --end -2001
<skill_dir>/scripts/cc-use scrollback --project "$PWD" --agent codex --start -2000 --end -

Options:

• --lines N: capture from -N through the end of the visible pane. Default is
  2000.
• --start LINE: explicit tmux capture start line.
• --end LINE: explicit tmux capture end line. Default is -.

Line semantics come from tmux:

• Negative numbers are lines in scrollback history.
• 0 is the first visible line.
• - means the end of the visible pane.

Use scrollback only after an inspect observation when the saved snapshot is
too narrow. Do not use it as a continuous progress feed while the screen is
actively changing.

Low-level commands

These exist for diagnostics and recovery:

<skill_dir>/scripts/cc-use list
<skill_dir>/scripts/cc-use snapshot <session>
<skill_dir>/scripts/cc-use kill <session>

Use kill only when the user explicitly asks to close the inner session, or
when the caller has finished with a deliberately short-lived named session.

Keep the inner session running by default. A long-running project may span
multiple outer conversations or calendar days, and the existing tmux/TUI session
preserves useful continuity for later work.

Only stop the default project session when the user asks. A caller that creates
its own named session may define a shorter lifecycle and close it after its work
has been accepted or rejected.

Scheduled tasks

cc-use can also register host-local recurring tasks. Use this only when the user
explicitly asks for a persistent local cron or heartbeat workflow.

• heartbeat periodically checks a persistent inner tmux session.
• cron runs a scheduled prompt or executable script.
• Schedules are agent-neutral; the default --agent auto follows the outer
  session's agent family when the schedule is created.
• Scheduled runs default to danger-full-access and never approval so local
  recurring tasks do not stall on routine filesystem or network access.

For the full workflow, command examples, migration notes, and troubleshooting,
read references/schedules.md.

TUI / tmux recording to GIF

cc-use can also help record an inner TUI session (Claude Code, Codex CLI, or
any ratatui-like app running in tmux) to a small animated GIF — useful for
README headers, blog posts, and docs.

The recording pipeline is asciinema → agg → gifsicle, plus optional
post-processing (cropping the tmux status bar and adding window chrome) with
Pillow.

Use this only when the user explicitly asks to record a TUI session or
produce a GIF demo. Key constraints:

• Probe dependencies and ask the user before installing anything.
• Always keep the intermediate .cast file — it is the canonical source and
  the user may want to re-render later.
• Produce a small slate of GIF variants (different font sizes) rather than one
  fixed spec; let the user choose.
• Bottom-cropping the tmux status bar / shell footer is a per-recording
  judgment call. Inspect a busy frame; do not freeze the heuristic into code.

For the full pipeline, principles, and pseudocode for the cropping decision,
read references/tui-recording.md.

Monitoring Model

delegate and monitor use adaptive observation:

• If the tmux screen changes, the outer agent does not read details and lets the
  inner agent keep working.
• If the screen stays unchanged past the current quiet threshold, cc-use captures
  the screen once and emits a neutral inspect observation.
• The helper does not classify stable screens as wait, intervene, or verify.
  Always read screen_path and make the semantic decision in the outer session.
• If the snapshot is too narrow, use scrollback --lines N or
  scrollback --start LINE --end LINE for temporary context. Do not create
  persistent transcript logs by default.

Typical observation:

{
  "event": "observation",
  "session": "ccu-my-project",
  "observed_at": 1778223935,
  "silence_seconds": 20,
  "screen_digest": "sha256...",
  "screen_path": "/path/to/project/.cc-use/state/ccu-my-project/screens/ccu-my-project-0001.txt",
  "decision": {
    "action": "inspect",
    "next_check_after_seconds": 0,
    "reason": "The screen is stable; inspect screen_path semantically before deciding whether to wait, steer, or verify.",
    "confidence": 1.0
  }
}

inspect means only that the screen is stable enough to review. It does not
mean the task is complete, blocked, failed, or still running. The outer session
must read screen_path and decide.

session_unavailable means tmux no longer has the expected session. Decide
whether to restart, report failure, or ask the user.

Outer Decision Rules

After an inspect observation:

• If the snapshot shows final output or a prompt after a completed response, run
  outer acceptance checks.
• If it shows tests, builds, downloads, or server commands that may still be
  running quietly, wait a reasonable interval and call monitor again.
• If it shows a permission prompt, password prompt, yes/no question, or blocked
  input, intervene or ask the user.
• If it shows an error, send one short corrective request or report the blocker.
• If it is too narrow to understand, monitor again and call scrollback once
  with enough lines or an explicit range, then decide.

If the screen is actively changing, delegate or monitor may not return for a
while because the quiet timer keeps resetting. This is expected. The helper is
designed to avoid consuming active output.

Outer acceptance checks must be run outside the inner session. Check the actual
files, run relevant tests or commands, inspect UI if applicable, and confirm the
work matches the user's request.

Discipline

• Do not expose tmux/session/state details unless the user asks.
• Do not pass or synthesize environment variables for the inner session.
• Keep the default project session available for future delegated work. Follow
  the caller's lifecycle for explicitly named sessions.
• Do not rely on the inner screen as proof of success; verify externally.
• Do not use scrollback as a persistent transcript. It is a temporary tmux
  history read.
• Let the inner agent do implementation work.
• The outer agent owns acceptance testing and final judgment.