A terminal UI for one Paseo agent: its live log on top, a prompt box underneath. Run it in any terminal pane, including a Herdr pane, to watch an agent, steer it, answer its permission requests, use its slash commands, stop it or start a new one, without opening the Paseo app.
The agent keeps running in the Paseo daemon. herdr4paseo is only a client. Quitting it never interrupts the agent, and the Paseo desktop or mobile app can be attached to the same agent at the same time.
┌ alpha (7dba08f) running | send: steer | full log ─────────────────┐
│ [User] fix the failing test │
│ [Thought] The failure is in the date parser... │
│ [Shell] pytest tests/test_dates.py │
│ I found the bug: the parser ignores the timezone offset. │
├─────────────────────────────────────────────────────────────────────┤
│ 1 pending: Bash: rm -rf build (Ctrl+A allow, Ctrl+D deny) │
│ > /compact [focus] Compact the conversation │
│ /context Show context usage │
│ ┌ prompt ───────────────────────────────────────────────────────┐ │
│ │ /co │ │
│ └───────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
Paseo agents belong to the Paseo daemon, and paseo attach is a read-only stream. If you live in a terminal multiplexer such as Herdr, you want to watch and steer a Paseo agent from a pane without touching its run. See getpaseo/paseo Discussion #4070 for the wider request. This tool is the stopgap for the "Paseo owns the agent, my terminal fronts it" direction. For the opposite direction (Herdr owns the agent, Paseo mirrors it) see sdananjay/paseo-herdr, an alpha plugin for OMP agents.
Needs Python 3.11+ and the paseo CLI on PATH, with the Paseo daemon running.
uv tool install git+https://github.com/frdminc/herdr4paseoTo work on it, clone the repo and run uv tool install --editable ..
herdr4paseo # pick an agent from a list
herdr4paseo 7dba08f # attach by id, short id or unambiguous prefix
herdr4paseo --tail 200 --behavior interrupt 7dba08fFind an agent id with paseo ls -g -a. Type a prompt and press Enter to send it. Type / to see slash commands.
| Option | Default | Meaning |
|---|---|---|
agent |
pick from a list | Agent id, short id or unambiguous id prefix |
--tail N |
50 | Log entries to show when attaching |
--behavior steer|interrupt |
steer |
How a send treats a turn that is still running. interrupt stops the turn and redirects it; steer steers the running turn and, per Paseo, falls back to interrupting it if steering is unavailable. |
| Key | Action |
|---|---|
| Enter | Send the prompt |
| Ctrl+J, Shift+Enter | Newline in the prompt |
/, then Tab, Up, Down |
Slash-command suggestions: Tab completes the highlighted command, Up and Down choose, Enter sends exactly what you typed |
| Ctrl+T | Toggle send behaviour: steer or interrupt |
| Ctrl+O | Toggle a tools-only log view |
| Ctrl+L | Switch agent: type to filter by id, status, name, provider or directory, then Enter |
| Ctrl+P, Ctrl+N | Prompt history, previous and next (kept between runs) |
| Ctrl+R | Start a new agent (paseo run --no-wait): prompt, directory, provider (prefilled from the current agent); then attaches to it |
| Ctrl+X | Stop the agent (paseo stop), after a y/n confirmation |
| Ctrl+A, Ctrl+D | Allow or deny the agent's pending permission requests (only active while some are pending; asks to confirm) |
Ctrl+Q, or /quit / /exit typed in the prompt |
Quit back to the shell (the agent keeps running). The two typed commands are handled here and never sent to the agent, so they shadow an agent's own /quit or /exit |
The header shows the agent's status (polled every 3 s), the send behaviour and the log view. A failed send keeps your text in the box and prints the error in the log.
The terminal bell rings, with a yellow alert: line in the log, when the shown agent goes from running to idle or a new permission request appears. If the log stream ends (for example the daemon restarts), it reattaches by itself every 3 s.
| Variable | Effect |
|---|---|
PASEO_HOST, PASEO_HOME |
Select a daemon, exactly as for the paseo CLI. They also tell the slash-command lookup where to connect. |
HERDR4PASEO_HISTORY |
Path of the prompt-history file (default ~/.local/state/herdr4paseo/history.json, the last 200 prompts, shared by all agents). |
PASEO_BIN |
Path to the paseo executable to run (default paseo). The tests point it at a fake. |
NO_COLOR |
Turns colour off (bold, italic and dim stay). Textual treats an empty NO_COLOR= as set too, which is stricter than no-color.org. See Colours. |
TEXTUAL_COLOR_SYSTEM |
Force the colour depth: auto (default), standard (16 colours), 256 or truecolor. |
- It is a log view, not the agent's own TUI: no PTY features. Slash commands work because
paseo sendpasses/context,/compactand skills such as/stepsthrough to the provider. The Paseo app's own commands (for example/exit) are client-side in Paseo and do not exist here. - Permission requests: a banner lists the shown agent's pending requests (polled every 3 s). Ctrl+A or Ctrl+D opens a confirmation listing them;
yanswers each listed request by id withpaseo permit allow|deny, so a request that arrives after you looked is never approved blind. While none are pending, Ctrl+A and Ctrl+D keep their prompt-editing meaning (line start, delete). - Slash suggestions come from the daemon's
list_commands_request, the one request thepaseoCLI does not expose, over its local WebSocket. It is read-only. The daemon's local credential is read from$PASEO_HOME/local-credentialand sent only to a loopback daemon. A remote daemon that needs a password gets no suggestions; typed commands still send. - Log colouring is line by line from what
paseo logsprints: the[Tag]prefix, continuation lines of[User]and[Thought]entries, markdown, diff and code fences in assistant text.paseo logsdoes not tag assistant text, so a multi-line[User]prompt followed directly by assistant text shows that text in the user colour until the next tag. It prints no tool results or diffs, so those cannot be coloured. Details: Colours. paseo sendtext beginning with-gets one leading space so the CLI does not read it as a flag.- Ctrl+R needs a provider because
paseo runrefuses to start without one; it is prefilled from the current agent. Worktrees, models and output schemas are not offered: use thepaseoCLI. - Checked against a live daemon on 2026-10-30: the
paseocalls forpermit allow|deny,run,stopandls. The TUI's new keys (Ctrl+R, Ctrl+X, the bell, reconnect, the picker filter) are covered by tests against fakes only.
- docs/usage.md: walkthroughs for the common jobs, and troubleshooting.
- docs/architecture.md: which
paseocommands it runs, the one WebSocket request, the security notes, the code layout and how to test.
uv run --group dev pytest -qThe tests drive the app with a fake paseo executable (tests/fake_paseo.py, selected through PASEO_BIN) and a fake daemon WebSocket (tests/fake_daemon.py), so they never touch a real daemon.
- getpaseo/paseo Discussion #4070 — request for a terminal front-end while Paseo owns the agent.
| Repo | Role |
|---|---|
| frdminc/herdr | Fork of herdrdev/herdr |
| herdr-plain-line | Local plugin: plain-English popup for tab/workspace rename and create |
| herdr-sleeper | Plugin: sleep idle agent panes, wake later |
| herdr4paseo | Terminal UI to watch/steer a Paseo agent from a pane |
| paseo4herdr | Paseo plugin mirroring OMP agents that run in Herdr |
MIT