agent-tui CLI
Drives terminal UI programs for agents: runs them in a PTY session, captures the screen, sends keys and waits for text.
- 121 ★ on the repository
- Last commit
Extended access
Why this level
- The agent types into running programs with your privileges.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/agent-tuiDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The agent types into running programs with your privileges.
This is third-party code. Review the repository files before installing.
What it does
agent-tui is a CLI that runs terminal programs in isolated PTY sessions and hands their screen to an agent. The `run`, `screenshot`, `press`, `type`, `scroll` and `wait` commands form a loop: the agent looks at the screen, acts and waits for the result. Output is text or JSON. The repository ships a skill at `skills/agent-tui/SKILL.md`. It teaches the agent to re-capture the screen after every action, verify outcomes with `wait --assert` and close the session with `kill --yes`. A background daemon manages several sessions at once, and live preview runs over WebSocket.
Who it is for. Developers and testers who hand interactive console programs such as htop or vim to an agent for checking.
Good fit when
- An agent walks through an interactive terminal wizard and checks every screen.
- A regression scenario for a TUI app is built from key presses and text waits.
- An agent needs text from a console program screen as JSON.
- A terminal tool demo is replayed as the same scenario.
Not a fit when
- You automate a browser or a GUI application.
- The system runs native Windows, where the tool does not start.
- The command is not interactive and a plain shell run is enough.
Example request
Run htop through agent-tui, capture the screen, find the process with the highest CPU load and close the session.Limitations
Unix only: Linux, macOS and systems with PTYs and Unix domain sockets. Native Windows and PowerShell are not supported. The legacy `input`, `action` and `scroll-into-view` commands are deprecated and go away in the next major release. The agent types into any program it starts, so run only software that is safe to drive that way. Session state is kept in `~/.agent-tui/`. The daemon listens only on `127.0.0.1` by default; non-local access is enabled by `AGENT_TUI_WS_ALLOW_REMOTE`.
How to disable. Stop the daemon with `agent-tui daemon stop --yes`, remove the skill from the agent skills directory and uninstall the package with the manager that installed it. Clean `~/.agent-tui/` by hand.
FAQ
What does the working loop look like?
`agent-tui run` opens a session, `agent-tui screenshot` captures the screen, `press`, `type` or `scroll` act, and `wait` waits for the result. `agent-tui kill --yes` closes the session at the end.
How do I get JSON output?
Pass `--format json` to `run` and `screenshot`; the README also shows `agent-tui screenshot --json`. The response includes `session_id` and the screen capture.
Does it run on Windows?
No. Native Windows is not supported; you need Linux, macOS or another Unix system with PTYs.
How do I watch a session live?
Run `agent-tui live start --open`. The preview uses JSON-RPC over WebSocket.
Where is state stored?
By default in `~/.agent-tui/`: `api.json`, `sessions.jsonl` and UI state. `AGENT_TUI_WS_STATE` and `AGENT_TUI_SESSION_STORE` change the paths.
Discussion
No questions or reviews yet.
Related
CLI toolsMicrosoft’s CLI controls real terminal sessions, checks visible text and records test runs for investigating failures.
A local debugger for TypeScript agents: run step trees, CI trajectory checks and portable evidence bundles, with no account.
A self-improving QA agent: natural-language tests for web and mobile that self-heal and remember runs
A skill and tester agent for Claude Code that test the 1C interface through the 1c-testpilot MCP server with evidence
About 70 test automation skills: Selenium, Playwright, Cypress, Appium, JUnit, pytest and more, with runs on the TestMu AI cloud
Tester
Тестер
A scenario testing system for 1C:Enterprise with a set of agent skills that let an AI agent operate the application like a regular user
README in short
A daemon holds PTY sessions and the CLI talks to it over a Unix socket. Waiting relies on screen text or screen stability.