/droid-control

name: droid-control
description: Control terminal TUIs, browsers, and native desktop apps for testing, demos, QA, and computer-use tasks. Use when you need to operate an app, automate a CLI, record a demo, or capture proof.

Droid Control

Automate terminals, browsers, and desktop apps. Route by the user's requested method first, then load only the mechanics and evidence stages needed.

Ground rules

1. **Real apps, real environments.** Non-deterministic behavior (LLM responses, network latency, variable output) is expected. Handle it with `wait` / `wait-idle`. Never substitute fixtures or mocked data. 2. **Recover from evidence.** After a failed or uncertain action, observe current state before retrying. Honor method constraints and permission boundaries; a refusal does not authorize another driver or broader target. 3. **Atoms are files, not skills.** Read each routed atom with the Read tool at `${DROID_PLUGIN_ROOT}/skills/droid-control/atoms/<atom>/ATOM.md` (index under [Atoms](#atoms)); the Skill tool cannot load them. A bold atom name in this plugin's commands and atoms means that file. Atoms link their own references with paths relative to the atom file; read them on demand. Atom files are not expanded, so wherever one writes the DROID_PLUGIN_ROOT variable, substitute this plugin root: `${DROID_PLUGIN_ROOT}` (quote it in shell commands). Desktop-use does not require a separately installed cua skill. 4. **`tctl` owns recorded terminal sessions.** It wraps `asciinema rec` around the PTY; browser and desktop drivers own their separate lifecycles. Never call `tuistory launch` directly. Resolve `TCTL` to an absolute path only for terminal workflows or worker handoffs. 5. **Isolate every run.** Multiple droids may be filming simultaneously on the same machine. Session names and output paths share a global namespace (`/tmp/tctl-sessions/`). At the start of every workflow, generate a run ID (`RUN_ID=$(date +%s)-$$` or similar) and use it as a prefix for all session names and a scoped temp directory for all output files:

   RUN_ID="$(date +%s)-$$"
   RUN_DIR="$(mktemp -d /tmp/droid-run-${RUN_ID}-XXXXXX)"
   # Session names: -s ${RUN_ID}-before, -s ${RUN_ID}-after
   # Output paths: ${RUN_DIR}/before.cast, ${RUN_DIR}/after.cast

Never use bare session names like `-s demo`, `-s before`, `-s after` — they will collide with concurrent runs. Separate names and paths do not isolate shared desktop focus or keyboard input. Keep one controller for a visible desktop.

Atoms

Each atom lives at `${DROID_PLUGIN_ROOT}/skills/droid-control/atoms/<atom>/ATOM.md`.

| Atom | Scope | |---|---| | **terminal-use** | Terminal TUI driver: tuistory virtual PTY by default, true-input for real terminal proof | | **true-input** | Real terminal emulator driver via a headless Wayland compositor or VM | | **browser-use** | Web page and Electron app driver via agent-browser | | **desktop-use** | Native GUI app driver via trycua cua-driver | | **droid-cli** | Droid CLI target patterns, shortcuts, modes, and launch helpers | | **pty-capture** | Ground-truth byte sequences from real terminal emulators | | **capture** | Recording lifecycle for terminal and browser sessions | | **compose** | Video assembly via the fframes renderer: title cards, layout, transitions, effects, and showcase polish | | **verify** | Deliverable verification against commitments | | **showcase** | Visual polish: window chrome, animations, and branded backgrounds |

Routing

Three independent lookups. Do all three, then read the union of atoms they produce.

1. Target route — what are you driving?

| Target | Read these atoms | |---|---| | User explicitly requests cua-only, native GUI input, or desktop control (including Electron) | **desktop-use**; method constraints override the defaults below | | Droid CLI (`droid-dev`, `droid exec`) | **terminal-use** + **droid-cli** | | Other terminal TUI | **terminal-use** | | Web page or Electron app | **browser-use** | | Native desktop GUI app | **desktop-use** | | Raw terminal byte sequences | **terminal-use** + **pty-capture** |

**terminal-use** selects the terminal backend behind `${DROID_PLUGIN_ROOT}/bin/tctl`: `tuistory` by default, and it loads **true-input** when real terminal rendering or keyboard-encoding evidence is needed. Desktop-use includes compositor-specific guidance; inspect live Cua capabilities rather than assuming all Linux targets are X11-only or abandoning the user's chosen method.

2. Stage route — what does the workflow need?

Every workflow passes through stages. Load the atoms for each stage you'll use.

| Stage | Atom | When to read | |---|---|---| | Capture | **capture** | Recording, scripted multi-step evidence, or a demo/QA deliverable; ordinary desktop operation uses the driver's observe/verify loop | | Compose | **compose** | When the deliverable is a produced artifact (video, annotated screenshots, comparison image) | | Verify | **verify** | Formal proof, demo, or QA deliverable; every action still needs verification even without this stage |

3. Artifact route — does compose need polish tools?

Only relevant when **compose** is loaded.

| Artifact need | Also load | |---|---| | Showcase polish (window chrome, branded frame, cinematic background) | **showcase** | | Effects and keystroke overlays | (compose handles this — they're fields in the Showcase props JSON) |

Workflow shape

Command (intent + commitments)
  → Target route (load driver atoms)
  → Capture (record / screenshot / byte-capture)
  → Compose (assemble deliverable, if needed)
  → Verify (check against commitments)
  → Report

Commands declare **what** to produce. Atoms own **how**.

Layout default

**Default: `single`.** One clip showing the target/final state. Pick this unless the deliverable is fundamentally a comparison.

| Case | Layout | |---|---| | Brand-new feature (no meaningful prior state) | `single` | | Bug fix, single-clip proof o