workstation

name	workstation
version	1.0.0
description	Control Varie Workstation sessions (Claude Code multi-session orchestration). Use when: (1) user wants to work on / start / resume a coding project, (2) checking session status, (3) sending commands to a session, (4) listing active sessions, (5) creating new sessions, (6) user replies to a plan approval or question notification, (7) user wants to stop/cancel/interrupt a session, (8) user wants a screenshot of a session or screen. Triggers on: work on, start, resume, sessions, workers, workstation, dispatch, project name, approve, reject, option, pick, yes, no, stop, cancel, interrupt, escape, kill, stuck, screenshot, show me, capture, what does it look like.
homepage	https://github.com/varie-ai/workstation
metadata	{"openclaw":{"emoji":"🖥️","requires":{"bins":["wctl"]}}}

Workstation Control

Control Varie Workstation coding sessions via wctl.

Step 0: Check Pending Prompts (ALWAYS DO THIS FIRST)

Before ANY routing or session work, check if a session is waiting for user input:

cat ~/.openclaw/workspace/pending-prompts.json 2>/dev/null || echo '{"prompts":[]}'

If prompts array is non-empty AND the user's message looks like a response (a number, "approve", "yes", "no", "reject", short answer, or references a project in the pending list): → This is a reply to a pending prompt. Go directly to "Responding to Session Prompts" section below.

If prompts array is empty OR user's message is clearly a new request (mentions a different project, asks to start/create something, etc.): → Continue to Smart Routing below.

Smart Routing (Main Workflow)

When the user mentions working on a project (e.g., "work on my-api", "resume frontend work", "start auth refactor"), follow this decision tree silently — do NOT ask the user unless you hit an ambiguous case:

Step 1: Check daemon + list sessions

wctl list

(If daemon not running, tell user to start the Workstation app.)

Step 2: Match project

Look at the repo field in each worker. Match the user's project mention against repo names (fuzzy — "frontend" matches "my-frontend-app", "api" matches "backend-api-service").

