Cc Use

# Scheduled Tasks

cc-use can register local recurring tasks for long-running project supervision.
The schedule feature has two modes:

- `heartbeat`: periodically checks that a persistent inner tmux session is
  healthy and responsive.
- `cron`: runs a scheduled prompt or executable script at a calendar time.

Use schedules only when the user explicitly asks to keep a recurring local task
running. Schedules are host-local state. They are not portable by themselves and
should be migrated deliberately per machine.

## Storage And Registration

cc-use stores schedule records under:

```text
~/.cc-use/schedules.json
~/.cc-use/logs/
```

The helper also registers the task with the host scheduler:

- macOS: launchd plist files under `~/Library/LaunchAgents/`.
- Linux: user crontab entries marked with `#cc-use:<id>`.

The registered command calls back into the installed helper:

```bash
<skill_dir>/scripts/cc-use schedule-run <id>
```

This means the schedule behavior follows the installed cc-use skill code. If
the helper path changes during migration, update the launchd or crontab entry.

## Agent Selection

Schedules are agent-neutral. By default, `--agent auto` uses the same agent
family as the outer session that creates the schedule. You may also pass an
explicit supported agent family when the user asks for one.

For scheduled tasks, the default execution policy is intentionally broad:

```text
sandbox = danger-full-access
approval = never
```

This avoids recurring tasks getting stuck on routine filesystem or network
access. Use narrower settings only when the user asks for that tradeoff.

For Codex schedules, `--profile NAME` is supported and stored in the schedule
record. Scheduled Codex `exec` runs include `--skip-git-repo-check` so tasks can
run from ordinary project or script directories that are not git repositories.

## Heartbeat

Create or reuse a heartbeat schedule:

```bash
<skill_dir>/scripts/cc-use schedule-add heartbeat NAME \
  --project "$PWD" \
  --interval-minutes 15 \
  --agent auto \
  --session ccu-my-project
```

Important options:

- `NAME`: human-readable schedule name.
- `--project DIR`: project root for state and tmux session derivation.
- `--interval-minutes N`: run interval. Default is `15`.
- `--agent auto`: use the same agent family as the creator.
- `--profile NAME`: Codex profile, when the user explicitly asks for one.
- `--session NAME`: explicit tmux session name.

On first creation, cc-use creates this project-local file if missing:

```text
<project>/.cc-use/heartbeat.md
```

The heartbeat runner delegates the heartbeat text to the persistent inner tmux
session and records the latest state under:

```text
<project>/.cc-use/heartbeat-state.json
```

The heartbeat should be small and cheap. It should ask the inner session to
report whether it is healthy, blocked, or needs attention.

## Cron

Create a cron-style scheduled task:

```bash
<skill_dir>/scripts/cc-use schedule-add cron NAME \
  --project "$PWD" \
  --cron-expr "30 22 * * *" \
  --prompt "Read ./daily-report.md and follow the instructions." \
  --agent auto
```

For a script-backed task, pass the executable script path as the prompt:

```bash
<skill_dir>/scripts/cc-use schedule-add cron NAME \
  --project "$PWD" \
  --cron-expr "30 22 * * *" \
  --prompt "$PWD/.cc-use/daily-report.sh" \
  --agent auto
```

If the prompt is an executable file path, `schedule-run` executes the script
directly. Otherwise, it sends the prompt to the selected non-interactive agent
runner.

Use `--search` when the scheduled Codex task should enable web search:

```bash
<skill_dir>/scripts/cc-use schedule-add cron NAME \
  --project "$PWD" \
  --cron-expr "30 9 * * 5" \
  --prompt "Read ./weekly-report-prompt.md and follow the instructions." \
  --agent codex \
  --profile zilliz \
  --search
```

## Inspecting And Operating Schedules

List schedules:

```bash
<skill_dir>/scripts/cc-use schedule-list
```

Show all schedules or one schedule with its latest l