herdr Compatibility

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. 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

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 keeps its name, and errored and limit_reached show as done.

As in herdr, done is an agent at rest with a finished turn that nobody looked at yet. An idle or done agent shows as done until someone looks at the pane, and then shows as idle. A pane counts as looked at when one of these occurs:

• An attached client shows the pane focused.
• You dismiss the Inbox item of the pane.
• A herdr tool calls pane.focus or agent.focus on the pane, with or without an attached client.

Mark unread in the Inbox makes the pane done again. Each change sends pane.agent_status_changed. agent.wait and events.wait match this status.

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.
• 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.
• Send a prompt to an agent with agent.prompt.

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.

agent.prompt types the prompt into the agent and submits it, as tuios ask-agent does. A working agent gets the prompt too, and its harness queues it for the next turn, as in herdr 0.9.5. An agent that waits on a prompt is refused with agent_blocked, and nothing is typed. tuios ask-agent still refuses a working agent.

The plugin.* methods and popup.close are answered by the tuios plugin host. See Plugins. Some other herdr methods, such as the 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.