Use
Recipes
Short stories about things people do with Hop, each with the commands. The machines are a laptop you sit at, tower (a Linux PC with a big graphics card) and studio (a Mac that is always on).
Get pinged when an agent is blocked
You have three coding agents running in sessions on tower and studio. Each one stops now and then to ask a question, and you only find out when you go and look.
A coding agent in a Hop session says what it is doing: working, blocked (waiting for you), done or error. hop events turns each change into a line. Pick out the blocked ones and show a notification:
hop events --types session.state --json | jq --unbuffered -r 'select(.state == "blocked") | "\(.session) on \(.machine) needs you"' | while read -r line; do hop notify "$line"; done
Behind the scenes, Hop looks at each machine's sessions every two seconds over its shared SSH connection and sends an event only when a state changes. Leave it running in a session of its own (hop new --name pinged --command "sh $PWD/pinged.sh") so it outlives the terminal.
hop notify shows it in Notification Center on a Mac, or the desktop's notifications on Linux. If the script runs on studio but you sit at the laptop, add --on laptop. The TypeScript SDK has the same as an example, sdk/ts/examples/notify-when-blocked.ts.
The Hop app does a version of this by itself: a tab gets a dot, and your desktop a notification, when a program in a tab you are not looking at finishes, fails or is waiting for an answer.
Wait for a server, then open it
You start the dev server on tower and want the page open as soon as it answers, not before.
$ hop do session.start tower --name dev --cwd '~/app' --command "npm run dev" $ hop wait tower:port/3000 --timeout 120 && hop open 3000 tower
hop wait checks tower's listening ports until 3000 is one of them, then exits 0, and hop open opens it in your browser through Hop's proxy. Nothing about tower's firewall changes. The server keeps running in the dev session: hop attach dev --on tower to see its output.
The same for a build:
$ hop do session.start tower --name build --cwd '~/game' --command "cargo build --release" $ hop wait tower:session/build ended --timeout 1800 && hop read build --on tower --lines 15
A session whose program says when it is done can be waited for with done (the default); a plain command, like this build, just ends.
Copy a project between machines
The game project lives on tower, and you want a copy on studio before trying something drastic. The two machines cannot reach each other directly, but the laptop reaches both.
$ hop ask "Copy ~/game from tower to studio?" && hop cp tower:~/game studio:~/backup/ $ hop run studio ls ~/backup/game
hop ask puts up a dialog and goes on only if you choose Yes. hop cp runs tar on tower, streams it through the laptop, and unpacks it on studio. Because ~/backup/ ends in /, the folder goes inside it (and backup is made if it is missing). Without the slash it would take the name backup.
A single file works the same, in any direction, with this computer as ~/…:
$ hop cp ~/Downloads/level.png tower:~/game/assets/
Everything passes through the computer running hop, so for a very large folder on a slow link, rsync between the two machines may be faster.
Drive an app by its buttons
An app on studio has no command line, but you want to script it. Hop reads the app's accessibility tree, the same one a screen reader uses, so a script can press buttons by name and not by position. Here is Calculator, read without touching it:
$ hop elements studio:window/Calculator Calculator — Calculator (230 × 408 points) window "Calculator" (0.5, 0.5) text "Edit field" = "0" (0.915, 0.262) button "Delete" (0.148, 0.385) button "All Clear" (0.383, 0.385) … button "7" (0.148, 0.517) button "Multiply" (0.852, 0.517) … $ hop find 'studio:Calculator >> button ~"ultipl"' #1 button "Multiply" at (0.852, 0.517)
Then press, and read the answer back:
$ for key in 6 Multiply 7 Equals; do hop press "studio:Calculator >> button \"$key\""; done $ hop find 'studio:Calculator >> text "Edit field"'
Each press brings the window to the front on studio and clicks the middle of that button. Someone sitting at studio would see it happen, so do this on screens nobody is using.
Apps that draw their own controls (games, Godot's editor, many cross-platform apps) show the system nothing but a window. For those, hop elements lists only the window; use keys and positions with window.act, or a picture with hop shot. Elements work on Macs today; Linux and Windows are coming.
Record it once, replay it anywhere
Doing the same clicks by hand on a second Mac? Record them while you do them through Hop, then replay the file there:
$ export HOP_RECORD=calc.jsonl $ hop press 'studio:Calculator >> button "6"' $ hop press 'studio:Calculator >> button "Multiply"' $ unset HOP_RECORD $ hop replay calc.jsonl --on server
Each step names the button by its selector, not by where it was, so it works on a screen of another size. Add hop wait 'studio:App >> text ~"Done"' while recording wherever the next step has to wait for something.
Morning status of every machine
Coffee, then one look at everything: which machines are up, how loaded, and what each session is doing.
#!/bin/sh
hop status
echo
hop call session.list '{}' | jq -r '
.machines[] | .machine as $m | .sessions[] |
"\($m)\t\(.name)\t\(if .state == "" then "-" else .state end)\t\(.title)"' | column -t -s "$(printf '\t')"
hop status asks every machine at the same time. session.list with no machine asks all of them too, and gives each session's name, state, title and folder as data.
These leave out git hosts such as github.com and gitlab.com unless you name them. Any other host in your ~/.ssh/config that is not a computer you use goes in hide in ~/.config/hop/config.toml; otherwise they wait 15 seconds for it and call it down.
Script a Godot export on another machine
Godot runs on tower, and exports take a while. You want to start one from the laptop, see it finish, and fetch the build.
$ hop do session.start tower --name export --cwd '~/game' \ --command "godot --headless --export-release 'Linux' build/game.x86_64" $ hop wait tower:session/export ended --timeout 1800 $ hop read export --on tower --lines 20 $ hop cp tower:~/game/build/ ~/Desktop/game-build/ $ hop notify "The Linux build is on the Desktop" --title Godot
The export runs in a session, so it keeps going if the laptop sleeps, and you can watch it in the Hop app (Machines → tower → export) or with hop attach export --on tower. The editor's own window can be shown too: hop window tower Godot.
Play a game from tower on the TV
tower has the graphics card; the TV is in the other room. The game should run on tower and show on the TV, with the controller in your hands.
In the Hop app on any computer: type the game's name in the new-tab box, and it starts on tower in a display of its own that nobody at tower's screen sees, drawn at the size of the pane. The picture is encoded on tower's graphics card; the controller you hold shows up on tower as an Xbox controller; the game's sound plays where you are. ⌖ captures the mouse and ⛶ goes full screen.
Hop for Apple TV is coming. Pair it once from a computer that stays on, then pick the window on the TV:
$ hop devices # the TV shows up here once Hop is open on it $ hop pair # type the six digits the TV shows; choose Allow on the TV $ hop serve # keep running
hop serve tells the TV what is open on every machine. When you pick a window, it starts that window's stream on tower and hands the TV the address and key. The pictures then go straight from tower to the TV over UDP, not through the computer running hop serve, unless the TV cannot reach tower directly.
An AI that works across all your machines
You want to ask "the tests pass on the laptop but fail on tower: why?" and have the agent go and look.
$ claude mcp add hop -- hop mcp
Now Claude Code can see every machine. For that question it would typically call machines, then context on tower (what is running, which folders are busy), start the tests there in a session with session_new, wait for it, and session_read the output. It can copy_path a file across to compare, and hop_open the session in a tab beside you so you can watch. See For AI for the tools and how they are kept safe.