2FA. The dial waits inside the handshake rather than restarting — a one-time code is only good once. One prompt per host, since shells, SFTP, editors and tunnels ride the same connection.

ProxyCommand. The command runs without a shell: a line needing one is refused with a clear error, so an imported config cannot smuggle in sh -c. %h %p %r %n are expanded. A ProxyJump may name another hop host by alias and borrows its user, port and key.

OSC 7. hop installs the prompt hook into bash/zsh itself — one line typed at the first prompt, then wiped from the pane, so the session looks untouched. Nothing is typed into a shell that already emits OSC 7, or while a full-screen program owns the screen. Where no directory can be learned, the key still opens the host in its default directory and says so.

Reconnect. Drops are found with keepalive probes rather than silence, so a suspended laptop or a dead VPN does not leave a pane quietly frozen.

esc never quits: a second one straight after the first is the same esc, and with no host in front there is nowhere to go back to, so it does nothing.

With vim keys on, j/k move, l opens a host out as → does, and h folds it up as ← does.

Two keys reach everything hop can do without knowing a single binding, and both of them show the key beside every line — so using them is how you stop needing them.

The menu is also a right-click on a host: the click stands the cursor on it and opens the menu in one gesture.

The menu is about the thing under the cursor. It lists only what that host can take right now — connect on an idle host, back to where you were on a live one, reconnect and reopen on one whose connection dropped, unpin it on a pinned one. ↑/↓ move, enter runs, esc closes and decides nothing.

The palette is about the mode you are in. In the host list it holds the host's actions and then hop's own; in the file browser it holds the browser's; in a shell or an editor tab it holds the chords behind the leader — which is the keyboard hardest to remember, and so the one it is worth most for. Type to narrow it: the search matches the label and the key, so a half-remembered ctrl+g finds the mouse toggle just as sft finds the browser.

Guidance — how much hop keeps on screen

The first time hop starts it asks one question: how much of its keyboard to keep on screen. Three answers, and every key works in all three — the profile changes what is shown, never what a key does.

hybrid is the default, and the one an escape from that first question picks. Change it any time with , → Guidance. An install that already had a config file is never asked: it keeps working exactly as it did, on hybrid.

Several shells on one host

S in the sidebar, or ctrl+o 0 from inside the pane, opens another shell on a host you are already connected to. It is a second channel on the connection hop already holds — no new handshake, no second authentication — and it appears as another tab under its host in the sidebar. The new shell arrives focused, at the full size of the content area, the same as the first.

Type exit to close a shell: its tab goes away, the rest keep running. When the last one exits, the connection is done and the host goes back to idle in the sidebar — unless its SFTP browser, an editor tab or a tunnel is still open on it, which keeps the connection alive. d still tears down the whole host at once.

The cursor

The pane draws the cursor itself — the emulator hands hop cells, not a cursor — and draws the one the remote asked for: a block, an underline or a bar (DECSCUSR, what vim switches between as you enter and leave insert mode), and no cursor at all while the program has it hidden (DECTCEM), the way a full-screen program hides it while it paints. A bar has no half-cell to stand in, so it is drawn as the thinnest glyph there is in place of the character; a full reset, and a program leaving the alternate screen, put the block back rather than leaving its shape behind.

Blinking is the one part that is yours: it is a clock hop has to run, so it is off until , → Cursor blink asks for it, and even then a cursor the remote asked to stand still does.

ctrl+o inside a pane has no effect of its own, and no timeout. It opens the leader, the footer becomes the menu, and hop waits as long as you take:

f and c follow the directory the shell reports as you cd. A shell that has not reported one (a login shell hop could not hook, or one still starting) leaves f opening the browser where it would anyway, and the status line says so.

A key that names no chord is swallowed, not passed to the remote: while the leader is open hop has the keyboard, and a program that received the tail of an abandoned chord would act on a key you were not typing at it. The leader also outranks ctrl+g, which is otherwise held in every mode.

