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:

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.

AddressWhat it names
towerA machine
tower:~/proj/notes.mdA file or folder. tower:notes.md is in the home folder; tower:/etc/hosts is absolute
tower:session/buildA terminal session
tower:window/12An app window, by id (from hop windows)
tower:window/GodotThe front window of an app, by the app's name
tower:port/3000A 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/hostsA 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.

SelectorMatches
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" #2The 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.

LevelMeansExamples
readOnly lookshop status, hop windows, hop shot, hop find, hop wait
actWorks things as a person at the keyboard wouldtyping into a session, pressing a button, opening an app
riskyRuns any command, or writes or copies fileshop 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.

FromThe same command
A terminalhop windows tower or hop do window.list tower
A scripthop call window.list '{"machine":"tower"}'
A program{"id":1,"call":"window.list","args":{"machine":"tower"}} to hop api
An AI toolthe windows tool of hop mcp