Hop from server to server without ever leaving your terminal.

What hop is

hop is a terminal UI over your SSH fleet. It holds one connection per host and opens everything else as extra channels on that same connection: more shells, an SFTP browser, an editor running on the remote box, and any tunnels you defined. Nothing is a new window, nothing re-authenticates, and leaving a pane never tears down what is inside it.

A status bar above the footer always tells you where you are and where your keystrokes are going — the host, the mode, the directory or file, and the machine behind the alias. That is the single most disorienting thing about a TUI that embeds other people’s programs, so it gets permanent screen space, directly above the keys that act on it.

Features

Install

One line, either platform. The script picks the archive for your OS and CPU, verifies its checksum, drops hop on your PATH and prints where it went.

# macOS / Linux -> /usr/local/bin, or ~/.local/bin when that is not writable
      curl -fsSL https://raw.githubusercontent.com/p-arndt/hop/main/scripts/install.sh | sh
      

# Windows -> %LOCALAPPDATA%\Programs\hop, added to your user PATH
      irm https://raw.githubusercontent.com/p-arndt/hop/main/scripts/install.ps1 | iex
      

Both take the same options — a specific release, a directory of your own:

sh scripts/install.sh --version 0.11.0 --dir ~/bin
      

.\scripts\install.ps1 -Version 0.11.0 -Dir C:\tools\bin -NoModifyPath
      

$HOP_INSTALL_DIR / $env:HOP_INSTALL_DIR sets the directory too. On unix the script never edits a shell profile: if the directory is not on your PATH it prints the one line to add. On Windows it appends to the user PATH in the registry unless you pass -NoModifyPath, so a new terminal has hop.

Prefer to do it by hand? Grab the archive from the latest release, unpack it and move the binary onto your PATH. Every release ships a hop_<version>_checksums.txt for sha256sum -c.

From source

Needs Go 1.26+ and optionally just ≥ 1.39.

git clone https://github.com/p-arndt/hop.git && cd hop
      just build          # -> ./hop   (or: go build -o hop .)
      just build-release  # stripped + version-stamped
      just install        # build it, then put it on your PATH
      

just install is the same installer with --from-source / -FromSource: it builds the checkout, stamps it with VERSION and the current commit, and installs it exactly where the downloading path would have.

Updating

hop self-update replaces the binary in place, wherever the installer put it — see Update.

Staying current

hop check-update   # is there a newer release?
      hop self-update    # download it, verify its checksum, swap this binary
      

self-update fetches the archive for your platform from the latest GitHub release, checks its SHA-256 against that release’s checksums.txt, and replaces the running binary atomically. On Windows the old hop.exe is renamed aside and swept up the next time hop starts. Source builds (version = dev) are refused: there is nothing to compare them against.

Quick start

hop            # launch the TUI
      

On a first run with no hosts, hop offers to import ~/.ssh/config for you: one enter and your list is full. Then, in the TUI: ↑/↓ to move, enter to connect, ctrl+o o to come back out. That is the whole model.

CLI

For when you are already in a shell.

Where things live

hop keeps its hosts in an OpenSSH config file of its own and adds a single Include hop.config line to the top of your ~/.ssh/config. Every host you save in hop is therefore a host ssh, scp and rsync can reach by the same alias, and a host you write into ~/.ssh/hop.config by hand shows up in hop. hop rewrites that file when you add, edit or remove a host, so comments inside it are not preserved — hosts you want hop to leave alone belong in ~/.ssh/config itself.

Anything OpenSSH has no keyword for — tags, groups, pin order, how often you connect — is hop’s own preference about a host, so it sits under the hosts key of config.json alongside the rest of your settings, out of ~/.ssh entirely. Losing that key costs your pins and ordering, never a host.

A missing or malformed config file starts hop on defaults rather than refusing to start.

Upgrading from a version that kept its hosts in SQLite? The first start converts <config dir>/hop/hop.db into the files above and leaves the database behind as hop.db.bak. Nothing deletes it.

The three modes

Every mode returns to the host list — from a pane with ctrl+o o, from the browser with ctrl+o, and from either with a double esc inside 400 ms. In the list itself esc esc is the last level out: it quits hop.

Two rows along the bottom say where you are and what to press. The status bar carries the place: the host, what you are doing on it, and the thing you are doing it to — the directory a shell is standing in, the file an editor tab holds, the listing the browser shows — with user@host:port and the tab count at its right-hand end. The footer below it is the key legend, and it is deliberately short: it names the keys the mode cannot be worked without, adds more as the window gets wider, and leaves the full table to ? (the key card), which opens on the section for the mode you are in.

Nothing here has to be memorised first. space opens the action menu on the host under the cursor and ctrl+k the palette for whatever mode you are in — both list what is possible and the key that does it, and how much hop keeps on screen without being asked is one setting (see Guidance).

Everything else works in all of them: the sidebar toggle, the settings popover, the tunnels, the mouse and the optional vim keys.

