TUI Orchestrators
An orchestrator is a program that manages terminal panes and keeps long-running sessions organized: tmux, zellij, and herdr are common examples. Polytoken detects which one you are running in and adapts to it.
When you run Polytoken inside a herdr pane, Polytoken reports session activity so herdr, an agent-aware terminal multiplexer, can show whether the pane is working, idle, or waiting for your decision.
Client context
Section titled “Client context”Each session records who is driving it. The harness type describes the client:
tui for the terminal interface, outpost for sessions launched by Outpost,
and exec for a non-interactive polytoken exec run. The orchestrator list
names the terminal orchestrators Polytoken detected when the client started,
such as tmux, zellij, or herdr.
Both values stay with the session. When you resume a session, the resuming
client’s values replace the ones recorded earlier, so a client that attaches
later becomes the client Polytoken recognizes. A client can also update either
value while the session runs by sending a request to POST /client-context;
Polytoken keeps the recorded value when a request omits a field and clears the
value when the request sends the field empty.
Templates can read these values: harness_type holds the harness type,
orchestrators holds the orchestrator list, and using_orchestrator(name)
tests whether the list contains a name. See the
template reference for the full rows.
Changing either value changes the system prompt Polytoken composes whenever a template uses it. That prompt change may flush the provider’s cache of your prompt prefix, so the next request can cost more to process than usual.
Pane status
Section titled “Pane status”Polytoken reports one of three states to herdr:
| State | Meaning |
|---|---|
working | A turn is running, so Polytoken has locked prompt input. |
idle | No turn is running and nothing is pending. |
blocked | Polytoken needs a decision from you. A pending question, permission request, goal approval, or plan review takes precedence over a running turn. |
When Polytoken exits the TUI, Polytoken releases the pane. Herdr also receives the current model and facet as display metadata. That metadata does not affect herdr’s waits or rollups.
Restore a session
Section titled “Restore a session”Polytoken includes polytoken continue <session-id> as the resume command with
each state report. Herdr 0.9.2 and later can use that command to restore the
pane to the same Polytoken session. Earlier herdr versions ignore the resume
command.
The herdr skill
Section titled “The herdr skill”When the daemon starts with HERDR_ENV=1, Polytoken adds the shipped herdr
skill to the session’s skill library. The skill helps the model inspect panes, wait
for sibling agents, and prompt them. This activation depends only on the
herdr environment, not project configuration. A project definition at
.polytoken/skills/herdr/ replaces the shipped skill body. See
Skills for how Polytoken loads skill definitions.
Detach and reattach
Section titled “Detach and reattach”Detaching the TUI ends pane reporting, but the daemon keeps running. Herdr clears the pane at the next shell prompt and drops the stored resume command. When you reattach the TUI in a pane, Polytoken holds the pane again and resumes reporting.
Requirements
Section titled “Requirements”Use herdr 0.9.2 or later for session restore. Polytoken reports pane state only
inside a herdr pane, where herdr sets HERDR_ENV, HERDR_BIN_PATH, and
HERDR_PANE_ID. Outside herdr, Polytoken behaves as usual.