README

t4a - terminals for agents

USAGE
  t4a <command> [args...]
  T4A_SOCKET=/tmp/t4a.sock (default)
  Daemon auto-starts on first command.

COMMANDS
  create [-- cmd...]        Create terminal (80x24, $SHELL)
  send <id> 'input\n'       Send keystrokes. Use single quotes!
                            t4a parses: \n \t \x03 \e \x7f
  send <id> < file          Reads stdin if no string arg
  events [id]               Stream events as NDJSON, never exits.
                            Omit id to stream all terminals.

  screenshot <id>            Low-res PNG to stdout (~250 tokens)
  screenshot <id> -o <file>  PNG to file
  text <id>                 All viewport lines (~400 tokens)
  text <id> 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 <id>               Raw PTY byte stream. Interactive.
  list                      List terminals as NDJSON
  kill <id>                 Kill terminal (SIGHUP)
  cursor <id>               {row, col, visible}
  resize <id> <cols> <rows> 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.