--- name: claudette description: Drive the running Claudette desktop app from the command line — list and create workspaces, inspect chat transcripts/tool turns/attachments, answer or approve pending agent controls, send or steer prompts to chat sessions, schedule recurring cron-style agent routines, fan out batch manifests across many workspaces, list pull requests via SCM plugins, invoke arbitrary plugin operations. Use when the user asks to list/create/archive workspaces, inspect or control Claudette chat sessions, send a message to a Claudette session, schedule a recurring prompt or cron routine for a session, kick off a phase plan or multi-workspace fan-out, check PRs from a workspace, or otherwise interact with their open Claudette app from outside the GUI. when_to_use: | Trigger when the user mentions Claudette workspaces, sessions, chat transcripts, pending agent questions, plan approvals, completed turns, batch / phase plans, scheduled routines or wakeups, "send this prompt to N workspaces", "get feedback from the other agents", "list my workspaces", "what's running in Claudette", "create a workspace for X", "show me the PR for this workspace", "schedule a routine", "create a recurring prompt", "run this session on a cron", "list my scheduled routines", or asks to invoke a Claudette SCM/env plugin operation. Also use proactively when the user has Claudette open and asks for operations that would obviously route through it (e.g. "fan out these 8 prompts as separate Claudette workspaces"). allowed-tools: Bash(claudette:*) --- # Claudette CLI Drive the running Claudette desktop app over a per-user local socket. Every command makes one JSON-RPC call to the GUI, so the GUI's tray rebuilds, notifications, agent spawn flow, and event subscribers fire exactly as if the action came from the UI. ## Prerequisites - The Claudette desktop app must be **open and running**. Every command discovers it via `${state_dir}/Claudette/app.json`. If it isn't running, commands exit with a clear error — do not try to start the app yourself; ask the user to launch it. - The `claudette` CLI must be on `PATH`. The cleanest install path: open the desktop app and use **Settings → CLI → Install on PATH** (one click; symlinks on macOS/Linux, copies + per-user PATH update on Windows). On Linux, `.deb` installs place the CLI at `/usr/bin/claudette` automatically. Standalone `claudette-cli-` release assets are also published per release for headless / CI consumers. ## Quick start ```bash # Inspect what the GUI exposes claudette version claudette capabilities # Workspace lifecycle claudette workspace list claudette workspace create my-feature claudette workspace archive # Send a prompt to a chat session (kicks off an agent turn in the GUI) claudette chat send "your prompt" claudette chat send @prompts/feature.md --model sonnet --plan # Orchestrate a running chat session claudette chat list claudette chat show --limit 50 claudette chat turns claudette chat answer --answers-json '{"Question?":"Answer"}' claudette chat approve-plan claudette chat deny-plan "revise the plan first" claudette chat steer @prompts/followup.md claudette chat stop # Schedule a recurring prompt for a session claudette routine create "0 9 * * 1-5" "Check open PRs" --name weekday-prs claudette routine list ``` ## Top-level commands | Command | Purpose | |---|---| | `version` | Print app + protocol version of the running GUI; warns on CLI/GUI version mismatch | | `capabilities` | List the JSON-RPC methods the GUI accepts | | `workspace` (alias `ws`) | List / create / archive workspaces | | `chat` | List, inspect, send, steer, and control chat sessions | | `repo` | List repositories registered with the GUI | | `batch` | Run / validate a batch manifest (multi-workspace fan-out) | | `plugin` | List loaded plugins, invoke any operation directly | | `pr` | Friendly shortcut over the active SCM provider plugin | | `routine` | Schedule / list / run / delete cron-style recurring prompts that fire through a chat session | | `rpc` | Raw JSON-RPC escape hatch for methods without a typed wrapper | | `completion ` | Generate shell completion script | ## Common workflows ### List and inspect workspaces ```bash claudette workspace list claudette workspace list --json | jq '.[] | {id, name, branch_name, status}' ``` The first column is the workspace ID — pass it to `archive`, `chat list`, `pr list --workspace …`, etc. ### Create a workspace and send the first prompt `workspace create` returns the workspace plus a `default_session_id`. The session id is what `chat send` targets: ```bash claudette workspace create phase-0-builtins --json \ | jq -r '.default_session_id' \ | xargs -I {} claudette chat send {} @prompts/43-builtins.md --model sonnet --plan ``` ### Send a prompt — three input modes | Form | Behavior | |---|---| | `claudette chat send SID "literal prompt"` | Use the string verbatim | | `claudette chat send SID @path/to/file.md` | Read the prompt from a file (most common for batch use) | | `claudette chat send SID -` | Read the prompt from stdin (pipe-friendly) | Per-turn agent settings (each boolean is tri-state — pass `--flag` to force on, `--no-flag` to force off, omit both to defer to the backend default of `false`): | Flag | Effect | |---|---| | `--model ` | Model override (e.g. `opus`, `sonnet`) | | `--plan` / `--no-plan` | Plan mode on/off | | `--thinking` / `--no-thinking` | Extended thinking | | `--fast` / `--no-fast` | Lower-latency variant when supported | | `--chrome` / `--no-chrome` | Chrome browser mode | | `--effort ` | `low` / `medium` / `high` / `xhigh` / `max` | | `--disable-1m-context` / `--no-disable-1m-context` | Suppress / re-enable the Max-plan 1M context auto-upgrade | | `--permission ` | `default` / `acceptEdits` / `bypassPermissions` | ### Inspect and orchestrate chat sessions Use `chat show` as the primary orchestration read. It returns one bounded JSON snapshot with hydrated session metadata, recent messages, metadata-safe attachments, completed tool activity, live pending controls, and pagination fields: ```bash claudette chat list claudette chat show --limit 50 claudette chat show --limit 50 --before ``` `pending_controls` contains live agent controls such as `ask_user_question` and `exit_plan_mode`. Use the `tool_use_id` from that array to answer questions or approve/deny a plan: ```bash claudette chat answer --answers-json '{"Which branch?":"main"}' claudette chat approve-plan claudette chat deny-plan "Please split migration and UI work." claudette chat clear-attention ``` Other chat inspection and control commands: | Command | Behavior | |---|---| | `claudette chat turns ` | Return completed turn/tool activity for the session | | `claudette chat attachments ` | Return attachment metadata and safe inline text snippets | | `claudette chat attachment-data ` | Fetch a full attachment body explicitly | | `claudette chat create ` | Create a new chat session in a workspace | | `claudette chat rename ` | Rename a session | | `claudette chat archive ` | Archive a session | | `claudette chat steer ` | Steer the queued message for a running session | | `claudette chat stop ` | Stop the live agent process | | `claudette chat reset ` | Reset the live agent session | Snapshots and attachment lists intentionally omit large base64 bodies so they stay under the IPC response cap. Fetch full bodies only with `attachment-data`. ### Archive a workspace ```bash claudette workspace archive claudette workspace archive --delete-branch # force on claudette workspace archive --no-delete-branch # force off ``` `--delete-branch` is tri-state: omit both halves to defer to the GUI's `git_delete_branch_on_archive` setting; pass either half to override per-call. ### Fan out N workspaces from a YAML manifest Write a manifest, validate it, run it, watch the sidebar fill in. Workspaces are processed sequentially today (concurrent execution is a follow-up): ```yaml # phase-0-cleanup.claudette.yaml repository: defaults: model: sonnet workspaces: - name: builtins-tsx prompt_file: ./prompts/43-builtins.md - name: shell-rs prompt_file: ./prompts/42-shell.md model: opus - name: app-tsx prompt_file: ./prompts/38-app.md ``` ```bash claudette batch validate phase-0-cleanup.claudette.yaml # lint without executing claudette batch run phase-0-cleanup.claudette.yaml ``` `prompt_file` paths resolve relative to the manifest. Validation also enforces workspace-name rules (ASCII alphanumeric + hyphens, no leading/trailing hyphen) so naming bugs surface up front. ### Scheduled routines `routine` schedules cron-style prompts that fire through a chat session — the CLI surface for Claudette's native agent scheduling. A routine targets a session id and re-runs a prompt on a standard 5-field cron expression evaluated in local time: ```bash claudette routine list # always JSON — wakeups + routines claudette routine create "0 9 * * 1-5" "Check open PRs" --name weekday-prs claudette routine create "30 14 28 2 *" @prompts/review.md --once claudette routine run weekday-prs # fire now, by id or name claudette routine delete weekday-prs # delete, by id or name ``` - `create` takes ` `. The prompt accepts the same three forms as `chat send`: a literal string, `@path/to/file.md`, or `-` to read from stdin. - `--name` assigns a stable handle so `run` / `delete` can address the routine without its generated id. - `--once` fires a single time at the next matching slot, then disables the routine; omit it for a recurring schedule. - `routine list` always emits JSON (ad-hoc wakeups plus recurring routines), regardless of `--json`. `create` / `run` / `delete` print a short confirmation line by default and full JSON with `--json`. ### Pull requests for the current workspace `pr` resolves the active SCM provider per workspace via the GUI's plugin registry. Set `CLAUDETTE_WORKSPACE_ID` in the shell or pass `--workspace`: ```bash export CLAUDETTE_WORKSPACE_ID= claudette pr list # PRs for this workspace's branch claudette pr list --all # every open PR in the repo claudette pr show 123 # one PR by number claudette pr list --json | jq . ``` If no SCM plugin matches the repository (plugin disabled, required CLI missing, or unrecognized remote host), the command exits with a helpful error pointing to `claudette plugin list`. ### Generic plugin invocation Skip the friendly wrappers and call any plugin operation directly: ```bash claudette plugin list # see what's loaded claudette plugin invoke github ci_status --workspace # any op, any plugin claudette plugin invoke env-direnv export --workspace '{"path":"/abs/worktree"}' ``` Workspace context is required because plugin operations resolve paths relative to a worktree. `--workspace` defaults to `$CLAUDETTE_WORKSPACE_ID`. ### Raw JSON-RPC For methods that don't have a typed subcommand yet (or for debugging): ```bash claudette rpc list_workspaces claudette rpc list_chat_sessions '{"workspace_id":""}' claudette rpc get_chat_snapshot '{"session_id":"","limit":50}' ``` `claudette capabilities` prints every method the running GUI accepts. ## Implicit context These environment variables are auto-honored: | Env var | Effect | |---|---| | `CLAUDETTE_WORKSPACE_ID` | Default for `--workspace` flag on `pr` and `plugin invoke` | Inside a Claudette workspace shell these are already set, so `claudette pr list` "just works." ## Errors and edge cases - **"Claudette desktop app is not running"** — the GUI must be open. Ask the user to launch it. - **"unauthorized" / connection refused** — discovery file present but socket dead; the user likely killed the GUI without a clean shutdown. Ask them to relaunch. - **`PluginError: NeedsReconsent` / `CliNotFound`** — surfaced verbatim from the GUI's `PluginRegistry`. Resolve in the GUI's Plugins settings, then retry. - **`workspace create` fails with branch-name conflict** — pass a different `name` arg; Claudette derives the branch from it. - **CLI/GUI version mismatch warning** — `claudette version` reports both. Reinstall the bundled CLI from Settings → CLI to bring them back in sync; the IPC layer is version-aware so commands keep working but new methods may be missing. ## Output conventions - Commands with a human-readable renderer (`workspace list`, `repo list`, `pr list`, `plugin list`) default to a table-ish format and switch to JSON when `--json` is set. - Other commands always emit JSON regardless of `--json` because they don't have a table renderer yet (`capabilities`, `rpc`, `chat list`, `chat show`, chat control commands, `pr show`, `routine list`, `workspace create` / `archive`, `batch run` summary). `routine create` / `run` / `delete` instead print a short plain-text confirmation by default and switch to JSON with `--json`. - Pipe `--json` output through `jq` for scripting. ## When to NOT use this skill - For Claudette **development** debugging (state inspection, monitor logs, screenshots) — use the `claudette-debug` skill instead. It targets the dev-build TCP debug server, not the IPC socket. - For starting / stopping the Claudette app — the CLI requires the GUI to already be running. - When the user clearly wants a GUI action (e.g. "click this button") — describe the GUI flow rather than substituting CLI operations that may not match.