Start
Concepts
Five ideas cover most of Hop: machines, addresses, sessions, levels and the current machine. Every command, in the CLI, for AI and for programs, uses them the same way.
Machines and local
A machine is a computer Hop can reach: any Host in your ~/.ssh/config, plus any you add in ~/.config/hop/config.toml. Its name is the one you would type after ssh, or the name you gave it in config.toml.
local is the computer Hop is running on: the one you are typing on. It is never reached over SSH: its commands run directly. Its own name means the same, so on tower, tower and local are both tower, and hop ls says which computer local is.
Names are your computer's view of the others: they come from your ~/.ssh/config and Hop's config. So after hop ssh tower, you are typing on tower, and there local is tower and the names are tower's own. exit brings you back.
Hop talks to a machine by running a short shell script on it over SSH and reading what the script prints. It keeps one shared SSH connection to each machine for ten minutes (OpenSSH's ControlMaster), so the second command to a machine does not sign in again. Nothing listens on the network on the other machine.
What needs Hop on the machine
Nothing, to begin with. A machine only needs to take SSH. Terminals, files, web pages and ports all work over plain SSH; a plain terminal ends when Hop closes, as any SSH session does.
Putting Hop on a machine (two programs in its ~/.local/bin, nothing that listens or starts at boot) adds:
- terminals that keep running when Hop closes, and the list of its sessions;
- what the AI agents in them are doing;
- workspaces saved on that machine;
- its app windows, shown and worked from elsewhere (
hop-windows).
Hop never puts itself anywhere on its own: only when you click Install daemon on the Machines page, Put it on … in a machine's App windows, or type hop daemon install tower. If you would rather it never offered, set Settings → Terminal → Install Hop on other machines to Never: the buttons and notes go, and your machines stay plain SSH. To keep just one machine that way, choose Keep Plain SSH in its menu (or hop call machine.edit '{"machine": "tower", "plain": true}'). A typed hop daemon install still works either way.
Asking a machine without Hop for something that needs it says what is missing, in a sentence, rather than failing: "Sessions on tower need Hop there: install it, or keep using plain terminals".
Addresses
An address names one thing on one machine. Every command that takes a thing takes an address, so they all read the same way.
| Address | What it names |
|---|---|
tower | A machine |
tower:~/proj/notes.md | A file or folder. tower:notes.md is in the home folder; tower:/etc/hosts is absolute |
tower:session/build | A terminal session |
tower:window/12 | An app window, by id (from hop windows) |
tower:window/Godot | The front window of an app, by the app's name |
tower:port/3000 | A listening TCP port |
studio:Calculator >> button "7" | An element in an app's window, found by a selector (on Macs for now) |
~/Downloads, ./x, /etc/hosts | A path on this computer (the same as local:~/Downloads) |
session/, window/ and port/ are words, not folders. A file really called that is written with its path: tower:~/window/x.
On the command line, an address fills in what it names. hop do session.read tower:session/build gives the command both the machine and the session's name.
Selectors
The part after >> picks elements of a window by what they are, not by where they are. Hop reads the window's accessibility tree (on a Mac, through hop-windows), so this works on the app's real buttons and fields.
| Selector | Matches |
|---|---|
button "Play" | A button named Play (the name matched whole, ignoring case) |
"Play" | Anything named Play |
button ~"Pla" | A button whose name contains Pla |
text ~"Export finished" | Any text containing those words |
button "OK" #2 | The second match |
group "Sidebar" >> button "New" | A New button inside the Sidebar group |
Roles are Hop's own words, the same on every system: button, field, text, checkbox, radio, menu, menuitem, link, tab, list, listitem, image, window, group, slider and other.
When a selector matches more than one element, pressing or filling it refuses rather than guessing; add #n to say which. A password field's value is never read out.
Sessions that keep running
A session is a terminal that lives on its machine, not in a window. The Hop daemon on that machine holds it, so it keeps running when you close the app, put the laptop to sleep or lose the network. Open it again from any computer, the app, the hub in a browser or the command line, and it is as you left it. There is no tmux or screen involved.
That is the difference from hop ssh, which is a plain SSH shell: it ends when you close it, and tmux or anything else you start in it is that machine's own, as with any SSH. Hop's app does not show it. Use a session (hop attach build --on tower) for a terminal that should keep running and show up in Hop.
A program in a session can say what it is doing: working, blocked (waiting for a person), done or error. Coding agents and builds do. Hop shows that as a dot on the tab, lists it in hop sessions, and sends it as a session.state event, which is how you get pinged when an agent needs you.
When the connection to a machine drops (the laptop slept, the Wi-Fi changed), Hop notices within 15 seconds, and a session's tab connects again by itself as soon as it can, showing it as you left it.
A machine needs the Hop daemon to hold sessions: hop daemon install tower puts it there (with the window helper), from this computer when tower is the same kind of computer, and otherwise from the builds for other kinds that install.sh makes when Zig is installed: Linux on Intel/AMD and ARM, from a Mac or from Linux, and hop daemon status tower says whether it is. It starts by itself with the first session and stops with hop daemon stop.
Levels: read, act, risky
Every command has a level, which says how much it can change.
| Level | Means | Examples |
|---|---|---|
| read | Only looks | hop status, hop windows, hop shot, hop find, hop wait |
| act | Works things as a person at the keyboard would | typing into a session, pressing a button, opening an app |
| risky | Runs any command, or writes or copies files | hop run, hop write, hop cp |
You, at the command line, can do anything at any level, the same as with ssh. Levels matter for other programs: the HTTP API gives each program a token that allows some levels on some machines, and refuses the rest. The reference gives every command's level.
The current machine
A command that needs a machine and was given none uses the current one. It starts as local; hop use changes it, and hop ls marks it with a dot.
$ hop use tower current machine: tower $ hop ports # tower's ports now $ ls # still this computer: hop use only changes hop commands $ hop use local # back to this computer
The current machine is kept in Hop's folder (~/.config/hop/current), so it holds for every terminal until you change it.
One list of commands
Everything Hop can do is one list of commands in a library, libhop. Each has a name (noun.verb, like window.list), a one-line summary, its arguments, its level and what it returns, which is always a JSON object. The command line, AI tools, hop api and these docs are all made from that list, so a command works the same way from each of them.
| From | The same command |
|---|---|
| A terminal | hop windows tower or hop do window.list tower |
| A script | hop call window.list '{"machine":"tower"}' |
| A program | {"id":1,"call":"window.list","args":{"machine":"tower"}} to hop api |
| An AI tool | the windows tool of hop mcp |