# Agent Terminal

> Terminal and TUI automation CLI for AI agents. Use when the user needs to create a terminal session, run a command in a terminal, automate an interactive CLI or TUI, wait for terminal output, capture a TUI screenshot, export a terminal recording, or test a CLI workflow with reviewable artifacts.

- Skill: `coder/agent-terminal` (Agent Skill)
- Install (CLI): `npx skillmds@latest add coder/agent-terminal`
- Raw SKILL.md: https://api.skillmd.com/api/skills/coder/agent-terminal/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: coder (https://skillmd.com/u/coder)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/coder/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.

```bash
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

```bash
# 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

```bash
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

```bash
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

```bash
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 ...`.