Agent Terminal

Terminal Automation with agent-terminal

Install the CLI with npm install -g agent-terminal, then use agent-terminal directly. Prefer isolated homes, JSON envelopes, and renderer-backed artifacts so terminal workflows stay reviewable and reproducible.

Core Workflow

Every terminal or TUI automation task should follow this pattern:

1. Create an isolated home with --home.
2. Check prerequisites with doctor --json before screenshot or recording work.
3. Create a session with create --json.
4. Run setup commands with run instead of simulating long shell typing.
5. Wait on observable terminal state with wait instead of blind sleeps.
6. Inspect the current screen with snapshot.
7. Capture proof artifacts with screenshot or record export.
8. Destroy the session when finished.

AGENT_HOME="$(mktemp -d)"
agent-terminal --home "$AGENT_HOME" doctor --json
SESSION_ID=$(agent-terminal --home "$AGENT_HOME" create --json -- /bin/bash | jq -r '.result.sessionId')
agent-terminal --home "$AGENT_HOME" run "$SESSION_ID" 'printf "ready\n"'
agent-terminal --home "$AGENT_HOME" wait "$SESSION_ID" --text 'ready' --json
agent-terminal --home "$AGENT_HOME" snapshot "$SESSION_ID" --format text --json
agent-terminal --home "$AGENT_HOME" screenshot "$SESSION_ID" --json
agent-terminal --home "$AGENT_HOME" record export "$SESSION_ID" --format webm --json
agent-terminal --home "$AGENT_HOME" destroy "$SESSION_ID" --json

Essential Commands

# Environment and lifecycle
agent-terminal --home <path> doctor --json
agent-terminal --home <path> create --json -- /bin/bash
agent-terminal --home <path> inspect <session-id> --json
agent-terminal --home <path> destroy <session-id> --json

# In-session control
agent-terminal --home <path> run <session-id> 'command here' --json
agent-terminal --home <path> type <session-id> 'literal text' --json
agent-terminal --home <path> paste <session-id> 'multiline payload' --json
agent-terminal --home <path> send-keys <session-id> Enter Ctrl+C --json

# Observation and proof
agent-terminal --home <path> wait <session-id> --text 'ready' --json
agent-terminal --home <path> wait <session-id> --screen-stable-ms 1000 --json
agent-terminal --home <path> snapshot <session-id> --format text --json
agent-terminal --home <path> screenshot <session-id> --json
agent-terminal --home <path> record export <session-id> --format webm --json

Common Patterns

Bootstrap a shell session

AGENT_HOME="$(mktemp -d)"
SESSION_ID=$(agent-terminal --home "$AGENT_HOME" create --json -- /bin/bash | jq -r '.result.sessionId')
agent-terminal --home "$AGENT_HOME" run "$SESSION_ID" 'pwd && ls -la' --json
agent-terminal --home "$AGENT_HOME" snapshot "$SESSION_ID" --format text --json

Drive an interactive CLI or TUI

AGENT_HOME="$(mktemp -d)"
SESSION_ID=$(agent-terminal --home "$AGENT_HOME" create --json -- /bin/bash | jq -r '.result.sessionId')
agent-terminal --home "$AGENT_HOME" run "$SESSION_ID" '<interactive-command>' --no-wait --json
agent-terminal --home "$AGENT_HOME" wait "$SESSION_ID" --screen-stable-ms 1000 --json
agent-terminal --home "$AGENT_HOME" send-keys "$SESSION_ID" Down Down Enter --json
agent-terminal --home "$AGENT_HOME" screenshot "$SESSION_ID" --json

Export reviewer-facing artifacts

AGENT_HOME="$(mktemp -d)"
SESSION_ID=$(agent-terminal --home "$AGENT_HOME" create --json -- /bin/bash | jq -r '.result.sessionId')
agent-terminal --home "$AGENT_HOME" run "$SESSION_ID" 'printf "artifact proof\n"' --json
agent-terminal --home "$AGENT_HOME" wait "$SESSION_ID" --text 'artifact proof' --json
agent-terminal --home "$AGENT_HOME" screenshot "$SESSION_ID" --json
agent-terminal --home "$AGENT_HOME" record export "$SESSION_ID" --format asciicast --json
agent-terminal --home "$AGENT_HOME" record export "$SESSION_ID" --format webm --json

Anti-Patterns

• Do not reach for tmux, screen, or ad hoc PTY wrappers first when agent-terminal can provide an isolated, inspectable session.
• Do not rely on blind sleep calls when wait --text, wait --idle-ms, or wait --screen-stable-ms can observe terminal readiness directly.
• Do not bypass --json when another tool or agent needs machine-readable results.
• Do not use external screenshot tools as the primary proof path when agent-terminal screenshot and agent-terminal record export can produce renderer-backed artifacts tied to the session timeline.
• Do not leave sessions running after the task ends; destroy them explicitly.
• Do not rewrite public examples into repo-local development invocations; the public workflow should stay agent-terminal ....