Computer

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.

Paths (portable)

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

| Variable | Meaning | |----------|---------| | SKILL_ROOT | Directory containing this SKILL.md (wherever the skill was installed) | | SCRIPTS | ${SKILL_ROOT}/scripts | | TERMINAL_COMPUTER_USE_HOME | Optional env override for SKILL_ROOT |

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.

Decision tree

User request
  ├─ Covered by scripts/* ? → run that script with flags
  ├─ 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

Running scripts

SCRIPTS="/scripts"
bash "${SCRIPTS}/.sh" [args]
python3 "${SCRIPTS}/.py" [args]

Every script supports -h / --help. Destructive scripts support --dry-run. Set TCU_SAFE_MODE=1 to prefer dry-run behavior for mutating flows.

Capability map

| Need | Script | |------|--------| | Health check | scripts/doctor.sh | | Tool inventory | scripts/which-tools.sh | | Desktop/Downloads path | scripts/desktop-path.sh | | Open app / file / URL | scripts/open-target.sh | | Quit / activate app | scripts/quit-app.sh, scripts/app-activate.sh | | List / frontmost app | scripts/list-apps.sh, scripts/frontmost-app.sh | | Reveal in file manager | scripts/reveal-in-finder.sh | | Safe move / copy | scripts/fs-move.sh, scripts/fs-copy.sh | | Organize (smart / extension / date) | scripts/fs-organize.py (--by smart default) | | Smart organize (shim) | scripts/fs-smart-organize.py → --by smart | | Safe trash | scripts/safe-trash.sh | | Clipboard | scripts/clipboard.sh | | Notification | scripts/notify.sh | | Screenshot | scripts/screenshot.sh | | Native path picker | scripts/choose-path.sh (macOS) | | AppleScript | scripts/osascript-run.sh (macOS) |

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

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.

Platform support

| | macOS | Linux | Windows | |--|-------|-------|---------| | Files (move/copy/organize) | ✅ | ✅ | partial | | Open / reveal | ✅ | ✅ | soon | | Clipboard / notify | ✅ | ✅ | soon | | Apps (list/quit/activate) | ✅ | best-effort | soon | | Screenshots | ✅ | ✅ | soon |

\* 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

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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: vivekkartha
• Source: vivekkartha/terminal-computer-use
• License: MIT
• Homepage: https://github.com/vivekkartha/terminal-computer-use

Install and usage instructions live in the source repository linked above.