Driving MiniCon from a script

MiniCon exposes the same surface to a script that a person uses through the window. There is no separate automation mode: the control CLI drives the real UI, and what you read back is what the window is actually showing.

This exists because a terminal an agent can drive has to be observable, not just controllable. Sending a key is easy; knowing what happened next is the hard half.

This is not a server

--control binds a local named pipe or Unix socket inside the GUI process, and only if you pass the flag. A second invocation, minicon cli --control …, is a short-lived client: it connects, sends one ATC1 request, prints JSON, and exits. Close the window and the endpoint is gone. There is no daemon, no default port, and no remote transport.

Capture and screenshots use that same socket (capture-pane, screenshot-pane, ui-snapshot). Alternatively, --emit-snapshot PATH writes screen text after each render with no listener at all.

AgenTerm is the Agent-era workbench on the same platform layer: Fleet, mux, persistence, and Agent permissions, with a server identity that can outlive one window. Shared verb spellings; different wire and lifetime. MiniCon stays the one-file local terminal.

Opening an endpoint

Start MiniCon with a control endpoint, then talk to it with the same executable:

minicon --control pipe:\\.\pipe\my-session
minicon cli --control pipe:\\.\pipe\my-session list-tabs

The endpoint is a named pipe on Windows and a Unix socket elsewhere. The Windows form needs the full local namespace — pipe:\\.\pipe\NAME. A bare name is refused rather than silently misinterpreted.

Every command prints JSON on stdout and exits nonzero on failure, so a script can branch on the exit status and parse the body without scraping prose.

Reading state

Command	Answers
list-tabs	every tab, its @ID, title, parent, and whether its child is alive
ui-snapshot	focus, IME state, input contents, pending work, control geometry
capture-pane	the pane as text; --output PATH writes it to a file instead of stdout
screenshot-pane	the pane as a PNG
perf-stats	frame and throughput counters
reset-perf-stats	zero the counters so a measurement starts from a known point
list-commands	the commands this build accepts

list-tabs reporting "child_alive": false with an exit code is how a script learns a command finished — without polling the screen for a prompt.

Waiting instead of sleeping

minicon cli --control ENDPOINT wait-text --timeout-ms 20000 "BUILD OK"
minicon cli --control ENDPOINT wait-tab-exit --target @2 --timeout-ms 60000

Both block until the condition holds or the timeout expires, and report which happened. A fixed sleep is either too short and flaky or too long and slow; these are neither.

Sending input

Command	Use
send-text	type text into a terminal; --file PATH sends a file's contents
send-paste	paste, with bracketed-paste handling; --file PATH sends a file's contents
send-keys	named keys — Enter, Escape, Tab, Up, F1, Ctrl+C
send-ui-keys	follows current UI focus rather than a terminal
send-ui-ime	drive an IME preedit and commit
send-mouse	pointer events in terminal cells
send-wheel	scroll; positive notches scroll up
cancel-pointer	release a control-owned pointer after a press without a matching release

send-keys always addresses a terminal; send-ui-keys addresses whatever has focus, which is how you reach the tab column and the input line.

Managing tabs

minicon cli --control ENDPOINT new-tab [--parent TAB]
minicon cli --control ENDPOINT select-tab --target @2
minicon cli --control ENDPOINT close-tab --target @2
minicon cli --control ENDPOINT resize-window --width 1000 --height 700
minicon cli --control ENDPOINT close-window
minicon cli --control ENDPOINT detach-gui
minicon cli --control ENDPOINT attach-gui

Tabs form a tree. Closing a parent promotes its children rather than taking them with it. @ID values are stable for the life of a tab, so a script can hold one across many commands without re-reading the list.

detach-gui releases the window while the process keeps running: the sessions stay alive and this endpoint keeps answering, so list-tabs and capture-pane still work with nothing on screen. Commands that need a window say so instead of hanging. attach-gui brings a window back. Both name the state they want, so either is safe to repeat.

Running one command instead of a shell

-e replaces the default shell. Everything after it is passed through verbatim, so it has to come last:

minicon -e cmd.exe /k my-build.bat

Combined with wait-tab-exit, this makes MiniCon a way to run something in a real terminal — with a real PTY, real VT handling, and a screen you can screenshot — and then collect the result.

Checking what you are talking to

minicon --status

Reports the build, the PTY backend this machine selected, the font face the system resolved to and its measured cell width, and where MiniCon writes when something fails. It opens no window, so a script can call it before deciding whether to start a session at all.

Discovering the surface

minicon cli list-commands

Prints the command list with no endpoint and no running window, which is what lets a script check what a given build supports before depending on it.