commandmate 0.43.0 → 0.44.0

package/docs/en/user-guide/cmate-schedules-guide.md

@@ -0,0 +1,388 @@
+[日本語版](../../user-guide/cmate-schedules-guide.md)
+
+# CMATE Schedules Guide
+
+A guide to setting up and managing scheduled executions using CMATE.md files.
+
+---
+
+## Overview
+
+The CMATE schedule feature allows you to automatically execute `claude -p` (or `codex exec`, `gemini -p`, `vibe-local -p`, `gh copilot -p`, `agy -p`, `opencode run`) commands by defining cron expressions in the Schedules section of a `CMATE.md` file placed in your worktree root.
+
+**How it works:**
+
+```
+Define a Schedules table in CMATE.md
+  ↓
+CommandMate polls CMATE.md every 60 seconds
+  ↓
+When a cron expression matches, claude -p is executed automatically
+  ↓
+Results are recorded in Execution Logs
+```
+
+---
+
+## Creating CMATE.md
+
+### File Location
+
+Place `CMATE.md` in the root directory of your worktree.
+
+```
+your-project/          ← worktree root
+├── CMATE.md           ← place it here
+├── src/
+├── package.json
+└── ...
+```
+
+### Creating via UI
+
+1. Select a worktree from the sidebar
+2. Click the **CMATE** tab
+3. Click the **CMATE button** to create a `CMATE.md` with a starter template
+
+---
+
+## Writing the Schedules Table
+
+Create a `## Schedules` section in your `CMATE.md` and define entries using Markdown table format.
+
+### Table Structure
+
+```markdown
+## Schedules
+
+| Name | Cron | Message | CLI Tool | Enabled | Permission |
+|------|------|---------|----------|---------|------------|
+| daily-review | 0 9 * * * | Review code changes and report improvements | claude | true | acceptEdits |
+```
+
+### Column Reference
+
+| Column | Required | Description | Default |
+|--------|----------|-------------|---------|
+| **Name** | Yes | Schedule name. 1-100 characters. Alphanumeric, Japanese, hyphens, and spaces allowed | - |
+| **Cron** | Yes | Cron expression (5-6 fields). Defines execution timing | - |
+| **Message** | Yes | Prompt sent to `claude -p`. Max 10,000 characters | - |
+| **CLI Tool** | No | CLI tool to use (`claude` / `codex` / `gemini` / `vibe-local` / `opencode` / `copilot` / `antigravity` / `command-code` / `opencode-v2`; the authority is `CLI_TOOL_IDS` in `src/lib/cli-tools/types.ts`). **Only copilot, opencode and opencode-v2 accept `--model <model-name>`** — writing it for another tool is a syntax error and the whole row is skipped. opencode and opencode-v2 also accept `--agent` / `--variant` / `--continue` / `--title` (Issue #2044 / #2982; opencode-v2's `--variant` only together with `--model`) | `claude` |
+| **Enabled** | No | Enable/disable the schedule (`true` / `false`) | `true` |
+| **Permission** | No | Execution permission level. See Permission Reference below | Tool-specific default |
+
+### Cron Expression Quick Reference
+
+| Pattern | Description |
+|---------|-------------|
+| `0 * * * *` | Every hour at :00 |
+| `0 9 * * *` | Daily at 9:00 |
+| `0 9 * * 1-5` | Weekdays at 9:00 |
+| `0 18 * * 5` | Every Friday at 18:00 |
+| `0 2 * * *` | Daily at 2:00 |
+| `0 0 1 * *` | 1st of every month at 0:00 |
+| `*/30 * * * *` | Every 30 minutes |
+
+Cron expressions support 5 fields (minute hour day month weekday) or 6 fields (second minute hour day month weekday).
+
+---
+
+## Permission Reference
+
+### claude (--permission-mode)
+
+| Value | Description |
+|-------|-------------|
+| `default` | Default permissions. Prompts for confirmation on file changes |
+| `acceptEdits` | Automatically accepts file edits (**default**) |
+| `plan` | Plan mode. Does not make code changes |
+| `dontAsk` | Automatically approves all permissions |
+| `bypassPermissions` | Skips all permission checks |
+
+### codex (--sandbox)
+
+| Value | Description |
+|-------|-------------|
+| `read-only` | Read-only access. Cannot modify files |
+| `workspace-write` | Allows file changes within the workspace (**default**) |
+| `danger-full-access` | Full access to all files |
+
+### gemini
+
+No permission settings. The Permission column is ignored (writing a value in it is a validation error).
+
+### copilot (--allow-all-tools / --yolo)
+
+| Value | Description |
+|-------|-------------|
+| `allow-all-tools` | Allows all tool usage (**default**) |
+| `yolo` | Allows all tool usage and bypasses all user confirmations |
+
+> **Warning:** `yolo` is the maximum permission mode that bypasses all user confirmations. When combined with scheduled execution (unattended batch), there is a risk of unrestricted file system writes and arbitrary command execution without human review.
+
+#### Copilot Model Selection
+
+Use `copilot --model <model-name>` in the CLI Tool column to specify a model for scheduled execution.
+
+```markdown
+| copilot-task | 0 9 * * * | Analyze code changes | copilot --model claude-opus-4.6 | true | allow-all-tools |
+```
+
+Model names may contain alphanumeric characters, hyphens, dots, slashes and colons, and must start with an alphanumeric (a leading `-` is rejected because it is ambiguous with a CLI option). **In the CLI Tool column, `--model` is accepted for copilot and opencode only** — for any other tool it is not "ignored" but a **syntax error that skips the whole schedule row** (`TOOLS_WITH_MODEL_SUPPORT` in `parseCliToolColumn`). The vibe-local model comes from the worktree's Agent settings (the DB) instead, and antigravity's `--model` takes display names containing spaces, which a single CLI Tool cell cannot represent — that one belongs to `commandmate send --model`.
+
+### antigravity (--dangerously-skip-permissions)
+
+| Value | Description |
+|-------|-------------|
+| `--dangerously-skip-permissions` | Auto-approves tool use (**default**; no other value is accepted) |
+
+> **Warning:** note that this is the only permitted value, and scheduled execution is an unattended batch.
+
+### opencode-v2 (--auto)
+
+`opencode-v2` (OpenCode V2, executable `opencode2`, or an `opencode` whose `--version` reports v2) runs as
+`opencode2 run --standalone --format json [--auto] -- <message>` (Issue #2974). The body of the last
+message is taken from the NDJSON output and stored in the execution log.
+
+| Value | Description |
+|-------|-------------|
+| `default` | No flag (**default**). A request that hits an `ask` rule in OpenCode's `permission` config is rejected automatically, and the run is **recorded as failed (exit 1)** |
+| `auto` | Passes `--auto`: permission requests that are not explicitly `deny`-ed (including `ask`) are approved automatically |
+
+- Measured on OpenCode V2 2.0.18: with no `permission` config, writes go through without a prompt. With an
+  `ask` rule, stderr says `permission requested: edit (…); auto-rejecting` and the process exits 1; the
+  execution log carries a Reason line saying that `auto` approves it unattended. The run never "succeeds"
+  having changed nothing.
+- **`deny` is not a sandbox**: with `edit: deny` / `write: deny` the model was still able to write a file
+  through the `shell` tool. Keep that in mind especially when combining it with `auto`.
+- **An operation answered with "Always allow" on screen is allowed in the schedules of every worktree of the
+  same repository.** OpenCode treats the worktrees of one repository as one project and saves "Always allow"
+  there. So even with the default Permission (`default`), an operation always-allowed in any worktree is not stopped
+  by `ask` (measured: an "Always allow" for `edit *` left in this repository's project let the edit `ask` through,
+  while a bash `ask` with no saved allowance was recorded as failed; the UAT of Issue #2979).
+- `--standalone` is always passed. Without it `opencode2 run` connects to the operator's background service
+  (`opencode serve --service`), starting one and leaving it behind when there is none. With `--standalone`
+  each run starts a private server, and no process is left after it ends.
+- The run happens in the worktree that holds the schedule, and reads that worktree's `opencode.json` /
+  `AGENTS.md`. OpenCode V2 picks its project from the `PWD` environment variable rather than its working
+  directory, so the child is started with `PWD` set to the worktree (Issue #2979; before that it ran in the
+  directory the server was started from).
+
+#### opencode-v2 run options (Issue #2982)
+
+The CLI Tool column takes run options with the same spelling as v1.
+
+```
+opencode-v2 [--model <provider/model> [--variant <name>]] [--agent <name>] [--continue] [--title <text>]
+```
+
+| In the column | Argument passed to `opencode2 run` |
+|---|---|
+| `--model <provider/model>` (or `-m`) | `-m <provider/model>` |
+| `--model <provider/model> --variant <name>` | `-m <provider/model>#<name>` |
+| `--agent <name>` | `--agent <name>` |
+| `--continue` (or `-c`) | `-c` |
+| `--title <text>` (wrap in `"…"` if it contains spaces) | `--title <text>` |
+
+- **`--variant` is only accepted together with `--model`.** `opencode2 run` has no `--variant` flag
+  (`Unrecognized flag`, exit 1 on 2.0.18); the variant rides on the model as `-m provider/model#variant`.
+  A `--variant` without a model is not silently dropped: it is a syntax error and the row is skipped
+  (the schedule editor and the API refuse it before saving, too). v1 (`opencode`) still accepts a
+  model-less `--variant`.
+- A `#` cannot be written in the `--model` value itself (invalid model-name character); use `--variant`.
+- Values are validated as for v1 (allowed characters, length). Choosing OpenCode V2 in the schedule editor
+  shows the Model / Agent / Variant / Title / Continue fields.
+
+```markdown
+| nightly-v2 | 0 2 * * * | Check for dependency updates | opencode-v2 | true | default |
+| review-v2 | 0 3 * * * | Review today's diff | opencode-v2 --model anthropic/claude-sonnet-4-5 --agent plan | true | default |
+| deep-v2 | 0 4 * * * | Look for vulnerable dependencies | opencode-v2 --model anthropic/claude-sonnet-4-5 --variant high --title "nightly deps" | true | auto |
+```
+
+### command-code (--yolo / --permission-mode)
+
+| Value | Description |
+|-------|-------------|
+| `yolo` | Launch with `--yolo` (= `--dangerously-skip-permissions`) (**default**). **The only value that lets the run write anything** |
+| `default` | `--permission-mode default`. Read-only (see the Warning below) |
+| `standard` | `--permission-mode standard`. Read-only |
+| `plan` | `--permission-mode plan`. Read-only |
+| `auto-accept` | `--permission-mode auto-accept`. Read-only |
+| `dont-ask` | `--permission-mode dont-ask`. Read-only |
+
+> **Warning:** in the print mode a schedule runs (`commandcode -p`), launching with anything other
+> than `--yolo` blocks five tools: `edit_file` / `write_file` / `shell_command` /
+> `monitor_command` / `kill_shell`. `--permission-mode` does not reach that gate at all, so **all
+> five mode values leave the run read-only**. Worse, a block does not fail the run — it ends exit 0
+> with `subtype:"success"` — so the execution log reports success while nothing was produced
+> (measured on the Command Code 1.53.0 bundle, Issue #2454). Leave the column at `yolo` for any
+> schedule that is supposed to write files.
+
+> **Note:** `yolo` is a CommandMate Permission-column value, not a sixth `--permission-mode` value.
+> It names the **flag**, the same way `yolo` does in the copilot column. The five values
+> `--permission-mode` accepts are read off the shipped bundle's
+> `.choices(["default","standard","plan","auto-accept","dont-ask"])`, not off `commandcode --help`,
+> which advertises only three of them (Issue #2250). An empty Permission column resolves to `yolo`.
+
+> **Note:** `--yolo` is not absolute. If the worktree's `.commandcode/settings.json` sets
+> `permissions.disableBypass` to true, `--yolo` itself is disabled and the run falls back to the
+> read-only state the Warning above describes. `permissions.deny` applies even under `--yolo`, and a
+> denied tool call ends the run with exit 4.
+
+> **Note:** print mode withholds these tools entirely: `ask_user_question` / `enter_plan_mode` /
+> `exit_plan_mode` / `plan_review` / `todo_write` / `cron_create` / `cron_list` / `cron_delete` /
+> `taste`. They are the ones that need a human to answer or a TUI to draw, so do not write a message
+> that depends on them.
+
+### opencode
+
+No permission settings, so **writing a value in the Permission column is a validation error**
+(Issue #1914). Before that, Claude's `--permission-mode` values (`acceptEdits` and friends) were
+accepted here and handed to a CLI that has no such option.
+
+> **Note:** "no permission settings" means opencode has no permission *level* vocabulary, not that it
+> has no flag at all. `opencode run` carries a boolean `--auto`, described by its own `--help` as
+> "auto-approve permissions that are not explicitly denied" (measured on opencode 1.18.21).
+> That is a different axis from claude's `--permission-mode` or codex's `--sandbox`, and CommandMate
+> does not pass it today.
+
+#### OpenCode Model Selection
+
+Use `opencode --model <provider/model>` in the CLI Tool column and the schedule launches
+`opencode run -m <provider/model> <message>`.
+
+```markdown
+| oc-task | 0 9 * * * | Analyze code changes | opencode --model ollama/qwen3:8b | true | |
+```
+
+The value is in **`provider/model` form** — that is what `opencode run --help` documents for
+`-m, --model` ("model to use in the format of provider/model", measured on 1.18.21) — and
+CommandMate passes it through **verbatim**. Before Issue #1914 the code prefixed it with `ollama/`,
+in a branch that could never run (`resolveModelOption()` always answered `undefined` for opencode);
+the prefix made every other provider unreachable and doubled up any value that already named one.
+A malformed value fails inside opencode with an opaque error — measured, an unknown provider and a
+bare model name produce the identical `UnknownError`, so CommandMate does not try to guess the shape
+and reject it here. Check the Execution Log for the result.
+
+> **Note:** opencode is not one of `commandmate report generate --tool`'s values
+> (`SUMMARY_ALLOWED_TOOLS` is claude / codex / copilot / antigravity). `--model` became available for
+> CMATE.md scheduled execution only.
+
+### vibe-local
+
+No permission settings. The Permission column is ignored. The `-y` flag is used for auto-approval.
+
+> **Note:** The vibe-local model uses the Ollama model selected in the worktree's Agent settings.
+
+---
+
+## Practical Examples
+
+### Daily Code Review
+
+```markdown
+| daily-review | 0 9 * * 1-5 | Review yesterday's commits and report any improvements | claude | true | acceptEdits |
+```
+
+Automatically runs a code review at 9:00 AM on weekdays.
+
+### Nightly Test Execution
+
+```markdown
+| nightly-test | 0 2 * * * | Run npm run test:unit and summarize the results | claude | true | plan |
+```
+
+Runs tests every night at 2:00 AM and generates a report. Uses `plan` mode so no code changes are made.
+
+### Hourly Status Check
+
+```markdown
+| hourly-status | 0 * * * * | Check git status and report any issues | claude | true | default |
+```
+
+Checks repository status at the top of every hour.
+
+---
+
+## Checking Results in the UI
+
+### Schedule List
+
+1. Select a worktree from the sidebar
+2. Click the **CMATE** tab
+3. Defined schedules are listed in the **Schedules** section
+
+### Viewing Execution Logs
+
+1. Check the **Execution Logs** section in the **CMATE** tab
+2. Click on a log entry to expand it and view details:
+   - **Message**: The prompt that was sent
+   - **Response**: The response from the CLI tool
+
+---
+
+## Validation
+
+CommandMate automatically validates the contents of CMATE.md.
+
+### When Validation Occurs
+
+- When you re-click the CMATE button
+- During CommandMate's 60-second polling cycle
+
+### Validation Rules
+
+| Field | Rule |
+|-------|------|
+| Name | 1-100 characters, alphanumeric/Japanese/hyphens/spaces only |
+| Cron | Valid cron expression with 5-6 fields |
+| Message | Must not be empty. Max 10,000 characters |
+| CLI Tool | Must be `claude`, `codex`, `gemini`, `vibe-local`, `opencode`, `copilot`, `antigravity`, or `command-code` |
+| Permission | Must match an allowed value for the selected tool |
+
+Invalid entries are skipped with a warning log. Other valid entries are processed normally.
+
+---
+
+## Troubleshooting
+
+### Schedule Is Not Executing
+
+- **Check Enabled**: Make sure it is not set to `false`
+- **Check Cron Expression**: Verify the format is correct (5-6 fields)
+- **Check CMATE.md Location**: Ensure it is placed in the worktree root directory
+- **Check CommandMate Status**: Make sure the server is running
+
+### Permission Confirmation Messages Appear
+
+- Set the Permission column explicitly
+- For claude, ensure the Permission level is appropriate for the operations your prompt requires (e.g., `acceptEdits` or higher for file modifications)
+
+### Behavior When Changing Names
+
+- Changing a schedule name causes it to be recognized as a new schedule
+- The schedule with the old name is automatically stopped
+
+### Concurrent Execution
+
+- Concurrent execution of the same schedule is prevented (the next execution is skipped until the current one completes)
+- A maximum of 100 schedules can be registered across all worktrees
+
+---
+
+## CLI Access
+
+```bash
+commandmate docs --section cmate-schedules
+```
+
+Use this command to view this guide from your terminal.
+
+---
+
+## Related Documentation
+
+- [Quick Start Guide](./quick-start.md) - Get started in 5 minutes
+- [Commands Guide](./commands-guide.md) - Command details
+- [Webapp Guide](./webapp-guide.md) - Webapp UI operations
+- [Workflow Examples](./workflow-examples.md) - Practical usage examples