claudette

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-<platform> release assets are also published per release for headless / CI consumers.

Quick start

# Inspect what the GUI exposes
claudette version
claudette capabilities

# Workspace lifecycle
claudette workspace list
claudette workspace create <repo-id> my-feature
claudette workspace archive <ws-id>

# Send a prompt to a chat session (kicks off an agent turn in the GUI)
claudette chat send <session-id> "your prompt"
claudette chat send <session-id> @prompts/feature.md --model sonnet --plan

# Orchestrate a running chat session
claudette chat list <workspace-id>
claudette chat show <session-id> --limit 50
claudette chat turns <session-id>
claudette chat answer <session-id> <tool-use-id> --answers-json '{"Question?":"Answer"}'
claudette chat approve-plan <session-id> <tool-use-id>
claudette chat deny-plan <session-id> <tool-use-id> "revise the plan first"
claudette chat steer <session-id> @prompts/followup.md
claudette chat stop <session-id>

# Schedule a recurring prompt for a session
claudette routine create <session-id> "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 <shell>	Generate shell completion script

Common workflows

List and inspect workspaces

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:

claudette workspace create <repo-id> 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 <name>	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 <level>	low / medium / high / xhigh / max
--disable-1m-context / --no-disable-1m-context	Suppress / re-enable the Max-plan 1M context auto-upgrade
--permission <level>	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:

claudette chat list <workspace-id>
claudette chat show <session-id> --limit 50
claudette chat show <session-id> --limit 50 --before <message-id>

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:

claudette chat answer <session-id> <tool-use-id> --answers-json '{"Which branch?":"main"}'
claudette chat approve-plan <session-id> <tool-use-id>
claudette chat deny-plan <session-id> <tool-use-id> "Please split migration and UI work."
claudette chat clear-attention <session-id>

Other chat inspection and control commands:

Command	Behavior
claudette chat turns <session-id>	Return completed turn/tool activity for the session
claudette chat attachments <session-id>	Return attachment metadata and safe inline text snippets
claudette chat attachment-data <attachment-id>	Fetch a full attachment body explicitly
claudette chat create <workspace-id>	Create a new chat session in a workspace
claudette chat rename <session-id> <name>	Rename a session
claudette chat archive <session-id>	Archive a session
claudette chat steer <session-id> <prompt|@file|->	Steer the queued message for a running session
claudette chat stop <session-id>	Stop the live agent process
claudette chat reset <session-id>	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

claudette workspace archive <ws-id>
claudette workspace archive <ws-id> --delete-branch       # force on
claudette workspace archive <ws-id> --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):

# phase-0-cleanup.claudette.yaml
repository: <repo-id>
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

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:

claudette routine list                                              # always JSON — wakeups + routines
claudette routine create <session-id> "0 9 * * 1-5" "Check open PRs" --name weekday-prs
claudette routine create <session-id> "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 <session-id> <cron-expr> <prompt>. 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:

export CLAUDETTE_WORKSPACE_ID=<ws-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:

claudette plugin list                                       # see what's loaded
claudette plugin invoke github ci_status --workspace <ws>   # any op, any plugin
claudette plugin invoke env-direnv export --workspace <ws> '{"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):

claudette rpc list_workspaces
claudette rpc list_chat_sessions '{"workspace_id":"<ws-id>"}'
claudette rpc get_chat_snapshot '{"session_id":"<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.