Terminal Computer Use

Operate the machine through the terminal, not GUI pixel control / vision APIs. Prefer reusable scripts in this skill’s scripts/ directory; write new ones when a pattern will be reused.

Out of scope — browser automation

TCU does not automate browsers. No Playwright, no CDP, no click/fill/type/DOM, no captcha bypass, no form automation, no Medium publish.

When the user asks for browser automation, web form fill, “drive Chrome”, captcha handling, or site publishing via automation:

1. Say it is not possible with TCU (briefly: captcha/bot checks and post-auth trust scoring defeat terminal/browser automation reliably).
2. Do not install Playwright, write browser-driving scripts, or invent pixel clicks.
3. May still help with desktop-side prep:
   • draft content in files
   • put text on the clipboard (clipboard.sh)
   • open a URL in the user’s normal browser (open-target.sh) — open only, no control

Paths (portable)

Never hardcode ~/.grok or any single agent’s install path.

Resolve once per session from the loaded skill path, or:

# When running a script, paths resolve via scripts/lib/common.sh automatically.
bash "${SCRIPTS}/doctor.sh"

If you only know the install locations, try in order:

1. $TERMINAL_COMPUTER_USE_HOME
2. Path of the skill file the agent loaded
3. ~/.agents/skills/computer
4. ~/.grok/skills/computer
5. ~/.claude/skills/computer
6. ~/.cursor/skills/computer

Operating principles

1. Prefer library scripts over one-off shell when a script already covers the task.
2. Shell first; Python when parsing / multi-file logic is clearer.
3. Persist useful automation under scripts/ with --help and --dry-run when mutating.
4. Confirm before bulk delete, overwrite, or externally visible sends.
5. Absolute paths, quote spaces, never rm -rf without an explicit approved target list.
6. Idempotent when possible. Report what you did.
7. Observe only as needed for the goal. Prefer structured OS/CLI state over screenshots.

Decision tree

User request / goal
  ├─ Browser automation / form fill / captcha / site publish? → refuse (not possible in TCU)
  │     optional assist: clipboard + open-target.sh only
  ├─ Covered by scripts/* ? → run that script with flags
  ├─ Open URL in user’s normal browser (no control)? → open-target.sh
  ├─ Simple one-liner? → shell directly
  ├─ Needs OS automation (apps/Finder)? → platform-aware scripts / osascript on macOS
  ├─ Structured multi-file logic? → Python 3
  └─ Will be reused? → add script under scripts/, then run it

How to verify (cheapest sufficient signal):
  1. Structured checks — paths, processes, clipboard, dry-run plans, doctor
  2. Script/CLI that reads system state directly
  3. screenshot.sh ONLY if the goal depends on visual/UI state those cannot provide
     (never screenshot "to be safe" before file/app/clipboard work)

Terminal Computer Use wins by using the control plane (files, apps, clipboard, processes). Screenshots are an escape hatch for UI-native goals — not the default observe loop.

Running scripts

SCRIPTS="<skill-root>/scripts"
bash "${SCRIPTS}/<name>.sh" [args]
python3 "${SCRIPTS}/<name>.py" [args]

Every script supports -h / --help. Destructive scripts support --dry-run. Set TCU_SAFE_MODE=1 to force dry-run on mutators (fs-move, fs-copy, safe-trash, fs-organize).

Capability map

See references/safety.md, references/macos-cli.md, references/linux-cli.md.

Writing new scripts

1. Name: kebab-case, verb-first (.sh / .py / .rb)
2. Shebang: #!/usr/bin/env bash or #!/usr/bin/env python3
3. Bash: set -euo pipefail; source scripts/lib/common.sh
4. --help; --dry-run for mutations
5. chmod +x
6. Prefer lib/platform.sh helpers (tcu_open, tcu_notify, …) over OS-specific commands
7. Update the capability table above when adding a primary entry point
8. Do not add browser automation (Playwright/CDP/DOM drivers) — out of scope

Safety (non-negotiable)

• Do not delete $HOME, /, or empty Trash unless explicitly asked.
• Prefer safe-trash.sh over rm.
• Quit apps gracefully; avoid kill -9 unless hung + requested.
• Network/message sends need explicit user intent.
• Bulk file ops: dry-run first unless the user asked to apply immediately.
• TCU_SAFE_MODE=1 forces dry-run on mutators even if --dry-run was omitted; blocks organize --apply / --undo.
• After a bad organize: python3 "$SCRIPTS/fs-organize.py" --undo (last plan under ~/.tcu/).

Platform support

* Needs common desktop utilities (xdg-open, notify-send, wl-copy/xclip).

Example prompts

/computer open Slack and reveal ~/Downloads
/computer organize my desktop (smart categories, dry-run first)
/computer quit Spotify; notify me when done
/computer move PDFs on Desktop into ~/Documents/PDFs
/computer put this draft on the clipboard and open medium.com/new-story

Communication

Professionally concise always: lead with a short summary; use tables/commands; skip long prose. Same bar for README, handoffs, and agent replies.

After complex work

1. Leave new scripts in scripts/ with --help.
2. Name them in the final reply for future reuse.
3. Prefer safe defaults over asking micro-questions.