herdr Compatibility

Use tools built for herdr, such as Collie and herdr plugins, with TUIOS through herdr's socket API.

herdr is another multiplexer for coding agents. Tools that are built for it talk to its socket: Collie's herdr adapter, herdr plugins, bar widgets and editor bridges. TUIOS answers herdr's socket API on a socket of its own, so these tools work with TUIOS.

TUIOS follows the API of herdr 0.9.3.

Connect a tool

Set HERDR_SOCKET_PATH to the TUIOS herdr socket. It is the daemon socket with .herdr added:

export HERDR_SOCKET_PATH="$XDG_RUNTIME_DIR/tuios/tuios.sock.herdr"

When XDG_RUNTIME_DIR is not set, the socket is /run/user/<uid>/tuios/tuios.sock.herdr when /run/user/<uid> is yours with mode 0700, and /tmp/tuios-<uid>/tuios.sock.herdr otherwise (Added in v0.9.3). In a TUIOS pane, HERDR_SOCKET_PATH is set already.

To run Collie against TUIOS, start its bridge with the herdr adapter:

COLLIE_MUX=herdr HERDR_SOCKET_PATH="$XDG_RUNTIME_DIR/tuios/tuios.sock.herdr" collie start

herdr's own commands, such as herdr pane list, herdr pane read and herdr api snapshot, also work against this socket.

A ping answers with version 0.9.3+tuios and server: "tuios", so a tool can tell that it talks to TUIOS.

How TUIOS maps onto herdr

herdr	TUIOS
workspace	session
tab	workspace
pane	window

A pane id has herdr's form, w<session>:p<window>. The ids stay the same while the session and the window exist, and a rename does not change them.

A TUIOS workspace is one of a session's numbered slots. A workspace shows as a tab when it holds a window, has a name, or is the one that shows.

An agent's state shows as herdr's agent_status: needs_input is blocked, so a tool that shows the agents that need you shows these panes. working, idle and done keep their names, and errored shows as done.

What a tool can do

• Read everything in one call with session.snapshot, or with the lists.
• Read a pane with pane.read.
• Type into a pane with pane.send_text and pane.send_keys.
• Rename, focus, split and close panes.
• Move a pane to a tab of any workspace with pane.move. A tab of another workspace moves the pane to that TUIOS session, and its program keeps running. (Added in v0.10.0)
• Create, rename, focus, move and close tabs.
• Create, rename and close workspaces.
• List, create, open and remove git worktrees.
• Follow changes with events.subscribe.
• Report an agent's own state with pane.report_agent and the other report methods.
• Start an agent in a pane with agent.start, and wait for its state with agent.wait.

agent.start types the agent's command only into a pane that is at its shell prompt with no agent in it. Any other pane answers agent_pane_busy, and nothing is typed. That includes a pane whose foreground program TUIOS cannot read.

Other herdr methods, such as the plugin and layout methods, answer the error unsupported. The full table of methods is in AGENT_STATE.md.

herdr's command line

Plugins and tools built for herdr run herdr's CLI through $HERDR_BIN_PATH. In a TUIOS pane, that variable names a link called herdr that runs TUIOS. It answers pane, tab, workspace, agent (except attach), worktree, notification show and api snapshot, prints herdr's JSON and uses herdr's exit codes.

"$HERDR_BIN_PATH" pane split --pane "$HERDR_PANE_ID" --direction right --focus
"$HERDR_BIN_PATH" notification show "Build done" --body "All tests pass"

herdr agent start returns when the agent is at rest (idle or done), as in herdr. The link is not on PATH, so a real herdr on your PATH still runs as herdr.

Crush permission prompts

Crush reports its state over herdr's protocol. When Crush shows its "Permission Required" dialog, TUIOS reads the dialog from the screen:

• The pane goes to needs_input, and the Inbox lists it under Approvals.
• The message names the tool and what it acts on, such as approve bash: touch hello.txt. When the dialog does not show the whole call, the message ends with (not all shown).
• In the Inbox, a allows, A allows for the rest of the Crush session, and d denies. TUIOS presses Crush's own keys: a, s and d. tuios respond answers it too.
• The risk rules read the message. A call that matches a rule, or a message that ends with (not all shown), takes a second press.
• TUIOS answers only when it sees a Crush process in the pane.

Crush v0.97.1 and earlier can report working while the dialog is still up. TUIOS then reads the screen, and the pane stays on needs_input until the dialog closes.

Who may do what

Each herdr method runs the TUIOS command that does the same work, with the same checks.

• A tool that runs outside every pane has your full rights.
• A tool that runs in a pane holds that pane's grants. A read needs read. Typing needs write. A create, close, rename or focus needs admin.

Warning: A pane may not type into another pane that waits on a prompt, unless it holds respond. The keys would answer the prompt. admin does not give respond.