If session exists and task context aligns (user's request fits the current taskId/workContext): → wctl dispatch <session-id> "<user's message>"

If session exists but task context doesn't align (user wants to work on something different in the same repo): → Ask: "There's already a session for {repo} working on {taskId}. Should I send this to that session, or create a fresh one?"

If no session exists for the project: → Go to Step 3.

If multiple repos match (e.g., "api" could be frontend-api or backend-api): → Ask which one.

Step 3: Auto-create session (no matching session found)

wctl discover

Find the project path from the discovered list, then:

wctl create <repo> <path> <task-id>

Derive task-id from the user's message (e.g., "work on auth refactor" → task-id: auth-refactor). Keep it short, lowercase, hyphenated.

After creation, confirm: "Started new session for {repo} ({task-id})."

If project not found in discover results, ask the user for the repo path.

Commands Reference

Command	Use
wctl status --human	Check daemon alive
wctl list	List sessions (JSON, for parsing)
wctl list --human	List sessions (readable, for user)
wctl dispatch <id> "<msg>"	Send message to existing session
wctl dispatch-answers <id> <a1> <a2>...	Send multi-question answers. Use next:N for multi-select
wctl create <repo> <path> [task]	Create new session (auto-registers in project index)
wctl escape <id>	Send Escape key (cancel prompt/menu)
wctl interrupt <id>	Send Ctrl+C (stop running process)
wctl enter <id>	Send Enter key (confirm/dismiss)
wctl screenshot <id> [--pages N]	Screenshot a session. --pages N captures N pages of scrollback (max 10)
wctl screenshot --screen	Screenshot main display
wctl set-remote-mode on|off	Enable/disable remote mode (bridge auto-focus for screenshots)
wctl discover	Scan for project repos

Creating New Projects

To start a brand new project that doesn't exist yet:

wctl create <project-name> ~/workplace/projects/<project-name> [task-label]
# Example: wctl create experiment_testing ~/workplace/projects/experiment_testing initial-exploration

The optional task-label is a short description shown in wctl list (e.g. "initial-exploration", "build-api", "fix-bug"). If omitted, the session shows no task label.

This will:

1. Create the directory if it doesn't exist
2. Start a new Claude Code session in that directory
3. Auto-register the project in the Workstation project index

Default path convention: ~/workplace/projects/<project-name>

When to use: User says "start a new project", "create an experiment", "I want to try something new", or names a project that doesn't exist in wctl list.

Session Control (Escape / Interrupt)

When the user wants to stop, cancel, or interrupt a session:

User says	Command
"stop session X", "cancel", "kill it", "abort"	wctl interrupt <id> (sends Ctrl+C)
"escape", "go back", "cancel prompt", "dismiss"	wctl escape <id> (sends Escape key)
"press enter", "confirm", "continue", "submit"	wctl enter <id> (sends Enter key)

Strategy: If unsure, try escape first (safe — cancels UI prompts). If still stuck, use interrupt (harder — sends SIGINT).

Screenshots

To show the user what a session looks like:

# 1. Capture the session (current viewport)
wctl screenshot <session-id>
# Returns: { "status": "ok", "imagePath": "/path/to/screenshot.png" }

# Capture multiple pages of scrollback (e.g., 3 pages of history)
wctl screenshot <session-id> --pages 3
# Returns plain text with one path per line:
#   Screenshot captured 3 pages:
#   Page 1/3: /path/to/page1.png
#   Page 2/3: /path/to/page2.png
#   Page 3/3: /path/to/page3.png

# 2. Send EACH image path to the user (one message per page)

--pages N captures N pages starting from the oldest visible content down to the current viewport. Use --pages 2 or --pages 3 when the user wants to see more output that scrolled past.

To deliver screenshots, use your built-in message tool with action: "send" and mediaUrl set to the image file path. This sends the actual image, not the path text.

IMPORTANT — multi-page delivery: Each page has a DIFFERENT image path. You MUST call the message tool once per page with mediaUrl set to that page's path. Never send paths as text — always use mediaUrl so the user receives the actual image.

Example for 2 pages:

1. wctl output: Page 1/2: /path/page1.png → message tool: { "action": "send", "mediaUrl": "/path/page1.png" }
2. wctl output: Page 2/2: /path/page2.png → message tool: { "action": "send", "mediaUrl": "/path/page2.png" }

If the message tool is unavailable, fall back to the CLI (one command per page):

openclaw message send --media /path/page1.png
openclaw message send --media /path/page2.png

For full screen (e.g., to see Chrome, other apps): wctl screenshot --screen

When to use: User says "show me", "screenshot", "what does it look like", "what's happening in session X". Use --pages when user says "show me the full output", "scroll up", or wants to see more than the current view.

Always send the image via openclaw message send --media after capturing — wctl only saves the file locally.

Critical Rules

1. dispatch for existing sessions — always. It types directly into the terminal. Never use wctl route (it may restart Claude and disrupt work).
2. Never prepend claude to messages — just pass the user's message as-is to dispatch.
3. Add --human when showing output to user — JSON otherwise for your own parsing.
4. Ask when unsure — if you can't confidently match the user's message to exactly one session/project, ask to confirm. Wrong dispatches disrupt real coding work. Autonomy is good, but correctness matters more.
5. Never guess or hallucinate — don't invent project names, session IDs, or options. Always check wctl list and pending-prompts.json for ground truth.
6. Use "Chat about this" as fallback — if you can't confidently map the user's answer to option numbers for a multi-question prompt, use --chat-arrows 20 to select "Chat about this" and then dispatch their message as text. A stuck question modal is worse than falling back to chat.

Responding to Session Prompts

When Step 0 finds pending prompts and the user's message is a response:

Step 1: Identify the target session

The pending prompt has a project field. Use it to find the session:

wctl list

Find the session whose repo matches the pending prompt's project. Use its sessionId.

If multiple prompts are pending, match the user's message to the most relevant one (by project name mention or most recent).

Step 2: Map intent to response

Plan approval — ALWAYS dispatch the OPTION NUMBER, never free text:

The plan approval prompt is a numbered menu in Claude Code. Free text will be misinterpreted as the "Other" option and may APPROVE the plan instead of rejecting it.

User says	Dispatch
"1", "clear context", "bypass all"	wctl dispatch <id> "1"
"2", "bypass permissions", "yes bypass"	wctl dispatch <id> "2"
"3", "approve", "yes", "go ahead", "lgtm", "manually approve"	wctl dispatch <id> "3"
"reject", "no", "don't do that", any rejection	wctl dispatch <id> "4" then optionally send feedback (see below)

Default to option 3 ("yes, manually approve edits") when user says generic approval like "yes", "approve", "go ahead".

CRITICAL for option 4 (reject/feedback): This is a two-step process. You MUST dispatch "4" first (the number only), wait for the text prompt to appear, then dispatch their feedback. Never combine rejection + feedback into a single dispatch — the PTY is a numbered menu, not a text field.

wctl dispatch abc123 "4"
sleep 2
wctl dispatch abc123 "don't modify the database schema"

If the user just says "reject" or "no" with no specific feedback, dispatch "4" only — no second step needed.

Question — ALWAYS dispatch the OPTION NUMBER, never text:

Look up the user's answer in the pending prompt's questions array and find the matching option number. Example: if options are ["1. Night", "2. Day", "3. Morning"] and user says "night", dispatch "1" (not "night").

User says	Action
A number ("1", "2")	Dispatch that number directly
A word matching an option label ("night", "dog")	Find the option number and dispatch the NUMBER
Free text not matching any option	Dispatch the text (for "Other" option)

Single question: Use regular dispatch: wctl dispatch <id> "2"

Multiple questions: Use dispatch-answers — it sends each answer without Enter (Claude auto-advances on single-select), then sends Enter at the end to submit. Map EACH answer to its option NUMBER, then pass them all in one command:

wctl dispatch-answers <id> 2 1 3

This sends: "2" → wait → "1" → wait → "3" → wait → Enter (submit). No chaining or sleep needed — timing is handled internally.

Multi-select questions (checkboxes — check the multiSelect field in pending-prompts.json): Typing a number toggles it on/off but does NOT advance (cursor stays at position 1). After selecting all options, use next:N to arrow-down N times to the "Next"/"Submit" button and press Enter. N = the number of options for that question (including "Other"), from questions[i].options.length.

wctl dispatch-answers <id> 1 2 next:5 2

This sends: "1" (toggle) → "2" (toggle) → arrow-down×5 to "Next" → Enter → "2" (next question, single-select) → Enter (submit all).

Example with 4 questions (multi/5opts, single, single, multi/5opts):

wctl dispatch-answers <id> 1 4 next:5 2 1 1 3 next:5

Each next:N is self-contained — N is always questions[i].options.length for that specific multi-select question.

How to tell if a question is multi-select: The pending prompt's questions array has a multiSelect field per question. If multiSelect: true, you MUST add next:N after their selections. If multiSelect: false (or missing), it's single-select and auto-advances — no next needed.

If the last question is multi-select, use next:N as the last token — it will click "Submit" instead of "Next" (same button position). The final Enter to confirm all answers is sent automatically after all tokens.

"Chat about this" — at the very bottom of the question modal (below all options and Next/Submit), there's a "Chat about this" option. Arrow keys do NOT wrap/circulate, so you can safely overshoot. Use --chat-arrows N to select it. Calculate N based on the first question only:

• First question is multi-select with K options (incl. Other): --chat-arrows K+1 (extra arrow for Next button)
• First question is single-select with K options (incl. Other): --chat-arrows K

# Example: first question is multi-select with 5 options → 6 arrows
wctl dispatch-answers <id> --chat-arrows 6
# Example: first question is single-select with 3 options → 3 arrows
wctl dispatch-answers <id> --chat-arrows 3

When using --chat-arrows, no answer tokens are needed — it replaces the entire answer flow.

FALLBACK RULE: If you are unsure how to map the user's answers to option numbers, or the user's message is vague/unclear, always use --chat-arrows instead of guessing. This lets the user follow up with a simple text prompt rather than getting stuck on a broken selection. Since arrows don't wrap, you can safely use --chat-arrows 20 if unsure about the exact count — it will land on "Chat about this" regardless.

After selecting "Chat about this", immediately dispatch the user's message as a follow-up:

wctl dispatch-answers <id> --chat-arrows 20
sleep 3
wctl dispatch <id> "<user's original message>"

Step 3: Confirm

After dispatching, tell the user: "Sent response to {project}."

Errors

• daemon not running → tell user to start Workstation app
• session not found → wctl list to show valid IDs
• project not in discover → ask user for repo path
• timeout → session busy, retry shortly

Quick Start

Install

1. Install the Varie Workstation Electron app (macOS arm64).
2. Install wctl (the CLI that bridges OpenClaw to Workstation):

   # wctl ships with Workstation — symlink it to your PATH:
   ln -sf /path/to/varie-workstation/openclaw/wctl.js ~/.local/bin/wctl
   chmod +x ~/.local/bin/wctl
   

3. Copy this skill to your OpenClaw workspace:

   cp -r workstation ~/.openclaw/workspace/skills/workstation
   

Configure

• Launch the Workstation app and verify it's running: wctl status
• Enable remote mode for mobile screenshot support: wctl set-remote-mode on
• The OpenClaw-Workstation bridge (bundled in the app) writes pending prompts to ~/.openclaw/workspace/pending-prompts.json — this enables bidirectional question/approval flows from your phone.

Verify

wctl status --human    # Should show "Workstation is running"
wctl list --human      # Should list active sessions (if any)

Prerequisites

This skill requires the Varie Workstation app — an Electron-based multi-session Claude Code orchestration environment. The skill is the mobile control layer: it lets you manage Workstation sessions from Telegram, WhatsApp, or any OpenClaw channel.

Dependency	What it does	Required?
Varie Workstation	Electron app hosting Claude Code terminals	Yes
wctl CLI	Bridges OpenClaw commands to Workstation's Unix socket	Yes (ships with Workstation)
OpenClaw-Workstation bridge	Forwards session events (questions, approvals) to OpenClaw for mobile notifications	Yes (bundled in Workstation)

Without Workstation running, the skill will report "daemon not running" for all commands.

Security & Guardrails

Permissions

• wctl communicates with Workstation via a local Unix socket (/tmp/varie-workstation.sock). No network calls — all traffic is local.
• Screenshot capture requires macOS Screen Recording permission for the Workstation app.

Declared File Access

• ~/.openclaw/workspace/pending-prompts.json (read-only) — This file is read on every invocation (Step 0) to check if any Claude Code session is waiting for user input. It is written by the OpenClaw-Workstation bridge, not by this skill. Contents: question text, option labels, and project identifiers from active sessions. No credentials, secrets, or user data. The file may not exist until the bridge creates it — the skill handles this gracefully with a fallback empty response.

Screenshots

• Session screenshots (wctl screenshot <id>) capture only the specific Workstation terminal window for the targeted session.
• Full-screen screenshots (wctl screenshot --screen) capture the entire display, which may include unrelated windows and sensitive content. This command is only executed when the user explicitly requests a full-screen capture (e.g., "screenshot my screen", "show me everything").
• Screenshots are saved locally to ~/.openclaw/media/ with a 30-minute TTL cleanup.
• Screenshots are sent only to the user's own messaging channel (Telegram/WhatsApp) — never to third parties or external services.

Confirmations Before Risky Actions

• The skill asks for confirmation before creating new sessions or when multiple repos match ambiguously.
• wctl interrupt (Ctrl+C) is reserved for explicit user requests — the skill never sends it autonomously.

Data Handling

• openclaw message send routes media through your configured OpenClaw channel (Telegram/WhatsApp). Images traverse the channel provider's servers but are only sent to the requesting user's conversation.

Input Validation

• The skill maps user intent to option numbers before dispatching — plan approvals and questions MUST use the option number (1-4), never descriptive text like "reject: reason" which gets misinterpreted as "Other" input.
• The "Chat about this" fallback is used whenever intent mapping is uncertain, preventing wrong selections.

External Endpoints

Endpoint	Protocol	Data Sent
/tmp/varie-workstation.sock	Unix socket (local)	Session commands (list, dispatch, create, screenshot)
~/.openclaw/workspace/pending-prompts.json	Local file read	None (read-only)
openclaw message send --channel --target	OpenClaw channel (Telegram/WhatsApp)	Screenshot images (when user requests)

No external APIs are called directly by this skill. All network communication goes through OpenClaw's channel layer.

Trust Statement

This skill controls local Claude Code sessions running inside the Varie Workstation app. All communication is via local Unix socket — no data leaves your machine unless you request a screenshot, which is sent through your configured OpenClaw messaging channel. Only install if you trust the Varie Workstation app and your OpenClaw channel configuration.

Publisher

@masqueradeljb

Links

• Varie Workstation — The Electron app this skill controls
• OpenClaw — The AI agent gateway this skill runs on