Getting back to anything. ctrl+o space raises go to over whatever you are in. With nothing typed it is a tree: every open host with what is open on it under it — each shell tab with its directory, the browser, each editor tab by path, the terminal panel, its tunnels — numbered as ctrl+o 1 … 9 count them, then the hosts with nothing open. The cursor starts on the place you were in before this one, so ctrl+o space enter goes back there. Typing flattens it into one list, most recently used first, narrowed by host, path or name the way / narrows the sidebar. enter lands exactly on the row: that shell tab, that file, the panel. A host row lands where you last were on that host, connects one that has no session, and reconnects one that dropped; esc closes the card and changes nothing. ctrl+o tab is alt-tab for hosts: it goes back to the host you were on before this one, on the tab you left it on, and a second press comes back. ctrl+o → and ctrl+o ← step along the open hosts in the sidebar's order. The file browser opens go to with p.

With vim keys on the browser keeps the whole motion set (the host list only the step keys): j/k, gg, G, H/M/L, ctrl+d/ctrl+u, ctrl+f, plus l to descend and h to back out.

Anything that needs an answer — a name to rename to, a local path to upload, a yes before an overwrite — asks on the status line, and while the question is up every key is its answer: a , typed into a filename is a comma, not the settings popover. enter answers, esc cancels, ctrl+u clears the line.

Marks and the target

Every file operation is plural. space marks the entry and steps down, so a run of files is marked by holding it; a takes the whole directory. With nothing marked, an operation falls back to the entry under the cursor, which is why the single-file keys above still read the way they always did. Marks are keyed by absolute path and survive a refresh, so one inside a collapsed directory is still marked — the footer always names the total, so it cannot quietly follow you around.

Copying and moving need somewhere to go, and that somewhere is the target: t pins the directory under the cursor, the tree draws it in green, and c and v send the marked entries there. Nothing is ever typed as a path, and both ends stay on screen — that is what the tree column buys that a single listing could not.

Both ask before they destroy anything, as d and u already do: a name already taken in the target is a confirmed overwrite for c — the question names the files, since one answer covers all of them — and for v a refusal, because a move cannot clear the way without a recursive remote delete, so it says so before it starts rather than failing halfway through the batch. Anything in the selection that already lives in the target is simply skipped, and the outcome says how many, so a count short of what you marked explains itself.

A batch stops at the first failure and says where it stopped: delete b: permission denied — 1 of 4 done, 2 skipped. The marks stay up, so the same keystroke retries what is left.

Transfers run off the UI, so a large file no longer freezes the browser — the status line becomes a progress line until it lands, counting 3/7 · name.txt through a batch. Deleting asks first, and so does overwriting a file that is already in your download directory.

The browser is the files tab. Where the window has room for the sidebar, the tree lives there, in a box under the hosts, and the content area beside it previews the file under the cursor — the first 64 KiB of it, read on demand, with directories, binaries and anything larger described rather than read. On an editor tab the same tree box stays under the hosts beside the open file, and tab and ctrl+o t pass the keyboard between the two. Below 94 columns there is no docked sidebar, and the files tab draws the tree across the content area instead.

enter on a file opens it in an editor inside hop, in the content area, with its path above it. The tree stays on screen in the sidebar, under the hosts, and every open file is a tab under its host there.

How it works

The editor runs on the remote host, not locally: hop opens a second SSH channel on the connection it already has and runs ${EDITOR:-vi} <file> on a pty, then renders that pty in a pane exactly as it renders a remote shell. There is no download and no copy — you are editing the real file, and :w writes straight back to the server.

If the remote $EDITOR is unset (it usually is over SSH, since the rc-file that sets it is never sourced for a non-interactive command), hop probes the remote PATH for nvim, vim, vi, then nano, falling back to vi — POSIX requires it to exist.

Tabs are independent editor processes, so leaving with a double esc keeps them all running: come back and every file is where you left it, cursor included.

Two files side by side

\ in the browser opens the file **beside** the current one instead of behind it, splitting the content area into two halves, each with its file's path above it. tab/ctrl+o t pass the keyboard between tree and content; shift+→/shift+← cycle the tabs of whichever half has it. The same file is never shown in both halves — asking for one that is already open just focuses the half it is in. A content area too narrow to give each half a readable 22 columns declines the split rather than drawing two unreadable ones.

