# socket api

While hrdx runs it serves a control API on a unix socket next to the state file (hrdx.sock), so scripts, editors, and coding agents can inspect and drive a running session. Disable with --api=false. The protocol is newline-delimited JSON: one request per line, one response line with the same id.

# macOS
$ SOCK="$HOME/Library/Application Support/hrdx/hrdx.sock"
 
# Linux
$ SOCK="$XDG_CONFIG_HOME/hrdx/hrdx.sock"
 
# inspect and drive the running session
$ echo '{"id": "1", "method": "status"}' | nc -U "$SOCK"
$ echo '{"id": "2", "method": "workspace.create", "params": {"path": "~/Developer/api", "agent": "claude"}}' | nc -U "$SOCK"
$ echo '{"id": "3", "method": "pane.create", "params": {"workspace": "api", "kind": "shell", "split": "down"}}' | nc -U "$SOCK"
$ echo '{"id": "4", "method": "pane.send_text", "params": {"pane_id": 3, "text": "run the tests", "enter": true}}' | nc -U "$SOCK"
$ echo '{"id": "5", "method": "pane.wait", "params": {"pane_id": 3, "until": "idle"}}' | nc -U "$SOCK"
$ echo '{"id": "6", "method": "pane.read", "params": {"pane_id": 3}}' | nc -U "$SOCK"

method	effect
ping	liveness check, returns pong
status	workspaces, tabs, and panes with id, kind, and state
workspace.create	open a directory as a workspace
workspace.close	close a workspace by name or path
pane.create	add a pane (kind, split: right, down, tab)
pane.send_text	type into a pane, optionally press enter
pane.read	the pane's visible screen as plain text
pane.wait	block until a pane's agent is idle or busy
pane.close	close a pane by id
events.subscribe	keep the connection open and push events

## events

After events.subscribe the connection stays open and hrdx pushes lines like:

{"event": "pane.busy_changed", "data": {"pane_id": 3, "busy": false}}

Events: workspace.created, workspace.closed, pane.created, pane.closed, and pane.busy_changed, so a script can react the moment an agent finishes instead of polling. pane.wait plus pane.send_text is enough to build simple agent pipelines: prompt an agent, wait until it is idle, read the screen, move on.