Two rules explain most of the keyboard:

• Inside a pane, ctrl+o is hop’s leader. It does nothing on its own and it is on no clock — it opens a menu in the footer and waits. ctrl+o o goes out.
• Outside a pane — in the browser, in a card — ctrl+o simply goes back. There is no remote program competing for keys there, so there is nothing to lead.
• Inside a pane, everything else is the remote’s. hop reserves as few keys as it can, because every one it takes is one the shell or editor no longer gets.

Navigation mode

Navigation — the host list

With vim keys on, j/k move, l connects as enter does, and h goes back as esc does.

Navigation mode

Import — the SSH config card

i opens the import card, a modal like the rest: one field, pre-filled with ~/.ssh/config, so the usual answer is a single enter.

The first run opens this card by itself: with no hosts yet and a ~/.ssh/config on disk, hop offers the import instead of showing an empty list. esc skips it — an empty list is not an error, and a adds a host by hand.

It stays bound once the list is full, because importing is a sync, not a one-time step: each host is upserted, so a re-import refreshes what the config knows (hostname, user, port, identity file, LocalForward/RemoteForward, ProxyCommand/ProxyJump) and leaves hosts hop added itself untouched. Wildcard patterns (Host *) are skipped. hop import [path] does exactly the same thing.

Navigation mode

Host keys and authentication

An unknown host key aborts the dial and shows a fingerprint card. y trusts it and retries, appending it to your usual ~/.ssh/known_hosts; n or esc trusts nothing. A mismatch — a key that changed on a host you already know — is always a hard error, never a prompt.

When the host asks for a password or a one-time code, a card opens by itself: enter submits or moves to the next question, tab/shift+tab move between fields, ctrl+u clears, and esc cancels the connect. The dial waits inside the handshake rather than restarting, because a one-time code is only good once — and you are asked once per host, since shells, SFTP, editors and tunnels all ride that one connection. Nothing is stored.

Terminal mode

Terminal — a live shell on a remote host

Several shells on one host

S in the host list, 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 a tab strip above the pane, which shows up only once there is a second shell to switch to. The new shell arrives focused.

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 list — 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.

Terminal mode

The leader — ctrl+o

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:

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+b and ctrl+g, which are otherwise held in every mode.

Terminal mode

Scrolling back through history

shift+↑ pauses the live shell and steps one line up into its scrollback; shift+pgup does it a page at a time. Both are deliberately chords a bare shell never sends, and both decline (falling through to the shell) when there is nothing to show: on the alt screen a full-screen program owns its own scrolling. The footer advertises shift+↑ scrollback exactly when the key is live.

Once paused, the keyboard drives the history viewport rather than the remote shell. The status bar says <host> › scrollback, and how far back you are reading is the ⇅ <offset>/<len> chip at its right-hand end.

The wheel enters and drives scrollback too, three lines a notch, and scrolling back down to the live bottom returns you to the shell. It keeps working while you are dragging out a selection: the view scrolls under the pointer and the selection grows with it. On the alt screen, where there is no history to show, a notch is sent on as ↑ / ↓ instead, so a full-screen program scrolls itself.

Terminal mode

How double-esc works, and what it costs

A lone esc is still forwarded to the shell. hop cannot know a second esc is coming without swallowing the first one and waiting out the timer, which would put a 400 ms lag on every esc you press in vim. So the rule is:

Browsing mode

Browsing — the SFTP file browser

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 a column, not a screen it takes over: it stays drawn while you read a file beside it, and tab and alt+t pass the keyboard between the two. ctrl+t gives the column’s width back to the file. Below 96 columns of room there is no space for both anyway, and the browser goes back to filling the pane while it has the keyboard.

Browsing mode

Editing — editor tabs

enter on a file opens it in an editor inside hop, in the content area beside the browser column, with a tab strip above it listing every open file. The tree stays on screen.

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 ctrl+o o 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 with their own tab strips. tab/alt+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.

Every mode

Actions — the menu and the palette

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, focus its shell 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+b finds the sidebar 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.

Every mode

Tunnels — port forwarding

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 status dot in the host list shows ⇄2 when two tunnels are up on that host.

Every mode

When a connection drops

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.

Every mode

The sidebar — ctrl+b

ctrl+b hides the host list and gives the whole window to the pane; ctrl+b again brings it back. It is bound in every mode except while a card is up — from a focused shell, from the browser, from an editor tab — because the moment you want the columns is the moment you are reading something wide on the far side of them. The terminals reflow to the new width immediately, both ways.

Every mode

Settings — the popover

, opens the settings card, floating over whatever is on screen. It works from the host list, from a pane and from the file browser. It is modal: while it is up, keys go to it.

Key	Action
↑ ↓ (k j)	move between settings
← → (h l)	pick a colour (accent), walk a profile, or flip a switch
enter i	edit the selected setting — or flip it, if it is a switch
enter esc ctrl+u	while editing: save / cancel / clear
r	reset the setting to its default
esc q ,	close

