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); 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
   

   Copy
   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.

Routing

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

1. Target route — what are you driving?

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.

3. Artifact route — does compose need polish tools?

Only relevant when compose is loaded.

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.

Do not synthesize a "before" state to justify side-by-side. If there is no real baseline, use single.

Delegation

Keep short interactive desktop tasks in the parent: it owns observations, input, user permission waits, and cleanup. Delegate independent capture environments or rendering, not individual screenshots interleaved with another controller's input.

What to delegate

How to delegate

Step 0: Resolve paths and generate a run ID. Workers don't inherit ${DROID_PLUGIN_ROOT}. Resolve once, paste everywhere:

TCTL="$(realpath "${DROID_PLUGIN_ROOT}/bin/tctl")"
RENDER="$(realpath "${DROID_PLUGIN_ROOT}/scripts/render-showcase.sh")"
RUN_ID="$(date +%s)-$$"
RUN_DIR="$(mktemp -d /tmp/droid-run-${RUN_ID}-XXXXXX)"

Use ${RUN_DIR} for all output files (recordings, props, rendered video). Use ${RUN_ID}- as a prefix for all session names. Never use bare names like -s before or hardcoded paths like /tmp/before.cast.

Give workers exact commands with the resolved absolute paths — not abstract instructions, not tuistory, not ${DROID_PLUGIN_ROOT}. The parent does the thinking; the worker executes:

Task prompt for a capture worker:
  "Run these commands in order. Report the output file path and any errors.
   1. /abs/path/to/bin/tctl launch "droid-dev" -s 1712345678-42-before --backend tuistory \
        --repo-root /abs/path/to/baseline/worktree \
        --cols 120 --rows 36 --record /tmp/droid-run-1712345678-42-xxxx/before.cast \
        --env FORCE_COLOR=3 --env COLORTERM=truecolor
   2. /abs/path/to/bin/tctl -s 1712345678-42-before wait ">" --timeout 15000
   3. /abs/path/to/bin/tctl -s 1712345678-42-before type "hello world"
   4. /abs/path/to/bin/tctl -s 1712345678-42-before press enter
   5. /abs/path/to/bin/tctl -s 1712345678-42-before wait-idle
   6. /abs/path/to/bin/tctl -s 1712345678-42-before close"

Task prompt for a render worker:
  "Run this command. Report the output file path and any errors.
   /abs/path/to/scripts/render-showcase.sh \
     --props /tmp/droid-run-1712345678-42-xxxx/showcase-props.json \
     --output /tmp/droid-run-1712345678-42-xxxx/demo.mp4 \
     /tmp/droid-run-1712345678-42-xxxx/before.cast /tmp/droid-run-1712345678-42-xxxx/after.cast"

Parallel capture pattern (comparison flows only)

Only applicable when the Layout default table selects side-by-side and the capture environments are independent. Serialize shared-desktop captures. For a single interactive desktop task, keep control in the parent.

For before/after comparison demos, launch both capture workers simultaneously:

1. Parent constructs the interaction script (identical for both branches)
2. Launch worker A: capture the baseline/reference branch with `--repo-root` set to that worktree
3. Launch worker B: capture the candidate/change branch with `--repo-root` set to that worktree
4. Wait for both to complete (TaskOutput)
5. Collect .cast paths from results
6. Continue to compose

Shared tooling

Terminal drivers use the unified tctl wrapper. Browser-use and desktop-use have their own CLIs (agent-browser, cua-driver) and do not use tctl.

Drivers can be combined in one workflow — e.g., tctl for a CLI and agent-browser for a web UI it interacts with.

Degraded-tail repro recipe (droid TUI)

Deterministic recipe for reproducing degraded transcript tails in the droid CLI — stranded live tool rows and queued steering messages — without waiting for a slow model turn. The trick: a slow PreToolUse hook pins a tool in its executing state for as long as you need.

1. Scratch project. Create a throwaway directory (never a real repo — the hook fires on every matching tool call) with a project-local hook that sleeps:

   SCRATCH="$(mktemp -d /tmp/degraded-tail-XXXXXX)"
   mkdir -p "$SCRATCH/.factory"
   cat > "$SCRATCH/.factory/settings.json" <<'JSON'
   {
     "hooks": {
       "PreToolUse": [
         {
           "matcher": "TodoWrite",
           "hooks": [{ "type": "command", "command": "sleep 120" }]
         }
       ]
     }
   }
   JSON
   

   Copy

   Pick a sleep long enough to interact mid-hook (60–180s) and a matcher for a tool the prompt will reliably trigger (TodoWrite fires on any multi-step ask).

2. Launch with --cwd pointed at the scratch project — --repo-root stays on your dev worktree so droid-dev provenance still records the code under test:

   $TCTL launch "droid-dev" -s ${RUN_ID}-tail --cwd "$SCRATCH" \
     --repo-root /abs/path/to/dev/worktree --record ${RUN_DIR}/tail.cast
   

   Copy

3. Trigger the hook, then degrade the tail while the tool row shows executing:

   • Interrupt mid-hook (press escape) — strands the live tool row: it never resolves to a completed/canceled state in the transcript tail.
   • Steer mid-hook (type "..." + press enter) — the steering message queues behind the executing tool instead of interleaving.

Gotcha: dev-scope hook settings can silently disable project hooks. If the tool completes instantly, run /hooks in the session and check the "Hooks enabled" toggle before debugging the hook config itself.

Prerequisites

Install commands

# tuistory driver + recording
npm install -g tuistory                              # virtual PTY driver
pip install asciinema                                # terminal recording (tctl wraps this)
cargo install --git https://github.com/asciinema/agg  # .cast -> .gif converter (compose needs this)

# true-input driver (Linux/Wayland)
sudo apt-get install -y cage wtype                   # required: headless compositor + keystroke injection
sudo apt-get install -y grim wf-recorder             # optional: screenshots + video recording

# agent-browser driver
agent-browser install                                # one-time: downloads bundled Chromium

# desktop-use: follow its setup instructions only if the binary
# is missing and installation is approved. No separate skill install.

# compose + showcase (video rendering)
sudo apt-get install -y ffmpeg                       # video processing (includes ffprobe)
sudo apt-get install -y clang libclang-dev libx264-dev  # renderer build deps (macOS: xcode-select --install; brew install x264)
cargo build --release --manifest-path ${DROID_PLUGIN_ROOT}/fframes/Cargo.toml  # renderer (render-showcase.sh also builds on first use)