terminal-use

Control macOS terminal apps via tmux keystrokes and verify output with screenshots.

2|Updated Oct 16, 2021
One-click install
npx skills add https://github.com/pattobrien/dotfiles --skill terminal-use-pattobrien
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: terminal-use
Source: https://github.com/pattobrien/dotfiles/tree/main/claude/skills/terminal-use
Command: npx skills add https://github.com/pattobrien/dotfiles --skill terminal-use-pattobrien

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve? Interacting with visible terminal applications normally requires stealing window focus or blind guessing at command results. This Skill lets an AI send keystrokes to terminal apps in the background and visually verify outcomes without disrupting the user's workspace. ## Core Features & Use Cases - Background Keystroke Injection: Send commands and special keys (Escape, Space, Return) to tmux sessions and nested apps like nvim without foregrounding windows. - Headless and GUI Screenshots: Capture tmux panes as PNG images via freeze, or grab specific windows and multi-monitor screens with screencapture and a CGWindowID lookup script. - Event-Driven Output Waiting: Block until specific text appears in a tmux pane using the wait-for-text.sh hook-based script instead of polling with sleep. - Use Case: Run an end-to-end test of a Neovim configuration by launching nvim in a detached tmux session, sending key sequences, waiting for the mode line to appear, and screenshotting the result to confirm the UI rendered correctly. ## Quick Start Open a detached tmux session named test, send it a command, wait for the expected output text, and take a screenshot to verify it worked.

Frequently Asked Questions about terminal-use

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I send keystrokes to a terminal app without stealing focus?▼

Use tmux send-keys to a detached session, for example tmux send-keys -t test "command" Enter. This works in the background and even supports nested apps like nvim using literal key names such as Escape or Space.

How to capture a tmux pane as an image without a GUI?▼

Pipe tmux capture-pane output into freeze: tmux capture-pane -pet <target> | freeze -o /tmp/screenshot.png. It renders ANSI colors and TUI elements to PNG in about half a second and works in CI or over SSH.

How do I wait for specific text in a tmux pane?▼

Use the wait-for-text.sh script with a target, an extended regex pattern, and an optional timeout. It uses tmux's pane-output-changed hook to block event-driven instead of polling, and exits immediately if the text is already present.

Does AppleScript keystroke sending work without foregrounding the app?▼

No, osascript with System Events steals focus, so it is only a fallback when tmux is unavailable. App process names may be lowercase, and you should add delay 0.2 between keystrokes that traverse layers like terminal to tmux to nvim.

How do I screenshot a single window by app name on macOS?▼

Use the get-window-id.sh script to look up the CGWindowID via JXA and CoreGraphics, then pass it to screencapture -l. For all monitors, pass multiple output paths to screencapture -x, one per screen.