tui-devtools

tui-devtools

All-in-one TUI automation + DevTools for terminal apps.

Run, screenshot, interact, and inspect — built for AI agents.

What It Does

Works with any TUI/CLI app — no framework dependency:

tui-devtools start                          # Start daemon
tui-devtools run "htop"                     # Run any TUI app in a PTY
tui-devtools screenshot                     # Capture screen as text
tui-devtools press q                        # Send keystrokes
tui-devtools type "hello"                   # Type text
tui-devtools wait "Ready"                   # Wait for text to appear
tui-devtools kill-session                   # Kill the app
tui-devtools stop                           # Stop daemon

Bonus for Ink (React) apps — component tree & state inspection:

tui-devtools run "DEV=true npx my-ink-app"  # Run with DevTools enabled
tui-devtools tree                            # React component hierarchy
tui-devtools inspect MyComponent             # Props, state, hooks
tui-devtools find Text                       # Search components by name
tui-devtools logs --level error              # Captured console output

Install

npm install -g tui-devtools

Two Layers

Layer	Works With	What You Get
PTY Automation	Any TUI/CLI app	run, screenshot, press, type, wait, scroll, kill
React DevTools	Ink apps + DEV=true	tree, inspect, find, logs

PTY automation works universally — Ink, Bubbletea, Ratatui, htop, vim, anything that runs in a terminal. React DevTools is an additional layer that activates when the app supports it.

Quick Start

Any TUI App

tui-devtools start
tui-devtools run "npx create-next-app"
tui-devtools wait "project name"
tui-devtools type "my-app"
tui-devtools press Enter
tui-devtools screenshot
tui-devtools kill-session
tui-devtools stop

Ink App with DevTools

tui-devtools start
tui-devtools run "DEV=true npx my-ink-app"
tui-devtools wait ">"

# Screen (what the user sees)
tui-devtools screenshot

# Structure (what React sees)
tui-devtools tree
tui-devtools inspect App --json

# Errors (what the console says)
tui-devtools logs --level error

tui-devtools kill-session
tui-devtools stop

Commands

PTY Automation (Universal)

Command	Description
start	Start daemon (WebSocket + IPC server)
stop	Stop daemon
run "<command>"	Run command in PTY (shell auto-wrapped)
screenshot	Capture current terminal screen
screenshot --strip-ansi	Without ANSI color codes
press <key> [key...]	Send keystrokes (Enter, Tab, ArrowDown, Ctrl-c, etc.)
type "<text>"	Type text
wait "<text>"	Wait for text to appear on screen
wait "<text>" --timeout 5000	With custom timeout
scroll up/down [N]	Scroll viewport
kill-session	Kill PTY process
sessions	List running PTY sessions
status	Show daemon & connection status

React DevTools (Ink Apps Only)

Command	Description
tree	Component hierarchy
tree --depth N	Limit depth
tree --json	JSON output
inspect <name>	Props, state, hooks
inspect --id <N>	By fiber ID
find <name>	Search components by name
logs	Captured console.log/warn/error
logs --level error	Filter by level
logs --tail N	Last N entries

React DevTools requires: react-devtools-core installed in the app + DEV=true env var.

Key Names

Key	Name
Enter	Enter
Tab	Tab
Escape	Escape
Arrows	ArrowUp ArrowDown ArrowLeft ArrowRight
Backspace	Backspace
Space	Space
Ctrl+C	Ctrl-c
Multiple	press ArrowDown ArrowDown Enter

Session Management

# Daemon-level sessions (-s) for isolation
tui-devtools -s project1 start
tui-devtools -s project2 start --port 8098

# Multiple PTY sessions within one daemon (--sid)
tui-devtools -s test run "app1" --sid app1
tui-devtools -s test run "app2" --sid app2
tui-devtools -s test screenshot --sid app1

Output Formats

tui-devtools screenshot                # Text (human-readable)
tui-devtools screenshot --json         # JSON (automation)
tui-devtools tree --json               # JSON component tree
tui-devtools sessions --json           # JSON session list

How It Works

┌─────────────────────────────────────────────────────┐
│ tui-devtools daemon                                 │
│                                                     │
│  ┌──────────────┐    ┌───────────────────────────┐  │
│  │ PTY Manager  │    │ React DevTools Server     │  │
│  │ (node-pty +  │    │ (WebSocket :8097)         │  │
│  │  xterm)      │    │                           │  │
│  │              │    │ Ink app ──ws──► fiber tree │  │
│  │ Any TUI app  │    │              ► console    │  │
│  └──────┬───────┘    └───────────┬───────────────┘  │
│         │                        │                  │
│         └────────┬───────────────┘                  │
│                  │ Unix socket IPC                  │
└──────────────────┼──────────────────────────────────┘
                   │
            CLI commands ◄── AI agent / human

Requirements

• Node.js >= 18
• macOS or Linux (PTY support)

For React DevTools features (optional):

• Target app must use Ink (React-based TUI)
• react-devtools-core package installed in the app
• App launched with DEV=true environment variable

Troubleshooting

# posix_spawnp failed (macOS)
chmod +x $(npm root -g)/tui-devtools/node_modules/node-pty/prebuilds/darwin-*/spawn-helper

# Daemon status
tui-devtools -s test status

# Debug logs
cat ~/.tui-devtools/test.log

License

MIT