T4a – Terminals for Agents
quality 7/10 · good
0 net
t4a - terminals for agents
USAGE
t4a [args...]
T4A_SOCKET=/tmp/t4a.sock (default)
Daemon auto-starts on first command.
COMMANDS
create [-- cmd...] Create terminal (80x24, $SHELL)
send 'input\n' Send keystrokes. Use single quotes!
t4a parses: \n \t \x03 \e \x7f
send < file Reads stdin if no string arg
events [id] Stream events as NDJSON, never exits.
Omit id to stream all terminals.
screenshot Low-res PNG to stdout (~250 tokens)
screenshot -o PNG to file
text All viewport lines (~400 tokens)
text 0:5 Last 5 lines (indexed from bottom)
Screenshots are intentionally low-res to minimize tokens. Use
screenshot to glance at overall state. Use text to read exact lines.
attach Raw PTY byte stream. Interactive.
list List terminals as NDJSON
kill Kill terminal (SIGHUP)
cursor {row, col, visible}
resize Resize terminal
EVENTS
command_done Shell finished a command. {"code": 0}
idle No output for 2s. {"after_ms": 2001}
activity Output resumed after idle.
exit Shell process exited. {"code": 0}
bell BEL character received.
title Window title changed. {"title": "vim"}
Typical sequence after sending a command:
activity -> command_done -> idle
command_done uses shell integration (bash/zsh). It fires for
every command, including builtins like cd. Does not fire inside
programs like vim or python — use idle for those.
EXAMPLE
$ t4a create
{"ok":true,"id":"t1","cols":80,"rows":24,"pid":1234,"socket":"/tmp/t4a.sock"}
$ t4a send t1 'cargo build\n'
$ t4a events t1 | head -3
{"event":"activity","terminal":"t1"}
{"event":"command_done","terminal":"t1","code":0}
{"event":"idle","terminal":"t1","after_ms":2001}
$ t4a text t1 0:3
error[E0308]: mismatched types
--> src/main.rs:42:5
$ t4a screenshot t1 -o s.png
$ t4a send t1 '\x03' # ctrl+c
$ t4a kill t1
Long-running commands (e.g. cargo build) can run for minutes.
Instead of polluting the context window with "Compiling x" lines,
kick it off and wait for the command_done event.
NOTES
IDs: t1, t2, ... assigned sequentially.
Screenshots: indexed-color PNG, ~2-10KB.
events never exits — pipe through head, grep -m1, etc.