Skip to Content
GuidesTerminal Console

Terminal Console

shep tui opens a full-screen console that lists every feature, live. Features that need you are pinned at the top, and single keys approve, reject, stop or resume a run. Inside tmux, Zellij, WezTerm or kitty it can also open a feature’s shell or agent log in a pane next to the console.

shep tui

The shep tui console: a header with 3 needs you, 1 running, 0 waiting, 0 failed and 1 done; a NEEDS YOU strip; the roster with state, feature, repo, phase, time and cost; a details pane for the selected feature with its branch, state, agent, tokens and an open question; and the key bar

The console does not need the web daemon. It reads Shep’s local database directly and runs actions through the same code as shep feat approve, shep feat reject and shep feat resume, so you can use it over SSH or on a machine where shep start isn’t running. It refreshes every 2 seconds and uses the terminal’s alternate screen, so your scrollback is untouched when you quit.

Options

OptionWhat it does
--repo <path>Only show features of this repository (shep tui --repo . for the current one)
--allInclude archived features
--no-notifyDon’t ring the bell or send a terminal notification when a feature starts needing you
--status [style]Print a one-line summary and exit. Styles: plain (default) or tmux. Needs no TTY

shep tui needs an interactive terminal. In scripts and pipes it exits with code 1 and points you to shep feat ls.

What’s on the screen

shep · Features 4 needs you · 0 running · 0 waiting · 0 failed · 0 done NEEDS YOU ◆ Dark Mode Toggle · review merge ◆ Rate Limit The Public API · review merge ◆ Billing… STATE FEATURE REPO PHASE AGENT TIME COST │ Rate Limit The Public API ae315e71 ◆ Needs you Dark Mode Toggle acme-web merge Claude Code 0s — │ Repo acme-web ▸ ◆ Needs you Rate Limit The P… acme-web merge Claude Code 0s — │ Branch feat/rate-limit-the-public-api ◆ Needs you Billing Dashboar… acme-web merge Claude Code 0s — │ State Needs you · merge ◆ Needs you Add Password Res… acme-web merge Claude Code 0s — │ Agent Claude Code · claude-opus-5-5 │ Time 0s │ Cost — │ Tokens 0 in · 0 out ↑↓ select enter details l log a approve r reject ? help q quit
  • Header. Counts of features that need you, are running, waiting, failed and done. The terminal window title also shows how many need you (shep · needs you: 4).
  • NEEDS YOU strip. Every feature waiting on you: an approval gate (review merge, review plan, …) or open agent questions (questions: 2). These features are also sorted first in the roster. When nothing needs you, the strip says so.
  • Roster. One row per feature with its state, name, repository, phase, agent, elapsed time and cost.
  • Details pane. Repo, branch, worktree, state, agent and model, time, cost, tokens, the PR, open questions and the last error for the selected feature. Press l to swap it for the tail of the agent log.
  • Key bar. Shows only the keys that apply to the selected feature. For example, a and r appear only when the run is waiting at a gate.

Keys

KeyAction
↑ ↓ / j kMove the selection
PgUp PgDn / g GPage up and down, jump to first and last
enter / iDetails pane
lLog pane: the tail of the current run, kept fresh
aApprove the gate
rReject the gate. Type your feedback, enter sends, esc cancels
sStop the run. Asks y/n first; the run stays resumable
RResume an interrupted or failed run
uRelease the paused fleet queue (asks first). Only offered while the queue is paused
oChat with the feature’s agent. esc returns to the list
t / TShell in the feature’s worktree: split pane / new window
f / FFollow the agent log: split pane / new window
/Filter the roster. enter keeps the filter, esc clears it
: / ctrl+pCommand palette
cCopy the selected feature’s full id to the clipboard (OSC 52)
CControl center: a window for every active feature
NNew feature in the selected feature’s repository
dLearned-harness changes waiting for you (adopt or reject). Only appears when the experimental self-learning harness has a change waiting
?Help (esc closes)
q / ctrl+cQuit and restore the terminal

Approve and reject

a approves the gate the selected feature is waiting at, exactly like shep feat approve <id>. Approving the merge gate merges the PR. r opens a feedback line at the bottom of the screen:

Feedback for Rate Limit The Public API: > Split the rate limiter from the API key rotation enter send · esc cancel

The agent reruns the phase with your feedback, like shep feat reject <id> --reason "…".

Create a feature

N asks for a description and creates a feature in the same repository as the selected row. Gates, push and PR follow your workflow settings (shep settings workflow). If the parallel-feature limit is reached, the new feature is queued and the console tells you its position.

Filter and the command palette

/ filters the roster by every word you type, for example acme merge. : or ctrl+p opens a palette of every command that applies to the selected feature. Type to search, enter runs the command:

The command palette over the console: Commands, 14 available, from Approve the gate (a) and Reject the gate with feedback (r) through Open a window for every active feature (C) to Quit (q), with a search prompt at the bottom

Commands 3 available Open a window for every active feature C Open a shell in a new window T Follow the agent log in a new window F : > window type to search · ↑↓ choose · enter run · esc close

Chat with a feature’s agent (o)

o opens a full-screen transcript of the feature’s chat, the same conversation as the Chat tab in the web UI. An interactive agent runs in the feature’s worktree, its text streams in as it writes, and each tool call shows as one muted line. Type a message and press enter.

When the agent asks a question, its options are numbered. Press a digit on an empty line to pick one, or type your own answer:

Chat · Billing Dashboard Charts · ready you › Which chart library should we use? ? Charts: Which library? 1. Recharts — Already used on the reports page 2. Chart.js — Smaller bundle, canvas rendering answer > 1–9 pick an option · or type an answer and press enter · esc back

