Socket API

Flock exposes a newline-delimited JSON (NDJSON) API over a Unix domain socket. The in-tree flock-multiplexer server implements HerdR-compatible automation methods; flock-herdr is the NDJSON client.

Source: crates/flock-multiplexer/src/api.rs · HerdR-compatible NDJSON automation (external herdr binary not required)

Connect

Setting	Default
Socket path	`$FLOCK_SOCKET` → `~/.config/flock/flock.sock` → `$XDG_RUNTIME_DIR/flock.sock`
Protocol	One JSON request per line; one JSON response per line
Streaming	`events.subscribe` and `pane.attach` may stream additional NDJSON events

Ensure the server is running:

flock multiplexer ensure
# or
flock herd server

Example request:

{"id": 1, "method": "ping", "params": {}}

Example response:

{"id": 1, "result": {"type": "pong", "version": "...", "protocol": "..."}}

Errors use {"id": ..., "error": {"code": "...", "message": "..."}}.

Method catalog

Method	Purpose
`ping`	Health check; returns server and protocol version
`session.snapshot`	Full session tree snapshot
`session.attach`	Resolve named session → workspace + pane
`workspace.create`	Create workspace with label, optional cwd
`workspace.list`	List workspaces
`tab.create`	Create tab in workspace
`tab.list`	List tabs (optional workspace filter)
`tab.focus`	Focus tab by id
`pane.split`	BSP split (`direction`, `ratio`, optional `cwd`)
`pane.swap`	Swap panes
`pane.zoom`	Zoom pane (`mode`: toggle / in / out)
`pane.focus`	Focus pane
`pane.list`	List panes (optional workspace/tab filter)
`pane.read`	Read visible screen text
`pane.send_text`	Send text to pane PTY
`pane.send_keys`	Send key sequence
`pane.send_input`	Send text and/or keys
`pane.resize`	Resize PTY rows/cols
`pane.write`	Raw write to pane
`pane.attach`	Stream pane output (subscription)
`pane.report_agent`	Hook: report agent name + state
`pane.clear_agent_authority`	Clear agent authority on pane
`agent.get`	Agent info for target pane
`agent.send`	Send text to agent pane
`agent.list`	List agents (optional workspace filter)
`agent.start`	Start registered agent in new/split pane
`agent.explain`	Diagnose agent state heuristics
`events.subscribe`	Stream filtered events
`events.wait`	Block until matching event (timeout)
`worktree.create`	Git worktree helper
`worktree.list`	List worktrees
`worktree.remove`	Remove worktree
`server.live_handoff`	Graceful server restart (layout preserved)
`server.stop`	Acknowledge stop (server may exit)

Methods marked Stream return an initial result then additional NDJSON event lines on the same connection.

CLI mapping

Automation need	CLI
Rich status dashboard	`flock herd status`
Attach to pane	`flock herd attach --pane <id>`
Wait for agent idle	`flock herd wait --pane <id> --status idle`
Install agent hooks	`flock integration install <agent>`
Remote over SSH	`flock remote --ssh user@host`

Agent detection

Screen heuristics detect Claude, Codex, and Cursor agent states (idle / working / blocked). Hooks via pane.report_agent provide authoritative state when integrations are installed.

Live handoff

server.live_handoff writes ~/.config/flock/sessions/handoff.json, spawns a replacement daemon, and releases the socket. PTY processes are not preserved across handoff — layout and visible text restore only.

Testing

cargo test -p flock-multiplexer
cargo test -p flock-herdr
flock multiplexer ensure
flock herd status

See Daily driver loop for the operator workflow.

Keyboard shortcuts