The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
hn — tmux improved
All of Harness in a terminal — every harness on every machine, in swarms and panes, from any terminal you can type into: a laptop, a server over SSH, a tablet's SSH app.
curl -fsSL https://harness.autonomous.ai/cli/install.sh | bash # installs harness and hn
hn # or: harness tui
The installed CLI keeps hn up to date automatically: it checks at daemon startup and on the
same schedule as CLI updates, including when only hn has a new release. Reopen hn to use the
new version; running clients and panes keep working. harness update also checks hn when
the CLI is already current. ADAPTER_UPDATE_DISABLE=true disables automatic updates for both;
local CLI builds and HARNESS_TUI_BIN overrides stay untouched. The first hn launch downloads
it if missing; harness tui --install explicitly reinstalls the latest published build.
If hn --version stays old after an update, run harness update to check the launcher too.
Old manual or development installs can bypass automatic updates. harness tui --install or
harness update --force backs up a recognized old Harness launcher and switches it to managed
updates after verifying the download. Unrelated commands and explicit HARNESS_TUI_BIN overrides
are preserved; the update output explains any PATH conflict. A missing binary behind a managed
launcher is restored automatically.
hn follows tmux 3.5a's keys, commands, formats and ~/.tmux.conf, with your harnesses on
every machine behind them. What tmux users have asked for over the years, and what hn does
about it: docs/tmux-improved.md.
The Harness OS image uses the same hn binary with an explicit OS session mode. Its live USB offers Install and Try; an installed OS offers agents, terminals and Wi-Fi. These screens and installation shortcuts are absent from ordinary hn on macOS and other Linux systems. Installing or updating hn alone does not turn a computer into Harness OS.
The shell-first flow opens your usual shell. Ctrl+B c makes a local window;
Ctrl+B Shift+N, %, and " make shell panes. A split inherits its source
computer, current directory, and selected model route. A new window uses native
agent defaults and stays local, even when the focused pane is remote. It uses a
local pane's directory, or the directory hn was launched from when leaving a remote pane.
Keyboard New Tab (Ctrl+B c) and New Harness (Ctrl+B Shift+N, or
Ctrl+Shift+N in terminals supporting extended keys) open the new shell's agent
picker at its first prompt. Escape leaves a normal shell. Explicit terminal
actions, scripted/detached windows, and native %/" splits remain plain shells.
In these zsh/Bash shells, ch chooses a computer (ch local, ch -), and cm
chooses a model route (cm default restores the agent's settings). These pickers
open under the prompt, within the current terminal. Switching
computers keeps each shell and its jobs alive. A route lasts for that pane;
explicit native model/profile/resume options take precedence. Run codex, claude,
pi, or another supported agent normally, and exit back to the shell. Missing
agents use the CLI's shared installer in that terminal, then launch with the original
arguments. An installation error returns to the prompt. Existing aliases/functions
stay intact; hn run <agent> explicitly uses the integration in that case, and
command <agent> bypasses it. Model routing currently supports Codex and Claude;
other agents ask you to use cm default rather than silently ignoring the selection.
At a Zsh or Bash 4+ prompt, Ctrl+P opens a blank search with sessions already
listed. Ctrl+N opens a blank search with agents already listed; no & is
displayed or required. Plain text filters that default list. Both use @ for
computers, : for project folders, and % for models. Removing the scope
character returns to the original list. Explicit & agent search remains
compatible. Agent and project choices compose the editable command; selecting
a session opens it. Only Enter at the shell prompt launches a composed command.
Choosing a different computer clears the old project folder and opens that
computer's folders. The agent, model, and native arguments stay selected. Escape
or Ctrl+C keeps the new computer without a folder; choosing the same computer
(including its name or local alias) keeps the existing folder.
Typing a fresh @, :, or % after an agent opens its suggestions automatically;
type to filter, Enter to insert, or Escape to keep editing. Bracketed paste,
quoted text, native option values, -- passthrough, and unrelated commands do not
open suggestions. HN_AUTOCOMPLETE=0 disables automatic opening while keeping
Ctrl+P and Ctrl+N available. Existing custom character bindings are respected.
Deleting an automatically opened scope closes suggestions and returns to the
composed command, preserving choices already made.
The computer and folder may also share one token:
claude @office:~/code/my-app %sonnet
claude %sonnet :~/code/my-app @office
codex :~/code/my-app %default
Each selection edits the line. Adding the agent after choosing a folder returns
the cursor to the end; deliberately editing a field in the middle stays there.
Escape preserves the draft and cursor. Only Enter
at the shell prompt launches. Fields replace earlier choices of the same kind;
their order after the agent does not matter. Folder lists and models come from the
selected computer. Remote paths use /absolute/path or ~/path; local relative
paths are resolved against the current shell directory. Missing/offline/ambiguous
computers, missing folders, and conflicting selectors fail without falling back
to another destination. The directory and model choices apply to this invocation;
they do not change the shell's cwd or its cm route. %default uses native agent
settings. %sonnet becomes a native model argument; grid picks use
%grid-name::model-id (quoted automatically when needed). Native model names are
ultimately validated by the agent; a typed name does not prove account access.
In the : folder picker, fuzzy-search nested folders by name: from home,
autonomous-harness or atnmhrns can find ~/code/work/autonomous-harness.
Candidates arrive as the selected computer's directory tree is scanned; typing
filters them immediately without restarting discovery. Tab or Right
searches inside the highlighted folder, Alt+Up goes to its parent, and
Enter inserts the full folder path in the command. code/ searches below
that directory relative to the shell; code/ap fuzzy-matches its descendants.
Recent projects outside the tree also appear in the initial list. Escape restores
the original command without changing directory or starting an agent. Hidden
folders and symlinks follow the existing directory API's exclusion policy.
Dependency/build trees and macOS Library/app bundles are listed but not descended
into until explicitly entered. Discovery is bounded to 10 seconds, 10,000 paths,
and 1 MiB of path text, and refreshed after 30 seconds; narrow to a folder if a
large tree reaches a limit. No find, Python, or fzf subprocess is required.
Use -- to pass everything after it literally to the agent, including tokens
beginning with @, :, or %. Ordinary commands, pipelines, native completion,
and user aliases/functions keep their behavior. Quotes around selector words
protect spaces and shell punctuation; they do not disable selectors. Use the
-- boundary or command claude when those words are agent input.
The existing ch, cm, and hn sessions commands stay available. hn pick
keeps the context switcher (@ computers, % model routes, with : as a legacy
alias). Ctrl+P in a non-agent draft uses the same @, :, % scopes as the
composer; picking a project inserts a quoted path, like file completion.
Stock macOS Bash 3.2 cannot expose its draft through bind -x;
it retains that switcher and accepts typed composed commands. The full editable
Ctrl+P composer and Ctrl+N agent picker use Zsh (macOS default) or Bash 4+ (Linux).
On Bash 3.2, Ctrl+N keeps its native history behavior.
When the chosen agent exits, its pane returns to that original shell, keeping
the working directory, model route, draft, and shortcuts. An exit in a background
pane does not move focus; the shell returns when you select that pane again.
On macOS, Cmd+P works when the terminal reports that key through the Kitty
keyboard protocol, or when its profile maps Cmd+P to Ctrl+P (hex 0x10). A
terminal's own menu shortcut otherwise wins; hn cannot override it. No terminal
settings are changed automatically. Ctrl+P also works on macOS. This binding is
active only while the shell edits a command; agents and editors keep their own
Ctrl+P. Up still recalls previous history. Set HN_PICKER_KEY='' in your shell rc
to disable the binding, or e.g. HN_PICKER_KEY='\C-g' to choose another key. The
Zsh widget is hn-picker-widget; the Bash bind-x function is _hn_picker_widget.
Ctrl+N also belongs only to the shell prompt; running agents keep their own binding.
Set HN_NEW_KEY='' to disable it or another key sequence to rebind it. Its Zsh
widget is hn-new-widget, and its Bash function is _hn_new_widget.
For shell-line completion, type ch , cm , or hn sessions and press Tab.
Search and press Enter to put the selection into the editable command; press Enter
again to run it. Escape preserves the draft. Ordinary completion and existing
fzf Ctrl+T, Ctrl+R, and Alt+C bindings stay in place. In Bash, an existing custom
completion for one of these commands takes precedence.
hn sessions [query] opens a compact inline finder in an integrated shell: fuzzy search through running
sessions and indexed saved conversations, with transcript search and previews. With no query,
they share one newest-first list by last activity; older conversations remain searchable. It reuses
Ctrl+B s's rows, fuzzy matcher, transcript search, previews, and open/resume actions.
Ctrl+/ toggles its preview; Alt+Up/Down scrolls it. Enter
focuses an existing session or resumes a saved conversation here; Escape leaves
the shell unchanged. Ctrl+B s remains the broader workspace browser. Saved history
and remote shell helpers need the matching CLI build; unsupported shells still work
as ordinary terminals.
The inline finder defaults to 45% height, reverse layout, a rounded border, and
inline counts. It uses supported layout, color, and key-binding options from
FZF_DEFAULT_OPTS, with conversation previews on the right and a compact list in
narrow panes. File-preview commands are not run on conversation IDs. Keep a bat
file preview in FZF_CTRL_T_OPTS rather than the global options so fzf's history
picker does not try to open a command as a filename.
Harness OS also has a file manager, only there: hn files [folder] (Super+E) fills a terminal of
its own with a folder as big tiles or a list (v), its folder tree to the left, and VS Code's
explorer menu on a right click: new files and folders, cut, copy, paste, duplicate, rename, and
delete to the Trash. A text file opens in its own editor (Ctrl+S saves, Esc closes; e uses
$EDITOR). hn files --open [folder] (Super+O) is an Open dialog in
the Mac's manner: places, folders as columns with a preview, Search, Cancel and Open. A folder
opens in an explorer of its own kept inside it (hn files --root DIR), a text file in the
editor alone (hn files --edit FILE), each through $HARNESS_FILES_LAUNCH when it is set. Inside hn on the OS, choose-file [-t pane] [folder] shows it over a pane.
Ordinary hn refuses both.


Rendered from demo-fleet terminal captures (tests/mock-daemon.mjs, MOCK_DEMO=1),
with animations off and a demo hostname.
It connects to the same daemon the desktop app uses: agents run on their own machines, and each agent pane streams its terminal. Swarms connected to a daemon share the account's desk with the desktop and phone. With no daemon available, hn opens local shells instead; a private PTY supervisor keeps them running through detach, reconnect and a client crash. These local sessions stay on this computer and remain intact when Harness reconnects.
hn requires a Harness account before opening the workspace, including in Harness OS and on existing signed-out
installations. Continue with Google, Apple or email in your browser, or approve a phone QR code
when using SSH. Escape cancels an attempt and returns to the sign-in choices; Ctrl+C detaches.
Signing in opens your saved workspace automatically. Already signed-in computers open offline too.
Harness OS connects to Wi-Fi or Ethernet before launching the TUI at that same sign-in page. Its installer
works offline; Super+W keeps network settings accessible before sign-in. After first setup,
an already signed-in account can reopen its workspace during a temporary outage.
Explicit sign-out and a session the server rejects both return to required sign-in, as Desktop
does. The background server keeps running throughout, preserving local work behind the page.
harness login remains available from a shell. Signing in keeps local work in place; changing
accounts removes the previous account's views without stopping its harnesses. If daemon startup
fails, a signed-in computer can still open a local shell. Each OS user connects through their own private Unix socket;
hn never attaches to another user's daemon merely because it occupies the default TCP port.
Like tmux new -A, it restores your swarms if the desk has any,
else window 0 opens your shell in the folder you ran hn from. C-b s finds every
harness. Closing the last window ends hn ([exited], as tmux says it); C-b d detaches.
Required account entry (terminal capture)
Rendered from the isolated native fixture in tests/workspace-controls.py.
Sessions are tmux's: hn new -A -s main (in a shell's rc, or a terminal profile) starts or
attaches, hn attach -t work goes back to one, and a plain hn returns to where you were.
From inside, new -d -s api -c ~/src/api, switch-client -t api, C-b ( C-b ) C-b L,
C-b $, kill-session, and any command's -t work:2 reach every session (C-b w shows them all
as tmux's tree does; C-b s lists them after the harnesses, so typing a session's name finds it), so
tmux-sessionizer and tmuxinator-style scripts work. The first session is the desk's (named for
this computer unless you name it); the others are this computer's, kept between clients.
More than one terminal works as with one tmux server. Each hn is a client. hn attach -t main from a second terminal (or over SSH) shows main in both, as tmux does: a split, a new
window or a window chosen in either shows in both, and either can type into its panes (typing
into a watcher takes control across that TUI's tabs). attach -r only watches; attach -d takes the session and
detaches the others. Commands from a shell reach every session, whichever terminal has it. hn ls, list-clients and detach-client -a see them all, and nothing is lost when they detach in
any order: the last one showing a session keeps it. What tmux's server
holds is every terminal's: set -g, bind, setenv -g and source-file in one reach the
others, a copy in one pastes in another, and ids ($1 @3 %7) name the same thing everywhere.
With no terminal open, scripts still work. The first command that needs a server starts hn
without a terminal: tmux's server, holding the sessions until you attach. For example,
hn new -d -s proj; hn new-window -t proj:1; hn send-keys -t proj:1 'npm run dev' Enter, or
tmuxinator's own script. It exits when it has no sessions left. tmux's -2 -u -l -v -N -D -T
flags are accepted (hn already works that way) and -c runs a command in your shell.
Keys
tmux's. The prefix is C-b; C-b s then Enter adds a harness to the current window, C-t opens
it in a new window, and C-v or C-x puts it beside or below. An already-open harness is focused.
A window is a swarm and a pane shows a harness. If you have a ~/.tmux.conf, it is read: your prefix and
binds (copy-mode-vi's and vim-tmux-navigator's too), source-file, if-shell, base-index,
renumber-windows, mouse, mode-keys, status-left/status-right and the window formats
(#[…] styles, #{?…}, %H:%M), pane-border-format, synchronize-panes and your colours come
with you. It is read as tmux reads it (tmux's own parser, ported): quotes and escapes, $VAR and
~, VAR=value and %hidden, %if/%elif/%else, { } blocks, source-file globs — the
whole file checked first, so a bad line is file:line: why and none of that file runs, as in
tmux. run-shell lines run too: a plugin's tmux … reaches hn (the tmux on its PATH is hn),
never a tmux server you have running.
Shared tabs use the same ordered pane rectangles as desktop, including custom divider
proportions. The layout picker offers desktop's shapes for the current pane count;
C-b Space still cycles tmux's seven layouts and shares their exact geometry.
Window resizing scales the saved arrangement without rearranging panes or publishing
an edit. Selected tab, focus and zoom remain local to each client. Standalone tmux
sessions retain tmux's resize behavior.
Splits, resize-pane, the seven layouts, swap-pane, rotate-window, join-pane, break-pane
and select-pane are tmux 3.5a's own arithmetic (layout.c, window.c): the same split sizes, the same
pane numbers and the same active pane after each. The default classic appearance draws thin
pane borders. Choose Appearance from the workspace menu, or use set -g @hn-look panes,
for pane surfaces with one-cell gaps and inset terminal content. In that appearance, panes have no drawn borders: background
contrast identifies focus. The margins and gaps keep the terminal's native background. The focused
pane uses a subtly contrasting fill (#181818 on a black terminal), while inactive dark panes use
rgb(64, 64, 64) with softer text. A lone or zoomed pane keeps the same focused surface. Light
terminals keep a light counterpart.
Explicit pane-border styles still customize the title; border line choices apply in classic and
tmux appearances.
Explicit program colors and user styles stay intact. The muted green status bar has a continuous
background, with tabs ordered number:name* status (previous window: number:name- status).
Subscription allowances read Claude 0% Codex 89% remaining, with amber at 20% or less
and red at 0% only on the percentage. Padding
shrinks automatically in small panes. The space between panes remains a resize handle; mouse
coordinates, copy selection and PTY dimensions follow the inset content. window_layout keeps
the original split structure. Use set -g @hn-animations off to keep
working and loading indicators still. Some defaults differ, and your .tmux.conf
overrides each: pane-border-status top (each pane's title row: its harness's name and state, and
its project and branch where the pane has room; long names shorten in the middle to keep
the state and distinguishing suffix visible), allow-set-title off (a pane's title is its
harness's name, not what the program sets), history-limit 10000 (agents print a lot; tmux keeps
2000), mouse on, set-titles on (the terminal's title: ?2 Fix flaky login test — Harness, the
harnesses waiting on you and the one in front; set-titles-string changes it), and the status line:
each window's most urgent harness state follows its name and tmux marker; idle dots are hidden
in tabs and pane headers. Connection, quota,
fleet counts, the quoted local machine name and clock sit on the right. The git branch stays in its pane
header, aligned to the right with its PR and written ⎇ branch without redundant punctuation.
Status-bar groups are separated by two spaces, with one space at each outer edge to align
with the pane surfaces. Window tabs start at the left, without a machine/session label.
Local and remote machines use their names from the app everywhere, such as "office".
Local shell panes keep that same name across daemon disconnects and reconnects. Unnamed account
machines use machine-<id8>, as on desktop and phone; before this computer is known, it is
This computer. An integrated shell's status shows its current computer and persistent
cm model route, or Agent default when none is selected. Per-command %model
choices stay in the command and do not change that persistent route. Other panes
keep the local-machine label. Custom formats can include #{shell_context}.
Custom status formats and the prefix cue remain supported.
Take Control (C-b : take-control, or take) reclaims all available local and remote panes
across the TUI's tabs, including hidden ones, without changing focus. Typing into a watched pane
does the same; the input goes only to that pane. Reconnects keep watching until a person asks
for control again, and read-only clients keep their read-only behavior.
One key differs on purpose: ⇧⏎
reaches the pane as CSI 13;2u (a new line in an agent's prompt; tmux, without extended-keys,
sends a plain Enter).
| tmux keys | |
|---|---|
C-b s |
every harness on every machine — an fzf list with a live preview |
C-b c |
new local shell window, using the local source folder or the folder hn was started in; the model route resets to agent defaults |
C-b N |
new shell pane with the agent picker, inheriting its source computer, current folder, and model route |
C-b % C-b " (and C-b | for %) |
split right / below — a shell, at once, in this pane's machine and folder (C-b - is tmux's delete-buffer) |
C-b o C-b ; C-b ←↑→↓ C-b q |
next pane, last pane, pane in a direction, pane numbers |
C-b z C-b space C-b M-1…7 C-b { } C-b C-o |
zoom, next layout, a layout, swap, rotate |
C-b C-←↑→↓ C-b M-←↑→↓ |
resize (repeatable, like tmux's -r) |
C-b n C-b p C-b l C-b 0…9 C-b w C-b , |
windows |
C-b x / C-b & |
Close pane / Close Tab, as in Desktop. Owned harnesses are saved and stopped; idle ones stop directly, while working, unknown or draft ones ask first with Cancel selected. A failed stop keeps the pane and says why, with Keep open selected; Close pane then closes only the view (the harness may still be running). Plain terminals ask before closing; shared, already-stopped or unlisted harnesses, and ones without a terminal, only close their view. |
C-b [ C-b ] |
copy mode (tmux's, vi or emacs keys as mode-keys says), paste |
C-b < C-b > |
the window and pane menus |
C-b / |
what a key does |
C-b : |
the command prompt — tmux commands, Tab completes |
C-b ? |
every key and what it does (list-keys -N) — or just pause after C-b and they show |
C-b d |
detach — everything keeps running |
Harness's additional actions use keys tmux leaves unbound. The stock close bindings above use
Harness's save-and-stop behavior; custom bindings and explicit kill-pane / kill-window
commands keep their existing tmux behavior.
A confirmed Stop removes that harness's other views across tabs and sessions too. Switching
agents from another attached hn client updates both views, with one replacement process.
C-b a / C-b A |
the next harness that needs you (next-harness) / all those waiting on you (M-1…9 answers from the list; M-a types an answer — an option's number, several for a multi-choice question, 1,3, or your own words) |
C-b N / C-b T |
New shell pane with the agent picker / a plain shell, on the focused pane's computer and directory. |
C-b I C-b @ C-b S |
models, machines, the Harness Store |
C-b g C-b B |
send a task (Harness picks the harness) / broadcast to the window |
C-b R C-b P C-b K |
restart, pause, clone the harness |
Clicking the footer + or a menu's New Harness opens a compact, centered form
with the task ready to type at the top. New Tab in the workspace menu opens the
GUI new-window screen, with the composer and recent sessions
below it. The tmux keyboard shortcuts continue opening shells.
Agent and Project follow, then Branch, Worktree, Model, Approvals and applicable Profile.
All settings are visible without expanding Options. Project reads project @ local, or
project @ machine for a remote destination; focusing it shows the full path below.
The initial destination is the connected local Harness machine, with successful agent
and project choices remembered. Explicit project commands keep their destination. Enter starts
with the displayed choices; the action names the selected agent (for example, Start Codex).
Tab/Shift-Tab moves between fields. Up/Down edits multiline tasks and moves to the previous/next
field at the first/last visual line. On other fields, it moves between fields and previews
their choices on the right. Enter, Right or typing enters a chooser; Enter accepts
an item and focuses Start. Enter in the task editor also focuses Start without launching.
Enter on Start launches. The harness opens in
the window that requested it, splitting beside the focused pane when needed. Switching windows
while it starts leaves your new window focused. Lowercase C-b n remains next window.
Escape backs out of a chooser or closes the popup without losing its draft. On New Window,
Escape leaves task editing; another Escape returns to the previous window and keeps the draft.
Agent combines coding agents and installed Store harnesses; a Store harness then offers its
compatible coding agents. Terminal is a separate action: C-b T opens a shell directly,
and Open Terminal on New Window is available by mouse. Neither sends task text to the shell.
Project offers Clone Repository, Open Folder, New Folder and recent
machine/folder pairs. Folder actions choose a machine first. Ctrl-L in the folder browser edits
a path. Project search includes the 50 most recently active distinct folders per machine;
duplicate sessions in one folder count once. Combine a machine name and folder, such as
office harness or m2 harness, in either order. The local machine's actual
name remains searchable when its label says local.
Task is edited directly in the form: Enter focuses Start, Alt-Enter inserts a newline, and pasted tasks
retain line breaks. Enhanced terminals can use Shift-Enter too. Arrow keys navigate wrapped
lines; Home/End, Ctrl-A/E, word movement/deletion, Ctrl-U/K and Ctrl-Y work in the editor.
On the welcome screen, C-b ] also pastes into the task, preserving its line breaks.
The popup keeps text-editor keys directly, as a tmux prompt does; Escape closes it with the draft kept.
Unicode graphemes stay intact. Escape preserves a dismissed dialog's task. Supported agents
receive it as their first message; an unavailable first task or one exceeding the daemon's
2,000-character limit is explained before launch. A blank task starts an ordinary session.
Git projects default to a new worktree from main, as on desktop; missing main requires a branch
choice. Models and profiles are checked on the selected machine before starting.

Rendered from the isolated terminal fixture in tests/new-harness.py.
The main form stays centered and fixed as agents, fields and choosers change. Choosers extend to its right; in narrow terminals they temporarily occupy the form's place. Escape returns through nested choosers and preserves a dismissed draft. Confirmed failures keep the draft and reuse any prepared project folder on retry. A lost reply offers Check status for the original launch; repeated Enter cannot start another harness while its outcome is unknown. Input in the form never reaches a working pane.
Mouse New Tab keeps a separate composer draft per window. A fresh startup opens
a shell, and C-b c opens a local shell with its agent picker. Explicitly selecting
a remote project in the GUI keeps that destination until you choose another
project; starting an agent or terminal never silently falls back to a different machine.
Submitting while the initial project check runs starts once it finishes. Escape, further
editing, or leaving the form cancels that pending start and keeps the draft.
Up to nine recent sessions appear below the composer, with fewer visible in short
terminals; Browse All Sessions opens
the full launcher. Existing Claude Code, Codex and other supported histories are discovered on
connected machines. Loading, empty and unavailable history have distinct states; Ctrl-R retries
discovery. Digits and plain-key bindings belong to the task while you type. Your modified prefix
(for example Ctrl-B) still switches windows and opens commands. With a plain prefix such as a
backtick, Tab to a setting first to use it for navigation. Open Terminal is explicit and
never sends the task to a shell. With the daemon offline, a task can be prepared while the local
terminal remains available. Existing workspaces still restore as usual. Harness OS keeps its
dedicated installation, network and first-launch actions.
In the harness and command lists, fzf's keys: C-j/C-k C-n/C-p move, Tab marks, C-/ toggles the preview,
S-↑/↓ scrolls it, M-/ wraps long rows (--wrap), C-a C-e C-w C-u edit the query. In the harness
list, enter adds a pane in the current window, C-t opens in a new window, C-v beside, C-x
below; an already-open harness is focused. In the command list, enter runs the command. esc
leaves. fzf's search syntax works
('exact ^prefix suffix$ !not a | b), and its colours follow FZF_DEFAULT_OPTS (--color=light,
16, bw). One key differs on purpose: fzf 0.67 binds ctrl-/ to toggle-wrap as well as alt-/,
but hn keeps C-/ for the preview, as fzf's own README binds ctrl-/ in its preview examples and
most people's fingers already know it. Its layout options apply too (--layout, --border and
--border-label, --margin, --padding, --info, --gap, --no-unicode, --preview-window);
--height docks a list at the bottom of the window, that many rows tall with the panes still in
view above it, where fzf would draw it under a prompt at the bottom of a terminal. The preview is
hn's own text about the row, so two of its defaults are hn's: its label is the row's name (unless
--preview-label gives one), and it wraps its text at spaces (unless --preview-window says
wrap, fzf's way with ↳, or nowrap). C-b s lays its preview out as
right,50%,<90(down,40%), your --preview-window after it, and the narrow one below 180 columns
takes your look too — so hidden hides it at every width.
Colours are the terminal's 16, as tmux's are, so hn reads on dark, light and Solarized themes.
At a glance
An agent already shows its own state in its pane: that it's working and for how long, each step, its sub-agents. hn repeats none of that. It shows what no single pane can: which of all your harnesses needs you, what each is doing or did, where, and for how long.
Every harness's state is one symbol, the same in its pane's title row, the window list and C-b s
(a plain shell has none). A window shows its most urgent pane's, and a window with a harness
waiting on you is reversed, as tmux shows a bell. A turn that ends while you are typing in another
pane counts as done and unread (✓) until you go to that pane.
⠹ (turning) |
working |
? |
needs you: a question or a permission |
✓ |
done, and you haven't looked yet |
· |
idle in lists; hidden in pane headers and tabs |
✗ |
failed |
◌ ‖ ○ |
starting, paused, offline |
- The status line counts the whole fleet:
?2 ✗1 ✓5 ⠹41means two need you, one failed, five are done and unread, and 41 are working. Idle ones aren't counted, and a state with none drops out. The right side keeps the quoted local machine name and the clock, with two spaces between groups. Branch and pull request context stay in the pane header. C-b slists every harness, the most urgent nearest the prompt: needs you, failed, done and unread, working, then the rest. Each row has one line: the question, what it is doing now (Run the unit tests, from its tool calls), what its last turn came to (the daemon's recap, else the first line of its final message), or why it failed (The agent did not start within 60 seconds.). Each row also has its pull request (#4812,#4807 draft,#4790 merged), its project when there are several, and how long it has been that way. Enter adds it as a pane in the current window, or focuses it if already open (C-tin a new window,C-v/C-xbeside or below,M-Enterin place of this pane). Typing filters as fzf does, by name, project, branch, machine, pull request ('4812) or state ('waiting,'failed,'done,'working,'idle). From the list, without opening it:M-mmarks it read (M-Mevery row shown),M-ssends it a message,M-rrestarts it,M-1…9/M-aanswer it; Enter adds marked rows as panes, whileC-topens a window each. The list stays ranked while it is open. The list reads newest first, each machine with its folders under it. A harness untouched for over 7 days, with nothing going on and not on screen, folds away behind the▸ N olderon its folder's heading (Enter or a click shows or hides them; a search always finds them). The keys line shows the main keys;?lists them all. The preview adds its final message whole, what it was last asked, its plan (its to-do list,✓done,▸doing), the sub-agents it has running, and what it has used (1.2M tokens · +340 −52 · 1 PR).- A session per project: in
C-b sthen#(the projects, each with its counts),C-tmakes a session named for the project with each of its harnesses in a window of its own (or goes to it and adds the ones it lacks). - Back after a while (the terminal's focus gone three minutes or more), hn says what changed:
While you were away (12m): ✓5 finished · ?2 need you · ✗1 failed — C-b a goes through them. C-b gsends a task to the harness it fits: at once when the router is sure (as the desktop does, 85% or more), else it lists the likely ones.C-b a(next-harness,-pthe other way) goes to the next harness that needs you, in that order, each once. It shows each in the same window, so a run through the queue doesn't pile up windows. Going there reads it, and the counts go down.
All of this is in options, which show -g, show -gw and C-b C print as they are:
status-left, status-right, the window formats and each pane's title row
(pane-border-format). Set them in your ~/.tmux.conf as you would for tmux; what you set
replaces hn's. The default is set -g @hn-look panes. set -g @hn-look classic restores hn's
previous line borders. set -g @hn-look tmux uses tmux's appearance and
content dimensions: no padding or title rows, and tmux's status line and window list. Changing
the look takes effect immediately and preserves pane identities and the split structure.
For your own formats: #{fleet} (the status line's counts, ready to drop into your theme) and
#{fleet_needs} #{fleet_failed} #{fleet_done} #{fleet_working} #{fleet_idle}, #{spinner},
#{pane_agent_icon} and #{pane_agent_state} (needs, working, done, idle, starting, failed,
paused, offline), #{pane_agent_mark} (the icon in its colour, as the title row draws it),
#{pane_heading} (the name, state and watcher label fitted to the pane header; #{pane_title}
stays complete), #{window_agent_icon} and #{window_agent_state} (its most urgent pane's), #{pane_project},
#{pane_branch}, #{pane_where} (machine:project ⎇ branch #123 as far as it fits beside the title;
local and remote machine prefixes yield to project, branch and PR context in narrow panes),
#{pane_pr} #{pane_pr_state} #{pane_pr_url} (the pull request for its branch), #{pane_tokens}
and #{fleet_tokens} (what it, and all of them, have used: 1.2M), #{pane_lines} (+340 −52),
#{pane_asked} and #{pane_did} (what it was last asked, and what its last turn came to),
#{pane_todos} (its plan's progress, 3/7) and #{pane_subagents} (how many it has running),
#{usage} (the agent accounts' rate limits on the focused pane's machine: claude 5h 42% week 18% · codex 5h 3%) and #{usage_high} (the one nearest its limit, from 80% used).
The status line uses #{usage_remaining_mark}: Claude 0% Codex 89%, showing remaining
allowance for every subscription with quota data, even when healthy. Each figure is the lowest
remaining percentage across that account's reported windows. Amber starts at 20% left, red at
0%; a nonzero allowance below 1% reads <1%. Shared account keys appear once across machines,
with the local reading preferred; different or unknown accounts stay separate. When a provider
has multiple accounts, extra remote accounts say Claude@studio 20% to distinguish them.
#{usage_remaining} provides the same figures without color. The daemon currently reads Claude
and Codex; Grok and other providers are not listed until a quota source is available. Existing
usage, usage_high and usage_high_mark formats retain their used-quota meaning for custom
configurations. Other formats:
#{local_machine} (this computer's name in the app),
#{pane_machine} (the focused pane's machine), #{pane_far} (another machine's), #{pane_watched} and #{pane_watcher}
(another window has the pane to type in, and who), and #{waiting} (the harnesses waiting on
you).
Graphical viewers
For a Blender, CAD, video or other domain harness, run view from C-b : or choose
open-viewer in the command list. The harness preview shows when its viewer is ready.
hn view # current hn pane
hn view -t 'My Blender scene' # by harness name or id, without opening a terminal pane
hn view -p -t 'My Blender scene' # print its URL, without launching a browser
hn view -c # copy its browser-app link through the terminal clipboard
hn view -w # open in the authenticated browser app even on this machine
On a local desktop, the current machine's viewer opens directly in your default browser.
Over SSH, hn prints a link you open on your own computer; it never launches a browser on the
SSH host. A harness on another linked machine uses the same browser-app link. Sign in as its
owner and link the machine if this browser has not done so before. The URL contains machine
and harness identifiers, not credentials, and does not grant access or create a public share.
The browser companion opens only that viewer. It does not restore your desk, attach a terminal,
or take the keyboard from hn. Closing either view leaves the harness running. Browser-based
remote viewers use Harness's existing encrypted interactive-viewer transport, which requires
Chrome or Chromium on the harness machine for rendering. Local direct viewers do not need that
renderer. A missing renderer is reported in the viewer with a retry action.
-p also works for scripts and terminals without clipboard support. Browser launch failure
prints the link instead. No tmux key bindings are changed.
From a shell
As tmux is: any tmux command, run in the client you have open, its output printed here.
hn display -p '#{pane_current_path}'
hn send-keys -t 1 'make test' Enter
hn capture-pane -p -t 0 | tail
hn list-panes -F '#{pane_index} #{pane_title}'
hn list-harnesses # every harness on every machine and its state (hn ls is list-sessions, as in tmux)
hn lsh -f '#{==:#{harness_state},needs}' -F '#{harness_name}: #{harness_question}' # who is waiting, and on what
hn send-message -t api 'run the tests' # a message to a harness, as a turn (hn send is send-keys, as in tmux)
hn answer -t 'Add rate' 2 # answer its question: the second choice (1,3 several; or your own words)
hn open-harness -h -s billing # a harness beside this pane (-v below; without either, a window of its own)
Harnesses have hooks as windows do: harness-needs runs when one asks, harness-done when one
ends a turn, harness-failed on an error — with #{hook_harness_name} #{hook_harness_line}
#{hook_harness_question} #{hook_harness_machine}. In a ~/.tmux.conf tmux reads too, keep them
inside %if (tmux doesn't know these hooks, and skips the block), and quote what a shell is given
with q: (names hold spaces and brackets):
%if "#{hn_version}"
set-hook -g harness-needs 'run-shell "notify #{q:hook_harness_name}"'
%endif
Copy mode
tmux's own (window-copy.c, ported): C-b [ takes a copy of the pane's screen and history, and
every key is looked up in the copy-mode-vi table (mode-keys vi) or copy-mode (emacs) and runs
tmux's command for it — so v Space Enter, C-Space C-e M-w, / ? n N, C-s
C-r (incremental), f t ; ,, 5k, %, { }, X M-x, the search marks and their
count, and your own bind -T copy-mode-vi … all do what they do in tmux. r takes the copy again
(output that arrived meanwhile is #{pane_unseen_changes}); q leaves.
What a command prints — C-b ?, C-b ~, :show -g, :list-windows, run-shell — opens in the
pane's view mode, as in tmux: the same keys move and search it, q closes it. The same list of
keys to search as you type, fzf-style, is C-b :keys (or hn keys from a shell).
Mouse and clipboard
The keyboard remains the primary path, and the same actions are reachable by mouse. Pane
headers show the agent and model as plain text controls, followed by … and × when there
is room. The menu keeps these actions available in narrow panes. Changing agents saves a
handoff and replaces the agent in the same pane; changing models targets the pane you chose,
even if focus moves while the picker is open. × uses the same safe Stop behavior as C-b x.
Right-click a pane header or window tab for its actions.
The status bar adds just + and …, plus Sign in when needed. + opens the GUI
New Harness composer. … opens New Harness, New Tab, the harness/machine/model counts and their lists,
Devices, Account, Appearance and Commands. Physical Harness devices are separate from machine
connections. Devices shows each owned host's connected devices and reported brightness, sound,
scrolling direction and voice language; settings are confirmed by the device before being shown
as saved. These settings use the existing firmware and CLI interfaces.
These controls follow mouse on, respect custom mouse bindings and leave custom status and
pane-title formats intact. Add #{hn_controls} to a custom status format to opt its footer into
the controls. mouse off, or the tmux appearance, keeps the keyboard-only presentation.
Commands such as workspace-menu, change-agent, models, hardware-devices and account
are also available from C-b :.
The terminal body keeps tmux's mouse: a click selects a pane or a window, a drag on a border (or a title row) resizes, a
drag in a pane selects and copies, a double-click copies a word and a triple-click a line, the
wheel scrolls back in copy mode, and the right button opens tmux's pane menu. Each is a key
binding you can change, as in tmux (bind -n WheelUpPane …, bind -T copy-mode-vi MouseDragEnd1Pane …); a program that asks for the mouse gets it. Hold ⇧ to select
with your terminal instead. Copying uses OSC 52, so it lands on the clipboard of the computer you
are sitting at, over SSH too.
Two windows, one harness
A terminal has one keyboard. Opening a harness another window is driving shows it read-only ("watching"); taking control here reclaims this TUI's panes across all tabs, and the other window starts watching. The first key typed into a watcher also takes control, preserving that key for its intended pane.
The dial
The Harness device, plugged into this computer: the daemon holds it, and hn is the window it talks to while the desktop app is not running. (With the app open, the app keeps the dial; hn still follows it while hn's terminal is the one in front.)
- Turn it to a harness: its pane is selected, in its window. A zoomed window stays zoomed, so the dial flips through panes full size.
- A finger on the glass scrolls the active pane the way tmux's wheel does: a shell's history in copy mode (left again at the bottom), a full-screen program its wheel or arrow keys, an open list its rows. A flick keeps going and slows down.
- Tap a notification: that harness comes forward, or opens in a new window.
- Pick a window on the dial: it is selected here.
- Speak on a harness and the words go to it. Speak with none chosen and hn routes them as
send-taskdoes: sent at once when the router is sure, otherwise the list asks (Enter sends, Esc cancels).
The dial turns through the panes of the window you are on, in pane order, and its window list is hn's windows.
Speed
Each pane's header shows its measured keystroke → echo latency. On this machine that is about a
millisecond. On another machine it is the network: when a pane measures slow (≥20ms), typed
characters are echoed locally — underlined until the far side confirms them, the way mosh does.
HARNESS_TUI_PREDICT=off turns that off, =always forces it on.
Your keys
~/.tmux.conf first (HARNESS_TUI_TMUX_CONF=off ignores it, =path reads another file); then
~/.config/harness/tui.toml for anything specific to Harness:
prefix = "C-a"
desk = "sync" # sync | read | off
predict = "auto" # auto | always | off
notify = true # OS notifications through the terminal
[keys] # the root table: no prefix
"M-h" = "select-pane -L"
"M-x" = "none"
hn --keys lists every binding, tmux-style, and reports problems in either file.
Models on Omarchy
On an Omarchy computer in Omagrid, a local model that is not running yet offers
[ Personal grid ] [ Omarchy community ] in its Models preview: ← and → choose (with nothing
searched), Enter runs it there. On the community grid it serves anyone in Omagrid and your harness
stays on its model; pick it under Shared with you to use it. A model that serves shows a
Grid │ Requests Out In Cached table of what this computer answered on each grid.
Other computers see none of this: set -g @hn-models-serving-os omarchy is the default, and
it takes macos, linux or all too.
Environment
| Variable | |
|---|---|
HARNESS_TUI_DESK=read |
show the desk's tabs, never change them |
HARNESS_TUI_DESK=off |
keep tabs to this window |
HARNESS_TUI_PREDICT |
off / always (see Speed) |
HARNESS_TUI_BIN |
the binary harness tui runs |
PORT |
the configured daemon port naming this user's private socket (default 18473) |
ADAPTER_DATA_DIR |
daemon state directory (default ~/.harness/cli/data); hn and the CLI must use the same one |
HN_DESKTOP=on / off |
whether the desktop app is running, instead of looking (see The dial) |
Building
cd tui && cargo build --release # target/release/harness-tui
cargo test
harness tui finds a dev build in tui/target/ on its own. hn contains code translated from tmux and
fzf and links the crates in Cargo.lock; their notices are in THIRD_PARTY_NOTICES.md, which the binary
carries (hn --licenses). After changing dependencies, run python3 scripts/notices.py (cargo test
fails until you do). Releases are built by
.github/workflows/release-tui.yml — static binaries for macOS (arm64, x64) and Linux (x64,
arm64, musl) with a checksummed manifest that harness tui --install verifies.
Layout of the code
| File | |
|---|---|
daemon.rs |
the private Unix-socket WebSocket per machine, requests, pushed frames |
proto.rs |
HTRL terminal frames (mirrors cli/src/lib/terminalBinary.ts) |
pane.rs |
one tile: alacritty_terminal grid, key/mouse encoding, selection, find, local echo |
app.rs |
all state: machines, streams, tabs, desk sync |
fleet.rs |
machines and harnesses, kept live from the daemon's frames |
input.rs |
keys, mouse, the launcher's modes and actions |
workspace_controls.rs / workspace_menu.rs |
pane and footer controls, stable action targets and compact menus |
session_close.rs / agent_switch.rs / workspace_events.rs |
save-and-stop lifecycle, agent handoff and view updates between local clients |
account.rs / account_scope.rs |
required sign-in and account-aware workspace restoration |
hardware.rs / workspace_resources.rs |
physical device settings and workspace counts |
dial.rs |
the Harness device: the ring and windows it turns through, its focus, scroll, taps and spoken tasks |
modal.rs / picker.rs |
the launcher's rows and its fzf matching (fzf.rs, ported from fzf) |
ui.rs |
drawing |
layout.rs |
the split tree |
mouse.rs |
tmux's mouse: events as mouse keys, drags, what a program in a pane is sent |