Chat needs an agent with interactive sessions: Claude Code or Cursor CLI. Chat sessions the console starts stop when you quit it. The feature’s background run is not affected; steer it at its gates with a and r. See Chat.

Panes in tmux, Zellij, WezTerm and kitty

When the console runs inside a terminal multiplexer, t opens a shell in the feature’s worktree and f follows its agent log (shep feat logs -f) in a split next to the console. T and F open them in a new window (a tmux window, a WezTerm or kitty tab, a Zellij floating pane) instead.

  • A pane starts in the feature’s worktree, or in the repository if the worktree doesn’t exist yet.
  • A shell pane takes focus. A log pane leaves focus on the console.
  • Each split halves the console’s pane, so use T and F when you want several at once.
  • Panes inherit the console’s SHEP_HOME, so their shep commands read the same data.

Detection. Shep checks for a live session in this order: TMUX, ZELLIJ, WEZTERM_PANE, KITTY_WINDOW_ID. tmux or Zellij running inside a WezTerm or kitty window wins, because that’s the session that should split. TERM and TERM_PROGRAM are not used: they survive into nested shells and SSH sessions that have no multiplexer to talk to.

kitty needs remote control, because Shep opens panes with kitten @ launch. Add this to kitty.conf and restart kitty:

allow_remote_control yes # any socket path works listen_on unix:/tmp/kitty

Override. Set SHEP_MULTIPLEXER to pick one, or turn panes off:

SHEP_MULTIPLEXER=wezterm shep tui # tmux | zellij | wezterm | kitty SHEP_MULTIPLEXER=none shep tui # run t and f in this terminal

Without a multiplexer, t and f run in the same terminal: the console steps aside and comes back when you exit the shell or press ctrl+c to stop following the log.

Control center (C)

C opens a window for every active feature that has a run and no window yet. Each window follows that feature’s log and is named after its state. As states change, the console renames the windows: ◆ needs you, ● running, ✗ failed, ✓ done.

shep tui in tmux after pressing C: the tmux status line lists one window per feature, each prefixed with ◆, and shows "◆ 3 needs you" on the right

[shep] 0:console* 1:✓ Rate Limit The Public API 2:◆ Billing Dashboard Charts 3:◆ Add Password Reset Flow ◆ 2 needs you

Zellij can’t rename a pane that isn’t focused, so in Zellij the names stay as they were when opened.

tmux status line

Inside tmux the console publishes two tmux user options whenever they change:

OptionValue
@shep_statusA styled summary, for example ◆ 2 needs you · ● 1 running
@shep_needs_youThe number of features that need you

Put the summary in your status bar in ~/.tmux.conf:

set -g status-right '#{@shep_status} %H:%M'

When the console isn’t running, shep tui --status prints the same line once and exits, so a status bar or prompt can call it:

$ shep tui --status ◆ 2 needs you $ shep tui --status tmux #[fg=yellow,bold]◆ 2 needs you#[default]

--status opens the database on every call, so while the console is running prefer #{@shep_status}.

Terminal alerts

When a feature starts needing you, the console sends your terminal’s own notification, so it reaches the right tab or pane:

TerminalAlert
iTerm2OSC 9
WezTerm, GhosttyOSC 777
kittyOSC 99
Anything elseBell

Inside tmux, the notification is wrapped in tmux passthrough and followed by a bell. Passthrough is off by default in tmux, so turn it on:

set -g allow-passthrough on

Zellij drops these sequences, so inside Zellij you get a bell only. Use shep tui --no-notify to turn alerts off.

Paused queue banner

When the fleet admission queue is paused (with shep fleet pause), a banner above the NEEDS YOU strip shows how long and why:

shep · Features 1 needs you · 0 running · 0 waiting · 0 failed · 0 done ⏸ queue paused 2h 05m — Release freeze NEEDS YOU ◆ Rate Limit The Public API · review merge

Press u to release it. The console asks first:

Release the paused queue? New features can start. (y/n)

This is the same action as shep fleet resume and the Resume button in the web UI. The console never pauses the queue itself. If the fleet’s circuit breaker has tripped, the header also shows breaker tripped.

Running inside Herdr

If you run shep tui in a Herdr  pane, the console reports its state to Herdr (blocked with “needs you: N”, working or idle) and releases the pane when you quit. Nothing to configure; outside Herdr nothing is sent. See Agent activity.

List Shep processes: shep ps

shep ps lists the processes Shep runs: the web daemon and the agent workers, with the feature, agent, status, uptime, CPU and memory of each.

shep ps # live Shep processes shep ps --all # include runs whose process has exited shep ps --json # rows for scripts shep ps -w # redraw every 2 seconds until ctrl+c
Shep processes (1) KIND PID FEATURE AGENT STATUS UP CPU MEM daemon 8334 http://localhost:4050 — * running 4s 42.0% 256.4 MB 1 running · 0 crashed · 0 exited

With --all, runs that exited (finished, failed, or parked at a gate) are listed too:

shep ps --all listing three feature agents for Dark Mode Toggle, Rate Limit The Public API and Billing Dashboard Charts, all exited at waiting_approval

ColumnMeaning
KINDdaemon, feature agent or agent run
FEATUREThe feature name and short id (the URL for the daemon)
STATUSrunning, crashed (the run is marked running but its process is gone) or exited, plus the run’s status
UP, CPU, MEMUptime, CPU and memory. Not available on Windows, where they show —

A crashed feature can be resumed with shep feat resume <id>. --watch needs an interactive terminal; in scripts use --json.

Stop a run

shep ps stop <id>

<id> is a run id, a feature id, or a prefix of either. The web daemon is not an agent run: stop it with shep stop. If you run shep ps stop from inside a Shep agent run, where it would stop the agent that is running it, Shep refuses unless you pass --force.

What’s next