ctrl+\ folds the split back to one box, keeping whichever file the half you were in was showing — it is the counterpart to \, and it closes the split, not the file: every tab stays open and every editor keeps running. Closing the last tab in a half folds the split back too, but that is the long way round.

Editing locally instead

o is the escape hatch for files a terminal editor is no good for — a PDF, an image. It downloads the file to a scratch directory under the system temp dir and hands that copy to the desktop (start on Windows, open on macOS, xdg-open elsewhere), returning immediately so hop stays usable. Unlike enter, this edits a local copy: nothing is written back to the remote host. d downloads without opening anything.

Forwards are defined per host and ride the connection hop already holds, so a tunnel costs no extra handshake and no second authentication.

A definition is a direction (local or remote), a bind address and port, and the host and port to reach on the far side. LocalForward and RemoteForward lines are picked up by the SSH config import, so the forwards you already have keep working. Editing a running definition stops the old one on save, and a reconnect puts the set that was running back up.

The sidebar shows ⇄ 2 tunnels under a host that has two up, and enter on that line opens its manager.

Drops are found with keepalive probes rather than silence, so a suspended laptop or a dead VPN does not leave a pane quietly frozen.

The pane keeps the last screen the host drew, under a banner saying what happened, so the command that was running is still there to read. Nothing is forwarded to the far end, because there is no far end.

Shell tabs, the browser's directory and the running tunnels come back on reconnect. Editor tabs do not — an editor holds a buffer, and reopening the file on a fresh pty would look like nothing was lost — and the status says how many were left behind.

The docs. docs/*.md is the only source for the website, the README and the keybinding reference; tools/docsgen renders all three, and just ci fails if a generated file is out of date. Sections carry frontmatter saying where they belong, and a handful of fenced directives (:::cards, :::why, :::figure) cover the layouts markdown has no syntax for — each with a plain-markdown lowering, so the same section reads well on GitHub.

The justfile is deliberately universal: recipe bodies are plain commands that run under both sh and PowerShell, and the two that need real shell logic (fmt-check, clean) are split with [unix] / [windows] attributes.

The demo. just demo records the GIF and the stills on this page. scripts/demo.mjs builds hop, points HOME at a throwaway directory with a seeded host database, and starts tools/demoserver — a loopback-only SSH server that invents everything on screen: a fake shell with a table of canned command output, an in-memory filesystem over SFTP, and a fake vi. The keypress overlay in the corner is hop's own, compiled in only under -tags hopdemo (internal/tui/keycast.go), so a released binary does not carry it.

Testing. Headless tests drive the real Bubble Tea model with real keystrokes against in-process Go SSH/SFTP servers and temp-file stores — see internal/tui/hostmgmt_test.go, TestEmbeddedRoundTrip, TestSFTPRoundTrip. CI runs vet + test + build on a Windows / Linux / macOS matrix, because the agent transport and the local-open handler are per-platform: a single-OS run cannot tell whether the others still compile.

The 2FA end-to-end tests. An in-process server that answers whatever you tell it to proves nothing about real two-factor auth, so internal/dockerenv brings up Ubuntu with the real openssh-server and libpam-google-authenticator, listening four ways: code alone, hardened publickey,keyboard-interactive, password-then-code, and both offered as alternatives. The tests compute TOTP codes the way a phone does and log in, with wrong and expired codes as negative controls. Opt in with just test-e2e; without HOP_DOCKER_E2E=1 they skip.

Releasing.

just release          # patch bump: stamps VERSION, commits, tags, pushes
just release minor    # or major, or an explicit 1.0.0

The tag push triggers the release workflow: it gates on the three-OS test matrix, then cross-compiles all six targets (windows/linux/darwin × amd64/arm64) from one Linux runner, with checksums and a git-cliff changelog. Windows gets a .zip, everything else a .tar.gz so the exec bit survives.