Skip to Content
TutorialsTerminal-Only with tmux

A Terminal-Only Workflow with tmux

You can run Shep without opening a browser. In this tutorial you set up tmux, open the shep tui console, act on features with single keys, follow logs and open shells in panes beside it, and keep an eye on Shep’s processes with shep ps.

Time: about 10 minutes. You need: Shep installed and an agent set up (see From zero to a merged PR), tmux, and a repository with a few features in it.

shep tui: moving through features, opening the log pane, searching the command palette and showing the keys help. Recorded with Shep's Demo agent.

Set up tmux

Add these lines to ~/.tmux.conf:

# Shep's summary in the status bar, while shep tui runs set -g status-right '#{@shep_status} %H:%M' # let terminal notifications through to your terminal app set -g allow-passthrough on

Start a session for your work:

tmux new -s shep

If tmux was already running, reload the file with tmux source-file ~/.tmux.conf.

Start a few features

From the shell in your repository, start two or three features, for example:

shep feat new "add a 404 page" --push --pr shep feat new "add a /health endpoint that returns uptime" --push --pr shep feat new "add a dark mode toggle to the header" --no-fast --pr

The last one is spec-driven, so it will stop at a requirements gate you can approve from the console.

Open 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 for four features; a details pane for Add /health endpoint with its repo, branch, state, agent, time, cost, tokens and one open question; and the key bar

You should see a header with counts, a NEEDS YOU strip, one row per feature and a details pane for the selected one. The roster refreshes every two seconds. Use shep tui --repo . to show only the current repository.

The console reads Shep’s local database directly, so it also works over SSH or when the web daemon isn’t running.

Move and inspect

KeyDoes
↑ ↓ or j kSelect a feature
enterDetails pane
lLog pane: the tail of the agent’s output
/Filter the roster by what you type
?All keys
qQuit

The key bar at the bottom shows only the keys that apply to the selected feature.

Approve or reject a gate

Select a feature marked ◆ Needs you:

shep tui with Add Stripe checkout selected: state Needs you in the requirements phase, and the key bar now showing a approve and r reject

  • a approves the gate, exactly like shep feat approve <id>. On a merge gate that merges the PR.
  • r opens a feedback line. Type what to change and press enter; esc cancels.

You should see the feature leave the NEEDS YOU strip and go back to work.

Features marked ? Question are waiting on an agent question. The details pane shows the command to answer it. See Decisions & agent questions.

Open panes beside the console

Inside tmux, select a feature and press:

  • f to follow its agent log in a split next to the console. Focus stays on the console.
  • t to open a shell in the feature’s worktree in a split. Focus moves to the shell; it’s a normal git checkout of the feature’s branch.
  • F or T to open the same in a new tmux window instead.
  • C to open a window for every active feature. The console renames the windows as states change: ◆ needs you, ● running, ✗ failed, ✓ done.

Each split halves the console’s pane, so use F and T when you want several.

Search the command palette

Press ctrl+p (or :). Every command that applies to the selected feature is listed with its key:

The shep tui command palette: 14 commands available, from Approve the gate (a) and Reject the gate with feedback (r) to Quit (q), with a search prompt at the bottom

Type to filter, for example follow, and press enter to run the highlighted command.

Watch Shep’s processes

Split a new tmux pane (ctrl+b %) and run:

shep ps --watch

shep ps listing two Shep processes: the daemon at http://localhost:4050 and a feature agent for Add /health endpoint, both running, with uptime, CPU and memory

You should see the web daemon (if it’s running) and one row per running feature agent, redrawn every two seconds. Press ctrl+c to stop watching. To stop one agent run, use shep ps stop <id> with a feature id or run id. Start it again later with shep feat resume <id>.

Check the status line

Look at the right side of your tmux status bar.

You should see Shep’s summary, for example ◆ 2 needs you · ● 1 running, updated by the console whenever it changes. When the console isn’t running, shep tui --status tmux prints the same line once, so you can call it from a script or a prompt.

Troubleshooting

  • shep tui exits with code 1 right away. It needs an interactive terminal. In scripts and pipes, use shep feat ls or shep tui --status.
  • t and f take over the whole terminal. Shep didn’t find tmux. Check that $TMUX is set in the console’s shell, or force it with SHEP_MULTIPLEXER=tmux shep tui. Zellij, WezTerm and kitty work too; see Terminal console.
  • The status segment is empty. @shep_status is set only while shep tui runs. Check that status-right is set in the session you’re looking at.
  • No notification when a feature needs you. Turn on allow-passthrough as in step 1. shep tui --no-notify turns alerts off on purpose.

What’s next