Every mode

The mouse

Every gesture is an existing binding reached by pointing, so nothing is mouse-only.

A selection is not limited to the screenful it started on: while the button is down the wheel scrolls the view under it and the selection grows, and a drag held against the top or bottom row of the pane scrolls by itself until you let go. A selection also rides the text it was made on, so scrolling leaves the highlight over the same words. Anything you type takes it down.

A remote program that asks for the mouse (vim with set mouse=a, htop) gets the pointer verbatim instead. The cards are keyboard-only. ctrl+g hands mouse reporting back to your terminal for a moment — for a selection spanning the sidebar and a pane, or anything else that wants your terminal’s own pointer.

Every mode

The rest of the keyboard

Copy and paste

Paste has no key of its own: paste the way your terminal pastes, and hop marks it as a paste for the remote program — which is what stops vim indenting a pasted block into a staircase. It works on Windows too.

Copying out of a pane is a drag (the mouse), or your terminal’s own selection after ctrl+g. A yank on the remote host travels to your clipboard over OSC 52, unless you turn Remote clipboard off. A remote asking to read your clipboard is never answered.

What hop takes from the remote

The full list, so there are no surprises: ctrl+o, ctrl+b, ctrl+g, shift+←/shift+→, shift+↑, shift+pgup, and the first esc of a double. Everything else reaches the program on the other end.

Two costs worth naming: a remote tmux never sees its own ctrl+b prefix through hop, and shift+←/shift+→ no longer reaches the remote as a selection motion.

macOS and the alt keys

hop’s own bindings are ctrl and shift chords, which every terminal sends — nothing below is needed to use hop.

The alt+… aliases are another matter. On macOS, Option+letter types a character (ø, é, ∑) instead of sending the ESC-prefixed meta key hop reads, so every alt+… binding is simply absent until the terminal is told otherwise:

• Terminal.app — Settings → Profiles → Keyboard → Use Option as Meta key
• iTerm2 — Settings → Profiles → Keys → Left Option key: Esc+
• Ghostty — macos-option-as-alt = true
• VS Code’s terminal — "terminal.integrated.macOptionIsMeta": true

This is also why shift+k/shift+j reorder pinned hosts, and why the sidebar is ctrl+b and the mouse toggle ctrl+g rather than the alt mnemonics they would otherwise be.

Every mode

Vim keys

Off until you turn them on, in the settings popover (, → Vim keys). Off, they are not bound to anything else either: a stray l in the host list does nothing at all. pgdn/pgup are not part of the switch — they page without being vim, so turning vim off never costs you a way to page.

Every mode

The cards

All of them are modal: while a card is up it takes every key, and esc closes it.

The keys card opens on the section for the mode you are in — the shell’s keys from a shell, the browser’s from the browser — and marks it you are here. That is what lets the footer stay short: it names the two or three keys a mode cannot be worked without and leaves the rest to this card, which is only a fair trade if the card starts where you are.

? reaches it from every mode hop owns the keyboard in. In a shell or an editor a bare ? is a question mark the remote is owed, so there it is ctrl+o ? — the same key, one level in.

The host form carries more than an address: a group, a default directory every session on that host starts in, an identity file, and ProxyCommand / ProxyJump for hosts you reach through a bastion. Renaming the alias keeps the host’s visit history, so it does not lose its place in the frecency order.

Development

just            # list recipes
      just run list   # go run . list
      just build      # dev binary
      just install    # build from source onto your PATH (scripts/install.sh|.ps1)
      just test       # go test ./...
      just test-e2e   # + the Docker 2FA end-to-end tests (needs Docker)
      just vet
      just fmt        # gofmt -w .
      just ci         # fmt-check + vet + test (what CI runs)
      just docs       # regenerate index.html, README.md and KEYBINDINGS.md from docs/
      just demo       # re-record assets/demo.gif + the stills (needs vhs)
      

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

Where a binding lives

The host list and the file browser move on the same keys, so they do not each spell that keyboard out. internal/keymap holds it: one table, one row per key, saying what the key means (a Motion), whether the vim setting owns it, and whether the host list binds it as well as the browser. Both views resolve keys through it — passing keymap.Full or keymap.List — and act on the motion they get back.

A mode with no motions of its own — the settings popover — asks keymap.Vim(key) instead, the same table answering the narrower question: is this a key the vim setting owns? That is why turning the setting off is one fact in the config rather than a flag threaded through three switch statements.

Roadmap

Shipped: embedded shells · multi-shell tabs · SFTP browser · remote editor tabs · scrollback · tunnels · ProxyCommand/ProxyJump · 2FA · reconnect · mouse · copy and paste · host management · host-key confirmation · SSH config import · live settings · uploads and file ops · async transfers · cross-platform releases.

Next up:

The living version, with far more detail on each item, is TODO.md.