{"id":51619993,"url":"https://github.com/coder/agent-tty","last_synced_at":"2026-07-12T18:02:15.577Z","repository":{"id":357584738,"uuid":"1186175186","full_name":"coder/agent-tty","owner":"coder","description":"Drive, inspect \u0026 record terminal sessions from the CLI","archived":false,"fork":false,"pushed_at":"2026-06-23T13:50:37.000Z","size":57305,"stargazers_count":9,"open_issues_count":1,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-11T02:13:16.256Z","etag":null,"topics":["ai-agents","automation","claude-code","cli","codex","developer-tools","ghostty","playwright","pty","recording","screenshots","terminal","testing","tui"],"latest_commit_sha":null,"homepage":"https://github.com/coder/agent-tty/tree/main/docs","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/coder.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"docs/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-19T10:52:05.000Z","updated_at":"2026-06-30T19:38:14.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/coder/agent-tty","commit_stats":null,"previous_names":["coder/agent-tty"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/coder/agent-tty","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coder%2Fagent-tty","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coder%2Fagent-tty/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coder%2Fagent-tty/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coder%2Fagent-tty/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/coder","download_url":"https://codeload.github.com/coder/agent-tty/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coder%2Fagent-tty/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35398566,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-12T02:00:06.386Z","response_time":87,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","automation","claude-code","cli","codex","developer-tools","ghostty","playwright","pty","recording","screenshots","terminal","testing","tui"],"created_at":"2026-07-12T18:02:14.857Z","updated_at":"2026-07-12T18:02:15.565Z","avatar_url":"https://github.com/coder.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# agent-tty\n\nGive your AI agent a real terminal it can drive, and get back reviewable snapshots, screenshots, and recordings of everything it did.\n\n\u003e It's like `agent-browser` / Playwright, but for terminal apps instead of web pages.\n\n[![npm](https://img.shields.io/npm/v/agent-tty)](https://www.npmjs.com/package/agent-tty)\n[![CI](https://github.com/coder/agent-tty/actions/workflows/ci.yml/badge.svg)](https://github.com/coder/agent-tty/actions/workflows/ci.yml)\n[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](./LICENSE)\n![Node](https://img.shields.io/node/v/agent-tty)\n\n[Quickstart](#quickstart) · [Why](#why-not-just-tmux-expect-asciinema-or-playwright) · [How it works](#how-it-works) · [Commands](#command-surface) · [Contributing](#contributing)\n\n![agent-tty: drive a terminal session and watch it live in the dashboard](./assets/hero.gif)\n\nTools like `tmux` or `screen` help _you_ manage your own terminal windows. `agent-tty` is for handing a real, long-lived terminal to an AI coding agent, so it can run commands, drive interactive apps like `nvim` or `htop`, and read the screen back. Because every session is recorded, you never have to take the agent's word for what happened: you (or another agent) get a plain-text snapshot, a real screenshot, or a video of the actual screen, and can replay it to check the work. It works just as well for plain shell automation and CI smoke tests with no agent involved.\n\n## What you'd use it for\n\n- **Proof you can review.** An agent runs a task and attaches the screenshot, video, or replayable recording to its PR, so a human can confirm at a glance that the change really worked, instead of trusting a log.\n- **A tighter feedback loop.** Tell the agent to actually _use_ the TUI it just built or fixed, then read the screen back, so it catches a broken layout itself before you ever see it.\n- **Reproducing terminal bugs.** Spin up a clean, isolated terminal, reproduce a flaky TUI bug report there, hand it to an agent to attempt a fix, and verify the fix with a fresh recording.\n\n## Demos\n\nReal Codex and Claude TUIs discovering the `agent-tty` skill, driving `nvim --clean`, writing a file, and exporting inner proof artifacts. (GitHub renders these as click-to-play players.)\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003cth width=\"50%\"\u003eCodex\u003c/th\u003e\n    \u003cth width=\"50%\"\u003eClaude\u003c/th\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003cvideo src=\"https://github.com/user-attachments/assets/f1823164-330c-4962-8adf-2b825080e06f\" controls width=\"100%\"\u003e\u003c/video\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003cvideo src=\"https://github.com/user-attachments/assets/966bed35-9383-444e-b06a-1d103ccba49a\" controls width=\"100%\"\u003e\u003c/video\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\nFull reproducer, transcripts, and proof bundles are in [`dogfood/agent-uses-agent-tty/`](./dogfood/agent-uses-agent-tty/) and [`dogfood/CATALOG.md`](./dogfood/CATALOG.md).\n\n## Quickstart\n\nRequires Node `\u003e=24 \u003c27`. Screenshots and WebM video also need a Playwright Chromium install (`npx playwright install chromium`).\n\n```bash\nnpm install -g agent-tty\n\n# Sessions, logs, and artifacts live under ~/.agent-tty by default.\n# Optionally point AGENT_TTY_HOME at a throwaway dir for an isolated run:\nexport AGENT_TTY_HOME=\"$(mktemp -d)\"\nagent-tty doctor --json                  # check your environment\n\n# The canonical loop:\nSID=$(agent-tty create --json -- /bin/bash | jq -r '.result.sessionId')  # 1. open a session\nagent-tty run \"$SID\" 'printf \"hello from agent-tty\\n\"' --json            # 2. type into it\nagent-tty wait \"$SID\" --text 'hello from agent-tty' --json               # 3. wait for the screen\nagent-tty snapshot \"$SID\" --format text --json                           # 4. read it back\nagent-tty screenshot \"$SID\" --json                                       # 5. capture proof\nagent-tty destroy \"$SID\" --json                                          # 6. clean up\n```\n\nDriving an interactive TUI is the same loop, with key chords and a wait for the screen to settle:\n\n```bash\nagent-tty run \"$SID\" 'nvim --clean' --no-wait --json\nagent-tty wait \"$SID\" --screen-stable-ms 1000 --json\nagent-tty send-keys \"$SID\" Down Down Enter --json\nagent-tty screenshot \"$SID\" --json\nagent-tty record export \"$SID\" --format webm --json\n```\n\nMore workflows are in [`docs/USAGE.md`](./docs/USAGE.md). Other install paths (tarballs, prerelease channels, source checkouts) are in [`docs/INSTALL.md`](./docs/INSTALL.md).\n\n## Why not just tmux, expect, asciinema, or Playwright?\n\nThose tools are good, and you can get partway with any of them. `agent-tty` exists because driving a terminal _and_ getting reviewable evidence back is awkward with each one:\n\n| If you reach for…                     | You get                                         | What `agent-tty` adds                                                                                                                                |\n| ------------------------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `tmux` + `send-keys` / `capture-pane` | drive a pane, scrape raw bytes                  | a `wait`-for-condition primitive (stop sleeping and grepping), semantic snapshots, and PNG / `.cast` / WebM artifacts a process or human can review  |\n| `expect`                              | scripted input/output matching on a byte stream | a model of the _rendered screen_ (cursor, alt-screen, colors), plus shareable visual artifacts                                                       |\n| `asciinema` / VHS                     | a recording to watch later                      | programmatic drive + `wait` + inspect, so you act on terminal state instead of only recording it (and it still exports asciinema-compatible `.cast`) |\n| Playwright                            | this exact stateful loop, for browsers          | the same drive → wait → inspect → snapshot loop, applied to terminals and TUIs                                                                       |\n\nOne practical difference worth calling out: `agent-tty` produces real **PNG screenshots and WebM video** of the rendered screen, not just text or an asciicast. That means the proof an agent attaches to a PR is something a human can glance at inline, with no special player.\n\n`agent-tty` is an automation-and-inspection layer, not a tmux replacement.\n\n## Watch sessions live\n\n`agent-tty dashboard` opens a read-only, interactive view that lists your sessions and live-mirrors the selected one, so you can watch what your agents are doing in their shells (for example in a `tmux` split). It reads the append-only event log as its source of truth and never interrupts the running session. It needs the `libghostty-vt` renderer and an interactive terminal; machine-readable listing stays available via `list --json`.\n\n## How it works\n\n```text\nagent-tty CLI → per-session host → PTY + append-only event log → Ghostty renderer → artifacts\n```\n\nEvery session is backed by a real PTY (`node-pty`) and an append-only event log. The log is the source of truth, so snapshots, screenshots, and recordings can be regenerated deterministically by replaying it, even after the session has exited.\n\nRendering uses Ghostty's terminal engine through two interchangeable backends (`--renderer`):\n\n- **`libghostty-vt`** — Ghostty's native VT engine, bound into Node. It is the default for semantic snapshots, render-backed `wait` checks, and screen hashes when the optional native package is available. It also powers the dashboard.\n- **`ghostty-web`** — a headless web build of Ghostty driven by Playwright/Chromium. It is the default for visual PNG screenshots and WebM video, and it remains the automatic semantic fallback when `libghostty-vt` is unavailable.\n\n`ghostty-web` is a _reference_ visual renderer: it shows what a pinned Ghostty build draws, not a pixel-for-pixel guarantee of any particular native terminal window. That tradeoff is deliberate. The renderer sits behind an adapter, so additional backends can be used without changing the CLI contract. Set `--renderer ghostty-web`, `AGENT_TTY_RENDERER=ghostty-web`, or `config.json` `defaultRenderer` to restore legacy all-`ghostty-web` behavior.\n\n## Where it came from\n\nI maintain [`coder/claudecode.nvim`](https://github.com/coder/claudecode.nvim) and was drowning in issues and PRs I couldn't easily reproduce. Neovim is a TUI, and \"reproduce this, configure that, screenshot the result\" is painful to script with sleeps and `capture-pane`. `agent-tty` lets me spin up an isolated, reproducible terminal so an agent can first reproduce the issue reliably, turn that reproduction into a fixture, and only then attempt a fix with that fixture — plus a fresh recording — as the hard validation gate.\n\nA colleague then used `agent-tty` to build an experimental TUI for Coder agents almost entirely by letting coding agents drive it, checking the screenshots and recordings it produced instead of watching over their shoulder. That's the loop it's built for: an agent acts, `agent-tty` captures reviewable evidence, and a human (or another agent) verifies.\n\n## Command surface\n\nEvery user-facing command takes `--json` and returns a stable, machine-readable envelope, and exits with a stable code (`0` success, `2` usage error, `3` session not found, `11` wait timeout, …) so scripts can branch without parsing output.\n\n| Group                   | Commands                                                                 |\n| ----------------------- | ------------------------------------------------------------------------ |\n| Session lifecycle       | `create`, `list`, `inspect`, `destroy`, `gc`                             |\n| Input and control       | `run`, `type`, `paste`, `send-keys`, `batch`, `resize`, `signal`, `mark` |\n| Observation and capture | `wait`, `snapshot`, `screenshot`, `record export`                        |\n| Live view               | `dashboard`                                                              |\n| Environment             | `version`, `doctor`, `skills`                                            |\n\nThe CLI documents itself: `agent-tty --help` lists every command, and `agent-tty \u003ccommand\u003e --help` shows its flags. The full reference, including the exit-code table, is in [`docs/USAGE.md`](./docs/USAGE.md); renderer and environment issues are in [`docs/TROUBLESHOOTING.md`](./docs/TROUBLESHOOTING.md).\n\n## Agent skills\n\n`agent-tty` ships a bootstrap skill so coding agents can load current usage instructions at runtime:\n\n```bash\nagent-tty skills list\nagent-tty skills get agent-tty\n```\n\nSee [`docs/AGENT-SKILLS.md`](./docs/AGENT-SKILLS.md).\n\n## Status \u0026 platform support\n\n`agent-tty` is `0.5.0` and focused on reliable, isolated, reviewable terminal and TUI automation through a stable CLI. \u003c!-- x-release-please-version --\u003e\n\n- Linux and macOS are tier-1; Windows is tier-2 and not CI-tested.\n- Semantic snapshots and render-backed waits prefer the optional `libghostty-vt` backend when it is available, then fall back to `ghostty-web`.\n- Screenshots and WebM video depend on Playwright/Chromium and the `ghostty-web` backend.\n- `run` is best for shell setup and command injection; it does not capture a child command's structured output or exit status.\n- Apache-2.0, runs entirely locally, no account or SaaS.\n\nThe supported contract is in [`RELEASE.md`](./RELEASE.md); the architecture is in [`design/ARCHITECTURE.md`](./design/ARCHITECTURE.md).\n\n## Contributing\n\nIssues and PRs welcome. See [`docs/CONTRIBUTING.md`](./docs/CONTRIBUTING.md) and the [`good first issue`](https://github.com/coder/agent-tty/labels/good%20first%20issue) / [`help wanted`](https://github.com/coder/agent-tty/labels/help%20wanted) labels.\n\n```bash\nmise install \u0026\u0026 mise run bootstrap   # preferred\nnpm run cli -- --help\nnpm run verify\n```\n\n## License\n\n[Apache License 2.0](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoder%2Fagent-tty","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcoder%2Fagent-tty","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoder%2Fagent-tty/lists"}