Reference
Command reference
Every command Hop has: 84 of them, protocol version 1. This page is made from hop api schema, Hop's own list, so it says what the code does.
Use any of them from a terminal as hop do <name> (some have a short form, such as hop windows), from a script as hop call <name> '<json>', from a program through hop api, and from AI tools through hop mcp by the tool name given. Levels: read only looks, act works things as a person at the keyboard would, risky runs commands or writes and copies files.
An address names a thing on a machine: tower, tower:~/notes.md, tower:session/build, tower:window/12, tower:window/Godot, tower:port/3000, studio:Calculator >> button "7". See Concepts.
All commands
| Command | Level | What it does |
|---|---|---|
machine.list | read | The computers Hop can reach |
machine.context | read | What is going on on a machine: apps, programs, folders, ports, sessions |
machine.status | read | Whether each machine is up, its load, battery and Hop helpers |
machine.edit | risky | Change a machine's name, or the user, address or port Hop signs in to it with |
session.list | read | The terminal sessions on a machine, or on every machine |
session.read | read | What a session shows, as plain text |
session.send | act | Type into a session |
session.start | act | Start a terminal session that keeps running on its machine |
session.end | act | End a session and whatever runs in it |
session.end_all | act | End every session on a machine |
shell.run | risky | Run a shell command on a machine and return what it printed |
file.read | read | Read a file (up to 2 MB) or list a folder on a machine |
file.write | risky | Write a file on a machine (replacing it whole) |
file.copy | risky | Copy a file or folder from one machine to another (or within one) |
file.list | read | A folder's entries on a machine, each with its kind, size and date |
file.find | read | Where a relative path a program printed is, on a machine |
file.search | read | Files and folders under a folder whose name holds some text |
file.move | risky | Move or rename a file or folder on a machine |
file.mkdir | risky | Make a folder on a machine |
file.trash | risky | Put a file or folder in a machine's trash, from where file.restore puts it back |
file.restore | risky | Put a file or folder back out of a machine's trash |
file.open | act | Open a file with a machine's own app, on that machine's screen |
file.sync | risky | Make a folder like another, on one machine or between two (rsync, one way) |
port.list | read | The TCP ports something is listening on, on a machine |
window.list | read | The app windows open on a machine's screen |
window.look | read | A picture of one app window |
window.elements | read | What one app window holds: its buttons, fields, menus and text |
window.act | act | Work one app window with the mouse and keyboard |
window.close | act | Close an app window: its app is asked to quit |
app.list | read | The apps installed on a machine |
app.open | act | Open an app on a machine and give its window's id |
app.hidden | read | The apps a machine runs out of sight, in displays of Hop's own |
app.quit | act | Quit an app a machine runs out of sight |
app.reveal | act | Move an app a machine runs out of sight to that machine's own screen |
app.icons | read | The icons of apps installed on a machine |
view.state | read | What the Hop window has open: tabs, panes, which is in front |
view.open | act | Open a terminal, page, folder, window or app in a new tab |
view.popup | risky | Run a command in a terminal floating over the Hop app, gone when it ends |
view.show | act | Bring a tab, pane, machine's tabs or page to the front |
view.close | act | Close a tab or pane (its session keeps running) |
view.command | act | Do one of the window's own commands, or list them |
view.run | act | Do anything the window can by its action id, or list every action |
view.keys | act | Press the window's own shortcuts |
view.settings | act | Read every setting, read one, or change one |
view.elements | read | What is on the window's screen to press or fill, each with a ref |
view.press | act | Press something view.elements listed |
view.fill | act | Type into a field view.elements listed |
view.search | read | Search everything the window knows, as its search box does |
view.type | act | Type into a pane: a terminal or an app window |
view.act | act | Work an app window shown in a pane with the mouse and keys |
view.look | read | See a pane as the person does: a picture, or a terminal's lines |
folder.list | read | The folders a machine knows of, best first, to find one by name |
event.watch | read | Stream changes on machines: sessions, windows, ports, up and down |
wait | read | Wait until something is so: a session done, a port open, a window, a machine |
element.find | read | Find elements in a window by what they are: button "Play" |
element.press | act | Press an element: a button, link, checkbox or menu item |
element.fill | act | Type into a field, replacing what it held |
person.notify | act | Show the person a notification on a machine's screen |
person.ask | act | Ask the person a question on a machine's screen and wait for the answer |
permission.list | read | What Hop may do on each machine, what is missing, and how to fix it |
permission.set | risky | Turn seeing or working a machine's windows on or off in Hop |
permission.ask | act | Ask a Mac's person to let Hop see and work its windows |
steps.run | risky | Run a list of Hop calls in order, on the machines they name or others |
mcp.add | risky | Connect the AI apps on a machine to Hop (adds Hop's MCP server to each) |
font.list | read | The fonts installed on a machine, and which are monospaced |
workspace.list | read | The workspaces kept on a machine, or on every machine |
workspace.get | read | One workspace: its windows and what each pane shows |
workspace.save | act | Keep a workspace on a machine |
workspace.remove | act | Forget a workspace kept on a machine |
workspace.folders | read | Project folders on a machine, or on every machine, to start a workspace in |
usage.list | read | How much of their plans' limits the AI programs on a machine have used |
pad.list | read | Which machines take game controllers, and the map each uses |
pad.map.get | read | What a controller's buttons and sticks do on a machine, or in one app there |
pad.map.set | act | Change what a controller does on a machine, or in one app there |
agent.list | read | Every AI agent in a terminal, on every machine: working, needs you, done |
agent.report | act | Tell a machine's daemon what an AI agent in a session is doing |
agent.hooks.add | risky | Have the AI agents on a machine tell Hop each step they take (their hooks) |
agent.hooks.remove | risky | Take Hop's hooks out of the AI agents' settings on a machine |
agent.kinds | read | The kinds of AI agent a machine's Hop knows, built in and taught |
agent.kind.add | act | Teach a machine's Hop an AI agent it does not know, with no code |
agent.kind.remove | act | Forget an AI agent a machine's Hop was taught |
approval.list | read | The calls waiting on a machine for you to say yes |
approval.answer | never | Say yes or no to a call waiting on a machine |
daemon.restart | act | Have a machine's daemon become the Hop installed there now, keeping its sessions |
machine
The computers Hop reaches, and how each is doing.
machine.list read
The computers Hop can reach
List the computers Hop can reach. "local" is the one this runs on. Each has its SSH host key's fingerprint (host_key, "SHA256:…", and host_key_type) when Hop knows it: who the machine is, whatever it is called. One that is another entry's machine again, under a second name or route and as the same account, says so with same_as naming that entry, so it can be shown once. One kept plain SSH (machine.edit's plain) says plain: true: Hop does not offer to put itself there.
It takes no arguments.
$ hop do machine.list
{"id":1,"call":"machine.list","args":{}}
machine.context read
What is going on on a machine: apps, programs, folders, ports, sessions
What is going on on a machine right now, in one read: its system, the apps open on it, the busiest programs, the folders work is happening in, listening ports, and its sessions. Start here to get your bearings on a machine. With its SSH host key's fingerprint (host_key, host_key_type), as machine.list has it.
| Argument | Kind | What | |
|---|---|---|---|
machine | text | needed | Machine to look at |
$ hop do machine.context <machine>
{"id":1,"call":"machine.context","args":{"machine":"tower"}}
machine.status read
Whether each machine is up, its load, battery and Hop helpers
Whether each machine (or one) answers, and if so its system, load, processors, battery, uptime, whether Hop's helpers are there, and its SSH host key's fingerprint (host_key, host_key_type), read from the machine just now. Machines are asked at the same time; one that is off or asleep says so instead of holding up the rest.
| Argument | Kind | What | |
|---|---|---|---|
machine | text | Machine to ask; leave out for all of them |
$ hop status [--option value…] $ hop do machine.status [--option value…]
{"id":1,"call":"machine.status","args":{}}
machine.edit risky
Change a machine's name, or the user, address or port Hop signs in to it with
Change a machine Hop keeps: its name, and where SSH goes for it. Give the address whole (address: host, user@host, user@host:port, or a Host from ~/.ssh/config, which then decides the user and port), or change one part of it (user, host, port); what is not given stays as it was. An empty user, or port 0, leaves that to ssh (the SSH config, or the user here and port 22). Background work tries the machine again at once. plain true keeps it plain SSH: Hop never offers to put itself there (its daemon, hop-windows), and what needs Hop says what works without it instead; false lets Hop offer again. Example: machine tower, user root, port 2222.
| Argument | Kind | What | |
|---|---|---|---|
machine | text | needed | The machine to change |
name | text | Its new name in Hop | |
address | text | Where SSH goes, whole: host, user@host, user@host:port, or a Host from ~/.ssh/config | |
user | text | The user to sign in as; empty to leave it to ssh | |
host | text | Its host name or IP address | |
port | number | The port SSH listens on; 0 to leave it to ssh (22, unless the SSH config says) | |
plain | true/false | Keep it plain SSH: Hop never offers to install itself there (true), or may again (false) |
$ hop do machine.edit <machine> [--option value…]
{"id":1,"call":"machine.edit","args":{"machine":"tower"}}
session
Terminals that keep running on their machine, whatever is looking at them.
session.list read
The terminal sessions on a machine, or on every machine
List the terminal sessions running on a machine (or on every machine): name, title, folder, and what the program in it says it is doing (working, blocked = waiting for a person, done, error, attention). Each machine's entry says whether it has Hop's helper (helper), which holds sessions; one that could not be asked has an error instead. daemon, when its daemon says, is {pid, program, update}: update is true when a newer Hop has been installed there than the daemon runs, which daemon.restart makes it without ending any session.
| Argument | Kind | What | |
|---|---|---|---|
machine | text | Machine to ask; leave out for all of them |
$ hop do session.list [--option value…]
{"id":1,"call":"session.list","args":{}}
session.read read
What a session shows, as plain text
Read what a session shows: its last lines as plain text, scrolled-off history included.
| Argument | Kind | What | |
|---|---|---|---|
machine | text | needed | Machine the session is on |
name | text | needed | Session name |
lines | number | How many lines from the end (default 80) |
$ hop do session.read <machine> <name> [--option value…]
{"id":1,"call":"session.read","args":{"machine":"tower","name":"build"}}
session.send act
Type into a session
Type text into a session, as if at its keyboard. With enter, press Enter after it.
| Argument | Kind | What | |
|---|---|---|---|
machine | text | needed | Machine the session is on |
name | text | needed | Session name |
text | text | needed | What to type |
enter | true/false | Press Enter afterwards (default true) |
$ hop do session.send <machine> <name> <text> [--option value…]
{"id":1,"call":"session.send","args":{"machine":"tower","name":"build","text":"make test"}}
session.start act
Start a terminal session that keeps running on its machine
Start a terminal session on a machine that keeps running there. Without a command it is a login shell; with one, it ends when the command does. Returns the session's name. The person can open it in Hop to watch.
| Argument | Kind | What | |
|---|---|---|---|
machine | text | needed | Machine to start it on |
command | text | Shell command to run in it | |
cwd | text | Folder to start in (default: home) | |
name | text | Name for it: letters, digits, - and _ | |
history | number | Lines it keeps to scroll back (default 5000) |
$ hop do session.start <machine> [--option value…]
{"id":1,"call":"session.start","args":{"machine":"tower"}}
session.end act
End a session and whatever runs in it
End a session and whatever is running in it.
| Argument | Kind | What | |
|---|---|---|---|
machine | text | needed | Machine the session is on |
name | text | needed | Session name |
$ hop do session.end <machine> <name>
{"id":1,"call":"session.end","args":{"machine":"tower","name":"build"}}
session.end_all act
End every session on a machine
End every session on a machine and whatever is running in each. The machine's Hop daemon keeps running, so new sessions can start at once. Returns the names of the sessions that ended.
| Argument | Kind | What | |
|---|---|---|---|
machine | text | needed | Machine whose sessions to end |
$ hop do session.end_all <machine>
{"id":1,"call":"session.end_all","args":{"machine":"tower"}}
shell
Running one command on a machine.
shell.run risky
Run a shell command on a machine and return what it printed
Run a shell command on a machine and return what it printed. It is stopped after timeout seconds (600 unless given). For something long, or that a person should watch, use session.start instead.
| Argument | Kind | What | |
|---|---|---|---|
machine | text | needed | Machine to run it on |
command | text | needed | Shell command |
timeout | number | Seconds to wait before stopping it (default 600) |
$ hop run <machine> <command> [--option value…] $ hop do shell.run <machine> <command> [--option value…]
{"id":1,"call":"shell.run","args":{"machine":"tower","command":"uname -a"}}
file
Reading, writing and copying files on any machine.
file.read read
Read a file (up to 2 MB) or list a folder on a machine
Read a file (up to 2 MB) or list a folder on a machine. ~ is the home folder there. With limit, only the start of a file is read, and the answer also gives its whole size and whether there is more.
| Argument | Kind | What | |
|---|---|---|---|
machine | text | needed | Machine the path is on |
path | text | needed | File or folder |
limit | number | Read at most this many bytes of a file (2 MB at most) |
$ hop do file.read <machine> <path> [--option value…]
{"id":1,"call":"file.read","args":{"machine":"tower","path":"~/notes.md"}}
file.write risky
Write a file on a machine (replacing it whole)
Write a file on a machine, replacing what it held, as one step (no half-written file is ever seen). to is an address such as tower:~/notes.md (or ~/notes.md on this device); the folder it is in is made when missing. Give the contents as text, or as base64 for anything that is not text.
| Argument | Kind | What | |
|---|---|---|---|
to | address | needed | Where: machine:path, such as tower:~/proj/notes.md |
text | text | The contents, as text | |
base64 | text | The contents, as base64, for bytes that are not text |
$ hop write <to> [--option value…] $ hop do file.write <to> [--option value…]
{"id":1,"call":"file.write","args":{"to":"tower:~/notes.md"}}
file.copy risky
Copy a file or folder from one machine to another (or within one)
Copy a file or a whole folder from one machine to another, or within one: from and to are addresses such as tower:~/proj and studio:~/backup/ (or paths on this device). When to ends in / or is a folder that exists, what is copied goes inside it (the folder is made when missing); otherwise it takes that name. The two machines do not have to reach each other: the copy passes through the device this runs on.
| Argument | Kind | What | |
|---|---|---|---|
from | address | needed | What to copy: machine:path |
to | address | needed | Where to: machine:path (an existing folder, or a new name) |
$ hop cp <from> <to> $ hop do file.copy <from> <to>
{"id":1,"call":"file.copy","args":{"from":"tower:~/proj","to":"studio:~/backup/"}}
file.list read
A folder's entries on a machine, each with its kind, size and date
List a folder on a machine as entries: each with its name, whether it is a folder (dir; a link to a folder counts), where a link goes (link), its size in bytes and when it last changed, as ls says it. folder is an address such as tower:~/proj (tower alone is its home folder). path in the result is the folder in full on that machine, so ~ comes back resolved. For the listing as text, use file.read.
| Argument | Kind | What | |
|---|---|---|---|
folder | address | needed | The folder: machine:path, such as tower:~/proj |
$ hop do file.list <folder>
{"id":1,"call":"file.list","args":{"folder":"…"}}
file.find read
Where a relative path a program printed is, on a machine
Find where a relative path is on a machine: a program in a terminal prints src/main.rs:12 without saying which folder it is in. Looks in the folders the person's programs there are working in (their shells, editors, coding agents), and gives the first that holds it, in full; path is null when none does. path is not an address but the words the program printed, so the machine is said on its own.
| Argument | Kind | What | |
|---|---|---|---|
machine | text | needed | Machine to look on |
path | text | needed | The relative path as printed, such as src/main.rs |
$ hop do file.find <machine> <path>
{"id":1,"call":"file.find","args":{"machine":"tower","path":"~/notes.md"}}
file.search read
Files and folders under a folder whose name holds some text
Search a folder on a machine, and everything under it, for files and folders whose name holds query (whatever its case). folder is an address such as tower:~/proj. At most 200 come back, as paths relative to the folder: found lists them, and entries says of each whether it is a folder (dir). An index is asked first where the machine keeps one (Spotlight's mdfind on a Mac, plocate), then fd, then find, for a few seconds at most; by says which answered. The big generated folders (.git, node_modules, target, .cache) are not looked into, nor hidden ones unless query starts with a dot, nor, on a Mac, the home folder's guarded folders (Documents, Desktop…) but through Spotlight.
| Argument | Kind | What | |
|---|---|---|---|
folder | address | needed | The folder to search: machine:path, such as tower:~/proj |
query | text | needed | Text the name must hold |
$ hop do file.search <folder> <query>
{"id":1,"call":"file.search","args":{"folder":"…","query":"tower 3000"}}
file.move risky
Move or rename a file or folder on a machine
Move or rename a file or folder on one machine. from and to are addresses such as tower:~/notes.md and tower:~/old/ (both on the same machine; between machines, file.copy then file.trash). When to ends in /, what moves goes inside that folder (made when missing) and keeps its name; otherwise to is its new path. Nothing already there is ever replaced: the move is refused instead. A link moves as a link. Paths may not hold ... The answer gives both paths in full, so the move can be undone by moving to back to from.
| Argument | Kind | What | |
|---|---|---|---|
from | address | needed | What to move: machine:path |
to | address | needed | Its new path, or a folder ending in / to move it into |
$ hop mv <from> <to> $ hop do file.move <from> <to>
{"id":1,"call":"file.move","args":{"from":"tower:~/proj","to":"studio:~/backup/"}}
file.mkdir risky
Make a folder on a machine
Make a folder on a machine, and any folders above it that are missing. folder is an address such as tower:~/proj/new. With unique, a folder already there is left alone and a new one is made beside it with a number added (new 2, new 3…), as a file manager's New Folder does; without it, one already there is fine (made is false). The answer gives the folder in full.
| Argument | Kind | What | |
|---|---|---|---|
folder | address | needed | The folder to make: machine:path |
unique | true/false | Never use a folder already there: add a number to the name instead |
$ hop mkdir <folder> [--option value…] $ hop do file.mkdir <folder> [--option value…]
{"id":1,"call":"file.mkdir","args":{"folder":"…"}}
file.trash risky
Put a file or folder in a machine's trash, from where file.restore puts it back
Put a file or folder in the trash of the machine it is on, rather than deleting it: on a Mac the Trash (with the system's trash where it has one, so Finder can put it back too), on Linux the desktop's trash (~/.local/share/Trash, as the freedesktop.org spec says, so the file manager lists it with where it came from). path is an address such as tower:~/old.txt. A link goes in as a link; paths may not hold .., and the home folder and the top of the file system are refused. The answer says where it came from and where it is now (trashed), for file.restore.
| Argument | Kind | What | |
|---|---|---|---|
path | address | needed | What to put in the trash: machine:path |
$ hop trash <path> $ hop do file.trash <path>
{"id":1,"call":"file.trash","args":{"path":"~/notes.md"}}
file.restore risky
Put a file or folder back out of a machine's trash
Put back something file.trash (or the machine's file manager) put in the trash. trashed is where it is in the trash, as file.trash answered (tower:~/.local/share/Trash/files/old.txt). It goes back where it came from, as the trash noted it, or to to when given; the folder it goes in is made when missing. Nothing already there is replaced: the restore is refused instead. Only things in the machine's trash can be restored this way.
| Argument | Kind | What | |
|---|---|---|---|
trashed | address | needed | Where it is in the trash: machine:path |
to | address | Where to put it, when not where it came from (the same machine) |
$ hop do file.restore <trashed> [--option value…]
{"id":1,"call":"file.restore","args":{"trashed":"…"}}
file.open act
Open a file with a machine's own app, on that machine's screen
Open a file or folder on a machine with the app that machine opens it with (open on a Mac, xdg-open on Linux), on that machine's own screen, as double-clicking it there would. path is an address such as tower:~/song.mp3. An app, a script or a shortcut opened this way runs.
| Argument | Kind | What | |
|---|---|---|---|
path | address | needed | What to open: machine:path |
$ hop do file.open <path>
{"id":1,"call":"file.open","args":{"path":"~/notes.md"}}
file.sync risky
Make a folder like another, on one machine or between two (rsync, one way)
Make the folder to like the folder from, one way, with rsync: what is new or changed in from is copied over, and nothing in from changes. from and to are addresses such as tower:~/proj and studio:~/proj, on one machine or two. Between two machines it runs on the sending one when that one reaches the other over SSH (checked to be the same machine and user); otherwise through the device this runs on, which keeps a copy of from to send from (in ~/.cache/hop/sync). dry_run says what would change and changes nothing in to (through this device it still brings from here, to compare against). delete also deletes what is in to but not in from, as a mirror does; it is refused for a home folder or the top of the file system. exclude lists files and folders to leave alone, as rsync's patterns (node_modules, .git, *.log). The answer lists the changes, each added, changed or deleted with its path inside the folder and dir for folders (at most 1000; more says how many are left out), counts them, and says how it ran. Needs rsync on the machines it runs on.
| Argument | Kind | What | |
|---|---|---|---|
from | address | needed | The folder to copy from: machine:path |
to | address | needed | The folder to make like it: machine:path (made when missing) |
dry_run | true/false | Only say what would change | |
delete | true/false | Also delete what is in to but not in from (a mirror) | |
exclude | list | Names or rsync patterns to leave alone: ["node_modules", ".git"] |
$ hop sync <from> <to> [--option value…] $ hop do file.sync <from> <to> [--option value…]
{"id":1,"call":"file.sync","args":{"from":"tower:~/proj","to":"studio:~/backup/"}}
port
What is listening on a machine.
port.list read
The TCP ports something is listening on, on a machine
List the TCP ports something is listening on, on a machine, with the program behind each.
| Argument | Kind | What | |
|---|---|---|---|
machine | text | needed | Machine to ask |
$ hop ports <machine> $ hop do port.list <machine>
{"id":1,"call":"port.list","args":{"machine":"tower"}}
window
App windows on a machine's screen: listing, pictures, their contents, mouse and keys.
window.list read
The app windows open on a machine's screen
List the app windows open on a machine's screen: each one's id, app, title and size, whether it is on screen now, the process it belongs to (pid), and whether it is a whole screen rather than one app's window (screen, as a Linux machine's desktop is). The id is what the other window tools take. With icons, each app's icon too: icons maps a window's pid to a PNG, as base64.
| Argument | Kind | What | |
|---|---|---|---|
machine | text | needed | Machine to ask |
icons | true/false | Give each app's icon too (default false) |
$ hop windows <machine> [--option value…] $ hop do window.list <machine> [--option value…]
{"id":1,"call":"window.list","args":{"machine":"tower"}}
window.look read
A picture of one app window
Take a picture of one app window on a machine and return it as an image. Use it to see what an app shows; use window.elements when the words and buttons are enough, which is cheaper.
| Argument | Kind | What | |
|---|---|---|---|
machine | text | needed | Machine the window is on |
window | number | needed | The window's id, from window.list |
max | number | Longest side in pixels (default 1400) |
$ hop shot <machine> <window> [--option value…] $ hop do window.look <machine> <window> [--option value…]
{"id":1,"call":"window.look","args":{"machine":"tower","window":12}}
window.elements read
What one app window holds: its buttons, fields, menus and text
Read what one app window holds, without a picture: its buttons, fields, menus and text as an outline, each with the place of its middle as x,y fractions of the window (0,0 top left; 1,1 bottom right). Give those to window.act to click it. On Linux this reads an app in a display Hop started (app.open); an app that draws its own controls, such as a game, has nothing to read, and the answer's note says to look at the picture instead.
| Argument | Kind | What | |
|---|---|---|---|
machine | text | needed | Machine the window is on |
window | number | needed | The window's id, from window.list |
$ hop elements <machine> <window> $ hop do window.elements <machine> <window>
{"id":1,"call":"window.elements","args":{"machine":"tower","window":12}}
window.act act
Work one app window with the mouse and keyboard
Work one app window on a machine with the mouse and keyboard. The window comes to the front there first. steps are done in order; each is an object with t: {"t":"click","x":0.5,"y":0.2} (x,y as fractions of the window; add "b":1 for a right click, "n":2 for a double click), {"t":"text","text":"hello"} to type, {"t":"key","code":"Enter"} to press a key named as web pages name them (Enter, Tab, Escape, Backspace, ArrowDown, KeyA, Digit1, F5…; add "m" for keys held: 1 Shift, 2 Control, 4 Option, 8 Command, summed), {"t":"scroll","x":0.5,"y":0.5,"dy":300} to scroll down by points, {"t":"wait","ms":500}. On Linux, Command (8) is taken as Control and Option as Alt, so the same steps work there. Look or read again afterwards to see what happened.
| Argument | Kind | What | |
|---|---|---|---|
machine | text | needed | Machine the window is on |
window | number | needed | The window's id, from window.list |
steps | list of steps | needed | What to do, in order |
$ hop do window.act <machine> <window> <steps>
{"id":1,"call":"window.act","args":{"machine":"tower","window":12,"steps":[{"t":"key","code":"Enter"}]}}
window.close act
Close an app window: its app is asked to quit
Close one app window on a machine. On a Mac the window's app is asked to quit, as its own Quit would: one with unsaved work asks about it on the machine's screen, and then closed is false and asking true. On Linux the display Hop made for the app is ended, with what runs in it, or a game Steam started on the machine's own screen is stopped. force ends an app that has not quit a few seconds after being asked; unsaved work in it is lost. app is a check: the window is left alone unless it is still that app's.
| Argument | Kind | What | |
|---|---|---|---|
machine | text | needed | Machine the window is on |
window | number | needed | The window's id, from window.list |
force | true/false | End the app if it has not quit when asked | |
app | text | Close it only if the window is this app's |
$ hop do window.close <machine> <window> [--option value…]
{"id":1,"call":"window.close","args":{"machine":"tower","window":12}}
app
Apps installed on a machine, and opening them.
app.list read
The apps installed on a machine
List the apps installed on a machine, by name. With detail, details has each one's name, id (its bundle id on a Mac), path (what app.icons takes) and stamp, which changes when the app is updated: a launcher that keeps icons asks again for those whose stamp changed.
| Argument | Kind | What | |
|---|---|---|---|
machine | text | needed | Machine to ask |
detail | true/false | Give each app's id, path and stamp too, in details (default false) |
$ hop apps <machine> [--option value…] $ hop do app.list <machine> [--option value…]
{"id":1,"call":"app.list","args":{"machine":"tower"}}
app.open act
Open an app on a machine and give its window's id
Open an app on a machine (or bring it forward when it is already open) and return the id of its window, for the window tools.
| Argument | Kind | What | |
|---|---|---|---|
machine | text | needed | Machine to open it on |
app | text | needed | The app's name as app.list lists it, its bundle id, or its path |
$ hop do app.open <machine> <app>
{"id":1,"call":"app.open","args":{"machine":"tower","app":"Godot"}}
app.hidden read
The apps a machine runs out of sight, in displays of Hop's own
List the apps a machine runs where nobody at its screen sees them: each was opened through Hop into a display of its own (Linux), and keeps running there when no Hop window shows it. A Mac opens apps on its own screen, so it has none (displays is false).
| Argument | Kind | What | |
|---|---|---|---|
machine | text | needed | Machine to ask |
$ hop do app.hidden <machine>
{"id":1,"call":"app.hidden","args":{"machine":"tower"}}
app.quit act
Quit an app a machine runs out of sight
Quit an app that runs in a display of Hop's own (see app.hidden), and everything it started there.
| Argument | Kind | What | |
|---|---|---|---|
machine | text | needed | Machine it runs on |
window | text | needed | Its id as app.hidden lists it, or its name |
$ hop do app.quit <machine> <window>
{"id":1,"call":"app.quit","args":{"machine":"tower","window":12}}
app.reveal act
Move an app a machine runs out of sight to that machine's own screen
Move an app out of the display of Hop's own it runs in (see app.hidden) to the machine's own screen, for whoever sits there. The app cannot change displays while it runs: it is quit and opened again on the screen, so anything unsaved in it is lost.
| Argument | Kind | What | |
|---|---|---|---|
machine | text | needed | Machine it runs on |
window | text | needed | Its id as app.hidden lists it, or its name |
$ hop do app.reveal <machine> <window>
{"id":1,"call":"app.reveal","args":{"machine":"tower","window":12}}
app.icons read
The icons of apps installed on a machine
The icons of apps on a machine, by the paths app.list gives in its details: icons maps each path to a PNG, as base64. An app with no icon, or a path that is not there, is left out.
| Argument | Kind | What | |
|---|---|---|---|
machine | text | needed | Machine the apps are on |
apps | list | needed | The apps' paths, as app.list's details give them |
$ hop do app.icons <machine> <apps>
{"id":1,"call":"app.icons","args":{"machine":"tower","apps":[]}}
view
The Hop app in front of the person: its tabs, panes, commands and settings. These need the app open.
view.state read
What the Hop window has open: tabs, panes, which is in front
What the person's Hop app has open: its tabs, each with its machine and its panes (terminals with their session, web pages, folders, app windows), which is in front, and whose tabs the bar shows. The numbers it gives for tabs and panes are what the other hop_ tools take. Start here before driving the app.
| Argument | Kind | What | |
|---|---|---|---|
on | text | The computer whose Hop app to drive, when it is not this one (the person may sit at another machine than the one this runs on) |
$ hop do view.state [--option value…]
{"id":1,"call":"view.state","args":{}}
view.open act
Open a terminal, page, folder, window or app in a new tab
Open something in the person's Hop app, in a new tab they will see: a terminal on a machine (optionally an existing session, or a command typed as it starts), a web page a machine serves, a folder, one of the machine's app windows, or an app by name (started there and shown here).
| Argument | Kind | What | |
|---|---|---|---|
machine | text | needed | Machine the thing is on |
on | text | The computer whose Hop app to drive, when it is not this one (the person may sit at another machine than the one this runs on) | |
kind | text | terminal, web, files, window or app (default terminal) | |
session | text | terminal: a session's name, to show that one | |
run | text | terminal: a line typed into it as it starts | |
url | text | web: an address, such as http://localhost:3000/ | |
path | text | files: the folder or file | |
window | number | window: its id, from window.list | |
app | text | app: its name, as app.list lists it |
$ hop do view.open <machine> [--option value…]
{"id":1,"call":"view.open","args":{"machine":"tower"}}
view.popup risky
Run a command in a terminal floating over the Hop app, gone when it ends
Run a command on a machine in a terminal that floats over the person's Hop app (tmux's display-popup): a picker, a dashboard, a quick shell. It closes when the command ends, unless it failed or keep is set; Esc twice closes it any time. Nothing about it is kept: for a terminal that stays, open a tab (view.open).
| Argument | Kind | What | |
|---|---|---|---|
on | text | The computer whose Hop app to drive, when it is not this one (the person may sit at another machine than the one this runs on) | |
machine | text | Machine to run it on (default: the pane in front's) | |
command | text | What to run, as a shell line (default: a shell) | |
cwd | text | Folder to run it in (default: the pane in front's, else home) | |
title | text | What its frame says (default: the command) | |
width | text | Its width: "80%" of the window, or columns (default 80%) | |
height | text | Its height: "80%" of the window, or rows (default 80%) | |
keep | true/false | Stay open after the command ends, until Esc |
$ hop do view.popup [--option value…]
{"id":1,"call":"view.popup","args":{}}
view.show act
Bring a tab, pane, machine's tabs or page to the front
Bring something to the front in the Hop app: a tab, a pane, one machine's tabs (machine, or "all"), or a page (home, settings, addons).
| Argument | Kind | What | |
|---|---|---|---|
on | text | The computer whose Hop app to drive, when it is not this one (the person may sit at another machine than the one this runs on) | |
tab | number | Tab to go to | |
pane | number | Pane to go to | |
machine | text | Show this machine's tabs; "all" for every machine's | |
page | text | home, settings or addons |
$ hop do view.show [--option value…]
{"id":1,"call":"view.show","args":{}}
view.close act
Close a tab or pane (its session keeps running)
Close a tab or one pane of the Hop app. A terminal's session keeps running on its machine.
| Argument | Kind | What | |
|---|---|---|---|
on | text | The computer whose Hop app to drive, when it is not this one (the person may sit at another machine than the one this runs on) | |
tab | number | Tab to close | |
pane | number | Pane to close |
$ hop do view.close [--option value…]
{"id":1,"call":"view.close","args":{}}
view.command act
Do one of the window's own commands, or list them
Do one of the Hop app's own commands, the ones its command list has (split-right, zoom, next-tab, pin, compact, window-full…). Without an id, lists them. With a tab or pane, goes there first.
| Argument | Kind | What | |
|---|---|---|---|
on | text | The computer whose Hop app to drive, when it is not this one (the person may sit at another machine than the one this runs on) | |
id | text | The command; leave out to list them all | |
tab | number | Tab to do it in | |
pane | number | Pane to do it in |
$ hop do view.command [--option value…]
{"id":1,"call":"view.command","args":{}}
view.run act
Do anything the window can by its action id, or list every action
Do anything the Hop app can, by its action id: every command (split-right, zoom, next-tab, compact…), every setting (toggle:bar, cycle:theme, set:theme=midnight), the buttons of each kind of pane (web-back, files-up, window-sound…) and what add-ons add. Without an id, lists them all with their keys and, for settings, what they are now.
| Argument | Kind | What | |
|---|---|---|---|
on | text | The computer whose Hop app to drive, when it is not this one (the person may sit at another machine than the one this runs on) | |
id | text | The action; leave out to list them | |
args | list | What it takes, if anything (tab takes a number 1–9) | |
tab | number | Tab to do it in | |
pane | number | Pane to do it in |
$ hop do view.run [--option value…]
{"id":1,"call":"view.run","args":{}}
view.keys act
Press the window's own shortcuts
Press the Hop app's own keyboard shortcuts, as if on its keyboard: "Meta+T", a sequence "Meta+K Meta+S", or "Prefix C" after the prefix key. For keys meant for a program in a pane, use view.type or view.act.
| Argument | Kind | What | |
|---|---|---|---|
keys | text | needed | The shortcut |
on | text | The computer whose Hop app to drive, when it is not this one (the person may sit at another machine than the one this runs on) |
$ hop do view.keys <keys> [--option value…]
{"id":1,"call":"view.keys","args":{"keys":"Meta+T"}}
view.settings act
Read every setting, read one, or change one
The Hop app's settings: with no name, every one with its value, default, choices and what it does; with a name, that one; with a name and value, changes it (as the person could in Settings).
| Argument | Kind | What | |
|---|---|---|---|
on | text | The computer whose Hop app to drive, when it is not this one (the person may sit at another machine than the one this runs on) | |
name | text | A setting | |
value | text | Its new value, as JSON (true, 14, "midnight", {…}) or as text |
$ hop do view.settings [--option value…]
{"id":1,"call":"view.settings","args":{}}
view.elements read
What is on the window's screen to press or fill, each with a ref
What is on the Hop app's screen that can be pressed or typed in: the bar and tabs, each pane's buttons and lists (a machine's web pages and ports, its windows and apps, a folder's files), the open page (home, settings, add-ons), the search box and add-ons' popups. Each has a ref for view.press and view.fill.
| Argument | Kind | What | |
|---|---|---|---|
on | text | The computer whose Hop app to drive, when it is not this one (the person may sit at another machine than the one this runs on) | |
where | text | Only this part: bar, palette, popup, page, or "pane 3" | |
find | text | Only items whose label has this text |
$ hop do view.elements [--option value…]
{"id":1,"call":"view.elements","args":{}}
view.press act
Press something view.elements listed
Press something view.elements listed, by its ref.
| Argument | Kind | What | |
|---|---|---|---|
ref | text | needed | Its ref, such as e12 |
on | text | The computer whose Hop app to drive, when it is not this one (the person may sit at another machine than the one this runs on) |
$ hop do view.press <ref> [--option value…]
{"id":1,"call":"view.press","args":{"ref":"e12"}}
view.fill act
Type into a field view.elements listed
Type into a field view.elements listed, replacing what it held; with enter, then press Enter.
| Argument | Kind | What | |
|---|---|---|---|
ref | text | needed | Its ref |
text | text | needed | What to put in it |
on | text | The computer whose Hop app to drive, when it is not this one (the person may sit at another machine than the one this runs on) | |
enter | true/false | Press Enter afterwards |
$ hop do view.fill <ref> <text> [--option value…]
{"id":1,"call":"view.fill","args":{"ref":"e12","text":"make test"}}
view.search read
Search everything the window knows, as its search box does
Search everything the Hop app knows, as its search box does: apps on every machine, what is open, web pages, folders, sessions, commands and settings. With pick, opens that result.
| Argument | Kind | What | |
|---|---|---|---|
query | text | needed | What to look for (a machine's name narrows it to that machine) |
on | text | The computer whose Hop app to drive, when it is not this one (the person may sit at another machine than the one this runs on) | |
pick | number | Open this result (counting from 0) |
$ hop do view.search <query> [--option value…]
{"id":1,"call":"view.search","args":{"query":"tower 3000"}}
view.type act
Type into a pane: a terminal or an app window
Type into a pane of the Hop app: a terminal (as at its keyboard) or an app window. The person sees it happen.
| Argument | Kind | What | |
|---|---|---|---|
text | text | needed | What to type |
on | text | The computer whose Hop app to drive, when it is not this one (the person may sit at another machine than the one this runs on) | |
pane | number | The pane; the one in front when left out | |
enter | true/false | Press Enter afterwards (default false) |
$ hop do view.type <text> [--option value…]
{"id":1,"call":"view.type","args":{"text":"make test"}}
view.act act
Work an app window shown in a pane with the mouse and keys
Work an app window shown in the Hop app with the mouse and keys, through the picture the person is watching. steps as for window.act: click, move, key, text, scroll, wait, with x,y as fractions of the window.
| Argument | Kind | What | |
|---|---|---|---|
pane | number | needed | The app window's pane |
steps | list of steps | needed | What to do, in order |
on | text | The computer whose Hop app to drive, when it is not this one (the person may sit at another machine than the one this runs on) |
$ hop do view.act <pane> <steps> [--option value…]
{"id":1,"call":"view.act","args":{"pane":1,"steps":[{"t":"key","code":"Enter"}]}}
view.look read
See a pane as the person does: a picture, or a terminal's lines
See one pane of the Hop app as the person does: an app window as a picture, a terminal as its last lines of text, anything else as what it is showing.
| Argument | Kind | What | |
|---|---|---|---|
on | text | The computer whose Hop app to drive, when it is not this one (the person may sit at another machine than the one this runs on) | |
pane | number | The pane; the one in front when left out | |
lines | number | Terminal: how many lines from the end (default 80) |
$ hop do view.look [--option value…]
{"id":1,"call":"view.look","args":{}}
folder
folder.list read
The folders a machine knows of, best first, to find one by name
List the folders on a machine (or on every machine) worth finding by name, each with a score (higher is better: used more, or more lately) and from, the reasons it is known: zoxide (its database, most used first), session (a terminal session is in it now), repo (a git repository under the home folder) and near (a folder at most two down from home). With scan false, only what is known already (zoxide, sessions) is listed, at once; otherwise the home folder is walked too, for a few seconds at most, skipping generated folders, other disks, hidden folders and, on a Mac, the folders it asks the person before showing. Paths under home are written with ~. Each machine's entry also says its home, its system, which coding agents it has (agents, each kind and display) and whether zoxide and fd are there. Needs only a shell: no Hop on the machine.
| Argument | Kind | What | |
|---|---|---|---|
machine | text | Machine to look on; leave out for all of them | |
scan | true/false | Walk the home folder for git repositories too (default true) |
$ hop do folder.list [--option value…]
{"id":1,"call":"folder.list","args":{}}
event
Changes on your machines as they happen.
event.watch read
Stream changes on machines: sessions, windows, ports, up and down
Stream what changes on machines as it happens: machine.up and machine.down; session.started, session.ended and session.state (what a program in a session says it is doing: working, blocked = waiting for a person, done, error); agent.started, agent.state and agent.ended (an AI agent in a session, as its machine's Hop daemon decides: its kind, state (working, needs_you, done, failed, idle), was, label, asks, since (when the state began) and changed_at (when its state or question last changed: the time to show); a new question while it waits is an agent.state too; news says what a person would want to hear of: needs_you, finished or failed); window.opened, window.closed and window.title; port.opened and port.closed; workspace.saved and workspace.removed (a workspace kept on the machine, with its name and when it was saved: how front ends follow one another); approval.asked and approval.ended (a call by an AI program waiting there for the person to say yes, with its id, who, call and args: see approval.list and approval.answer). Each event has its type, machine, the address of what changed, and when. Runs until the caller stops it.
| Argument | Kind | What | |
|---|---|---|---|
machines | list | Machines to watch (default: all of them) | |
types | list | Only these types, or kinds of type: ["session.state", "window"] (default: all) | |
every | number | Seconds between looks (default 2) | |
initial | true/false | First send what is there now, as if it had just started or opened |
$ hop events [--option value…] $ hop do event.watch [--option value…]
{"id":1,"call":"event.watch","args":{}}
wait
Waiting until something is so.
wait read
Wait until something is so: a session done, a port open, a window, a machine
Wait until something is so, then answer. for is an address: a session (state working, blocked, done, error, or ended; default done), a window by id or app (open or closed; default open), a port (open or closed; default open), a file (exists or gone; default exists), an element of an app's window (mac:Calculator >> button "7"; appears or gone; default appears), or a machine (up or down; default up). Waiting for a session that is not there is not_found unless the state is started or ended. Gives up with a timeout error after timeout seconds.
| Argument | Kind | What | |
|---|---|---|---|
for | address | needed | What to wait for: tower:session/build, tower:port/3000, tower:window/Godot, tower:~/out.txt, mac:Calculator >> button "7", tower |
state | text | The state to wait for (see above) | |
timeout | number | Seconds to wait at most (default 300) |
$ hop wait <for> [--option value…] $ hop do wait <for> [--option value…]
{"id":1,"call":"wait","args":{"for":"tower:port/3000"}}
element
An app's own buttons and fields, found by a selector such as button "Play".
element.find read
Find elements in a window by what they are: button "Play"
Find the elements of an app's window (on a Mac, or of an app in a display Hop started on Linux; apps that draw their own controls, such as games, show none) that a selector names, with their role, name, value and place. A selector is a role and a name: button "Play", field "Name", text ~"finished" (~ for contains), "OK" (any role), button "OK" #2 (the second one), group "Sidebar" >> button "New" (inside). Roles: button, field, text, checkbox, radio, menu, menuitem, link, tab, list, listitem, image, window, group, slider, other.
| Argument | Kind | What | |
|---|---|---|---|
target | address | needed | The element: machine:app >> selector, such as mac:Calculator >> button "7" (or machine:window/12 >> …) |
$ hop find <target> $ hop do element.find <target>
{"id":1,"call":"element.find","args":{"target":"studio:Calculator >> button \"7\""}}
element.press act
Press an element: a button, link, checkbox or menu item
Press one element of an app's window, found by a selector (see element.find): mac:Calculator >> button "7". When the selector matches more than one, add #n to say which, so nothing is pressed by mistake. The window comes to the front there first. On Linux the app is asked to press the element itself, so one that is out of sight (a line of a closed menu, something scrolled away) can be pressed too.
| Argument | Kind | What | |
|---|---|---|---|
target | address | needed | The element: machine:app >> selector, such as mac:Calculator >> button "7" (or machine:window/12 >> …) |
$ hop press <target> $ hop do element.press <target>
{"id":1,"call":"element.press","args":{"target":"studio:Calculator >> button \"7\""}}
element.fill act
Type into a field, replacing what it held
Type into one field of an app's window, found by a selector (see element.find): tower:Safari >> field "Address". What the field held is replaced. With enter, press Enter afterwards.
| Argument | Kind | What | |
|---|---|---|---|
target | address | needed | The element: machine:app >> selector, such as mac:Calculator >> button "7" (or machine:window/12 >> …) |
text | text | needed | What to put in it |
enter | true/false | Press Enter afterwards |
$ hop fill <target> <text> [--option value…] $ hop do element.fill <target> <text> [--option value…]
{"id":1,"call":"element.fill","args":{"target":"studio:Calculator >> button \"7\"","text":"make test"}}
person
Telling and asking the person at the computer.
person.notify act
Show the person a notification on a machine's screen
Show the person a notification on a machine's screen (this one unless on says another), for telling them something finished or needs them. On a Mac with the Hop app open it is Hop's, with Hop's icon, and clicking it brings Hop forward; on a Mac without the app open, AppleScript's (which macOS shows as Script Editor's); on Linux, the desktop's notifications. Fails with needs_permission when that Mac has Hop's notifications turned off.
| Argument | Kind | What | |
|---|---|---|---|
text | text | needed | What to say |
title | text | A title (default Hop) | |
on | text | The machine whose screen to show it on (default this one) |
$ hop notify <text> [--option value…] $ hop do person.notify <text> [--option value…]
{"id":1,"call":"person.notify","args":{"text":"make test"}}
person.ask act
Ask the person a question on a machine's screen and wait for the answer
Ask the person a question on a machine's screen (this one unless on says another) and wait for their answer: a dialog with up to three choices on a Mac, two on Linux. The answer is the choice they picked; yes is true when it was the first. Gives up with a timeout error when nobody answers. Use it before doing something they should agree to.
| Argument | Kind | What | |
|---|---|---|---|
question | text | needed | What to ask |
choices | list | The answers to choose from, the yes first (default ["Yes", "No"]) | |
timeout | number | Seconds to wait for an answer (default 120) | |
on | text | The machine whose screen to ask on (default this one) |
$ hop ask <question> [--option value…] $ hop do person.ask <question> [--option value…]
{"id":1,"call":"person.ask","args":{"question":"…"}}
permission
What Hop may do on each machine, what is missing, and turning things off.
permission.list read
What Hop may do on each machine, what is missing, and how to fix it
For each machine (or the one named): whether Hop reaches it without a password, whether the Hop daemon (sessions) and the window helper are there, and whether it may see its windows and screens and work them: allowed, missing (with the command that fixes it), or turned off by the person in Hop's settings.
| Argument | Kind | What | |
|---|---|---|---|
machine | text | One machine (default: all) |
$ hop permissions [--option value…] $ hop do permission.list [--option value…]
{"id":1,"call":"permission.list","args":{}}
permission.set risky
Turn seeing or working a machine's windows on or off in Hop
Turn one kind of access on or off for a machine in Hop's settings: see (pictures and contents of its windows and screens) or control (working its windows with clicks and keys). Off is refused by every part of Hop, whatever the machine's system allows; on lets Hop use what the system allows.
| Argument | Kind | What | |
|---|---|---|---|
machine | text | needed | The machine |
what | text | needed | see or control |
on | true/false | needed | true to allow it, false to turn it off |
$ hop do permission.set <machine> <what> <on>
{"id":1,"call":"permission.set","args":{"machine":"tower","what":"…","on":true}}
permission.ask act
Ask a Mac's person to let Hop see and work its windows
Say what macOS lets each of Hop's programs on a Mac do (this one unless machine says another), and open System Settings on its screen at the first permission still missing, with the program already in that list, so the person there turns one switch. One at a time: run it again for the next. hop-windows needs Screen & System Audio Recording (pictures of windows) and Accessibility (working them); the Hop app, when open, may use the Microphone. For when permission.list, window.look, window.elements or element.* say one is missing.
| Argument | Kind | What | |
|---|---|---|---|
machine | text | The machine (default this one) |
$ hop allow [--option value…] $ hop do permission.ask [--option value…]
{"id":1,"call":"permission.ask","args":{}}
steps
steps.run risky
Run a list of Hop calls in order, on the machines they name or others
Run Hop calls one after another. Each step is {"call": "element.press", "args": {…}}, as HOP_RECORD=file writes them; a wait step waits for something to appear before the next. Stops at the first step that fails unless keep_going. on moves the steps to another machine (when they name one machine besides this one, or only this one); machines says where each machine's steps run instead.
| Argument | Kind | What | |
|---|---|---|---|
steps | list of steps | needed | The calls, in order: [{"call": name, "args": {…}}, …] |
on | text | Run them on this machine instead | |
machines | object | Where each machine's steps run instead: {"tower": "server"} | |
keep_going | true/false | Go on after a step fails (default: stop there) |
$ hop do steps.run <steps> [--option value…]
{"id":1,"call":"steps.run","args":{"steps":[{"t":"key","code":"Enter"}]}}
mcp
mcp.add risky
Connect the AI apps on a machine to Hop (adds Hop's MCP server to each)
Find the AI apps on a machine (this one unless machine says another) and add Hop's MCP server, hop mcp, to each one's settings: Claude Code, Claude Desktop, Cursor, VS Code, Windsurf, Gemini CLI and Codex. Says, for each, whether it was added, was there already, or why not. A file changed keeps its old self beside it as <file>.before-hop. apps limits it to some (claude-code, claude-desktop, cursor, vscode, windsurf, gemini, codex); levels says what the AI may do (read, act, risky: see hop mcp), read,act unless it says otherwise, and a call that is risky or runs or types what it is given waits for the person to say yes in the Hop app or on a phone (hop mcp --ask-first): the risky commands (running a shell command and reading what it prints, writing and copying files) only when asked for. Act still lets it type into terminals. An app that has Hop already keeps what it was given.
| Argument | Kind | What | |
|---|---|---|---|
machine | text | The machine (default this one) | |
apps | text | Only these, comma-separated (default: every one found) | |
levels | text | What the AI may do: read, act, risky, comma-separated (default read,act: risky only when asked for) |
$ hop do mcp.add [--option value…]
{"id":1,"call":"mcp.add","args":{}}
font
font.list read
The fonts installed on a machine, and which are monospaced
List the font families installed on a machine, each with whether it is monospaced (every letter as wide as the next, as a terminal wants). On a Mac this asks the system's font manager; on Linux, fontconfig (fc-list).
| Argument | Kind | What | |
|---|---|---|---|
machine | text | needed | Machine whose fonts to list; local is this one |
$ hop do font.list <machine>
{"id":1,"call":"font.list","args":{"machine":"tower"}}
workspace
workspace.list read
The workspaces kept on a machine, or on every machine
List the workspaces (like tmux's sessions: a name and its windows of panes) kept on a machine, or on every machine: each one's name, when it was last saved, how many windows it has, the machines its panes are on, and the terminal sessions its panes show (each { machine, host?, session }, the machine as the workspace saved it). Each machine also says its own host name, so its workspaces' panes can be matched to this device's machines.
| Argument | Kind | What | |
|---|---|---|---|
machine | text | Machine to ask; leave out for all of them |
$ hop do workspace.list [--option value…]
{"id":1,"call":"workspace.list","args":{}}
workspace.get read
One workspace: its windows and what each pane shows
Get a workspace as it was last saved: its windows, each a layout of columns of panes, and what each pane shows (a terminal session, a folder, a web page, an app window) and on which machine.
| Argument | Kind | What | |
|---|---|---|---|
machine | text | needed | Machine the workspace is kept on (its home) |
name | text | needed | Workspace name: letters, digits, '.', '-' and '_' |
$ hop do workspace.get <machine> <name>
{"id":1,"call":"workspace.get","args":{"machine":"tower","name":"build"}}
workspace.save act
Keep a workspace on a machine
Save a workspace on its home machine, replacing one of the same name: an object with a list of windows, each { machine, name?, columns: [[pane spec…]…], sizes }. A pane on another machine than its window says so with its own machine. With if_updated (when the copy you changed was saved; 0 for a new one) it is saved only if nobody saved it since: otherwise the answer has changed: true and when it was saved, to get it again, merge and retry. Front ends that follow a workspace (event.watch's workspace.saved) save this way.
| Argument | Kind | What | |
|---|---|---|---|
machine | text | needed | Machine the workspace is kept on (its home) |
name | text | needed | Workspace name: letters, digits, '.', '-' and '_' |
workspace | object | needed | The workspace: { windows: [...], active? } |
if_updated | number | Save only if it is still the one saved at this time (its updated; 0: only if new) |
$ hop do workspace.save <machine> <name> <workspace> [--option value…]
{"id":1,"call":"workspace.save","args":{"machine":"tower","name":"build","workspace":"…"}}
workspace.remove act
Forget a workspace kept on a machine
Remove a workspace from its home machine. Its terminal sessions keep running; only the layout is forgotten.
| Argument | Kind | What | |
|---|---|---|---|
machine | text | needed | Machine the workspace is kept on (its home) |
name | text | needed | Workspace name: letters, digits, '.', '-' and '_' |
$ hop do workspace.remove <machine> <name>
{"id":1,"call":"workspace.remove","args":{"machine":"tower","name":"build"}}
workspace.folders read
Project folders on a machine, or on every machine, to start a workspace in
List the folders that could each be a workspace (as tmux-sessionizer and sesh do): what is directly in ~/personal, ~/projects, ~/code, ~/src, ~/dev, ~/work, ~/Developer, ~/repos, ~/git and ~/workspace, or in the roots given; then, when the machine has them, the folders tmux-sessionizer --list prints and those zoxide knows, most used first. Each is { name, path, from, changed? }, from being projects, sessionizer or zoxide, and a path under the home folder written with ~.
| Argument | Kind | What | |
|---|---|---|---|
machine | text | Machine to look on; leave out for all of them | |
roots | list | Folders to look in, with ~ for home (default: the usual homes of code) | |
only_roots | true/false | Only the roots' folders: leave out tmux-sessionizer's and zoxide's |
$ hop do workspace.folders [--option value…]
{"id":1,"call":"workspace.folders","args":{}}
usage
usage.list read
How much of their plans' limits the AI programs on a machine have used
List how much of each plan limit the AI programs on a machine (or on every machine) have used, as the programs themselves last said: for each limit the program (claude, codex), how long its window is in minutes (300 is the five-hour limit, 10080 the weekly one), the percentage used, when it starts again and when the program said so (seconds since 1970). Claude Code says it through its status line, kept by agents/claude-code/hop-usage (see the README); a machine without that, or whose programs have said nothing since their limits last started again, lists none.
| Argument | Kind | What | |
|---|---|---|---|
machine | text | Machine to ask; leave out for all of them |
$ hop usage [--option value…] $ hop do usage.list [--option value…]
{"id":1,"call":"usage.list","args":{}}
pad
pad.list read
Which machines take game controllers, and the map each uses
For each machine (or the one named): whether it makes a real controller for a viewer's (native: Linux, through uinput) or turns one into a mouse and keys (a Mac), the name of the map in force there, and the apps that have a map of their own. Also what a map can be made of: the ready-made maps (presets), a controller's buttons, what a stick can do, and keys worth offering. See pad.map.get for a whole map.
| Argument | Kind | What | |
|---|---|---|---|
machine | text | One machine (default: all) |
$ hop do pad.list [--option value…]
{"id":1,"call":"pad.list","args":{}}
pad.map.get read
What a controller's buttons and sticks do on a machine, or in one app there
The controller map in force for a machine, or for one app on it: the app's own if one is saved, else the machine's, else the default (a controller as it is where the machine makes real ones, a mouse and keys where it cannot). from says which. The map: buttons (each that is not itself: pad:<button>, key:<code> as web pages name keys, mouse:left|right|middle, none), left and right (each stick: left, right, mouse, scroll, wasd, arrows, none), dead (the dead zone, 0 to 0.5), speed (the pointer's pixels a second), and name (the ready-made map it equals, or custom).
| Argument | Kind | What | |
|---|---|---|---|
machine | text | needed | The machine the windows are on |
app | text | One app there, by name (Godot); left out, the machine's own map |
$ hop do pad.map.get <machine> [--option value…]
{"id":1,"call":"pad.map.get","args":{"machine":"tower"}}
pad.map.set act
Change what a controller does on a machine, or in one app there
Save a controller map for a machine, or for one app on it, given as exactly one of: preset (a ready-made one: pad, desktop, wasd), map (a whole map, as pad.map.get returns it; what is left out is as on a plain controller), or reset (forget the saved one, back to the default). Windows opened after this use it; ones already playing take it when their viewer is told. Example: machine tower, app Godot, map {"left":"wasd","right":"mouse","buttons":{"a":"key:Space","rt":"mouse:left"}}.
| Argument | Kind | What | |
|---|---|---|---|
machine | text | needed | The machine the windows are on |
app | text | One app there, by name (Godot); left out, the machine's own map | |
map | object | The whole map: buttons, left, right, dead, speed | |
preset | text | A ready-made map: pad, desktop or wasd | |
reset | true/false | true to forget the saved map |
$ hop do pad.map.set <machine> [--option value…]
{"id":1,"call":"pad.map.set","args":{"machine":"tower"}}
agent
agent.list read
Every AI agent in a terminal, on every machine: working, needs you, done
List the AI agents (Claude Code, Codex, Gemini, opencode, …) in terminal sessions, on every machine unless machines says which, as each machine's Hop daemon decides them. Each has its machine, session (and its address), kind, state (working; needs_you = waiting for a person, with what it asks in asks; done = its turn ended; failed; idle), label (the conversation's name, else "Claude in <folder>"), cwd, since (when the state began, seconds since 1970), and, when the agent's hooks said them, its conversation id and transcript. Those needing a person come first. A machine that could not be asked is in errors and one whose daemon is too old to say in notes; the others answer all the same.
| Argument | Kind | What | |
|---|---|---|---|
machines | list | Machines to ask (default: all of them) |
$ hop agents [--option value…] $ hop do agent.list [--option value…]
{"id":1,"call":"agent.list","args":{}}
agent.report act
Tell a machine's daemon what an AI agent in a session is doing
Pass on what an AI agent's hook says, for the daemon of the machine its session is on, which takes it into what it reports of that session (agent.list, session.list, event.watch). event is the hook's event as Claude Code names it (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PermissionRequest, Notification, Stop, StopFailure, SessionEnd; Codex's Interrupt), report what the hook was given, and kind the agent (default claude). An agent's own hooks do this through hop agent report (see agent.hooks.add); this is for a program that runs an agent itself. Says whether it was taken, and the agent as the daemon now has it.
| Argument | Kind | What | |
|---|---|---|---|
session | address | needed | The session the agent is in: tower:session/build |
event | text | needed | The hook's event: Stop, PermissionRequest, … |
report | object | What the hook was given, as JSON (session_id, message, tool_name, …) | |
kind | text | The agent: claude (default), codex, … |
$ hop do agent.report <session> <event> [--option value…]
{"id":1,"call":"agent.report","args":{"session":"…","event":"…"}}
agent.hooks.add risky
Have the AI agents on a machine tell Hop each step they take (their hooks)
Add Hop's hooks to the settings of the AI agents on a machine (this one unless machine says another): Claude Code (settings.json in its folder) and Codex (hooks.json). Each step the agent takes (a prompt sent, a tool about to run, a permission asked, its turn ended) then runs hop agent report, and the machine's daemon knows what it is doing for certain, rather than from its screen. Says, for each, whether they were added, were there already, or why not. A file changed keeps its old self beside it as <file>.before-hop. Codex runs them once you trust them with /hooks. apps limits it to some (claude-code, codex).
| Argument | Kind | What | |
|---|---|---|---|
machine | text | The machine (default this one) | |
apps | text | Only these, comma-separated: claude-code, codex (default: every one found) |
$ hop do agent.hooks.add [--option value…]
{"id":1,"call":"agent.hooks.add","args":{}}
agent.hooks.remove risky
Take Hop's hooks out of the AI agents' settings on a machine
Take out of the AI agents' settings on a machine (this one unless machine says another) the hooks agent.hooks.add put there, and nothing else. A file changed keeps its old self beside it as <file>.before-hop when it has none yet. apps limits it to some (claude-code, codex).
| Argument | Kind | What | |
|---|---|---|---|
machine | text | The machine (default this one) | |
apps | text | Only these, comma-separated: claude-code, codex (default: both) |
$ hop do agent.hooks.remove [--option value…]
{"id":1,"call":"agent.hooks.remove","args":{}}
agent.kinds read
The kinds of AI agent a machine's Hop knows, built in and taught
List the kinds of AI agent the Hop daemon on a machine (this one unless machine says another) recognises in its terminals: the built-in ones (claude, codex, gemini, opencode, cursor-agent, aider, amp, goose, …) and those a person taught it with agent.kind.add. Each has its kind (the id agents carry), display (what people call it), the program names it goes by, and, for a taught one, taught: true, its file and its patterns (args, titles, screen, working, asking, done), icon and color. A manifest that does not read is in problems, with why.
| Argument | Kind | What | |
|---|---|---|---|
machine | text | The machine (default this one) |
$ hop do agent.kinds [--option value…]
{"id":1,"call":"agent.kinds","args":{}}
agent.kind.add act
Teach a machine's Hop an AI agent it does not know, with no code
Teach the Hop daemon on a machine (this one unless machine says another) to recognise an AI agent in its terminals, and what it is doing, by writing a manifest to <Hop's folder>/agents/<kind>.toml there (replacing one of the same kind). kind is its id (lower case letters, digits and -). It is known by programs (names of the program in front, or of the script an interpreter runs), else args (patterns for its command line), titles (patterns for its terminal's title) or screen (patterns for a line it draws near the bottom). working, asking and done are patterns for screen lines that mean it is working, asks something (the line is the question) or finished its turn; without them Hop reads its screen as it does any agent's. Patterns are regular expressions. display, icon (a letter or two, or a Hop icon's name) and color (#rrggbb) are how clients show it. A kind that is built in is added to: another program name, say. The daemon takes it within a few seconds; a daemon older than this ignores it until it is updated and restarted.
| Argument | Kind | What | |
|---|---|---|---|
kind | text | needed | Its id: acme, my-agent |
machine | text | The machine (default this one) | |
display | text | What people call it: Acme | |
programs | list | Its program's names: acme, acme-cli | |
args | list | Patterns for its command line: acme/dist/cli\.js | |
titles | list | Patterns for its terminal's title: ^acme\b | |
screen | list | Patterns for a line it draws near the bottom, that says it is this agent | |
working | list | Patterns for a screen line that means it is working | |
asking | list | Patterns for a screen line that means it asks something | |
done | list | Patterns for a screen line that means its turn ended | |
icon | text | A letter or two, or a Hop icon's name | |
color | text | Its colour: #rrggbb |
$ hop do agent.kind.add <kind> [--option value…]
{"id":1,"call":"agent.kind.add","args":{"kind":"…"}}
agent.kind.remove act
Forget an AI agent a machine's Hop was taught
Take away the manifest agent.kind.add wrote on a machine (this one unless machine says another) for kind. Its daemon forgets it within a few seconds; a built-in kind it added to is as Hop knows it again. Says whether there was one.
| Argument | Kind | What | |
|---|---|---|---|
kind | text | needed | Its id |
machine | text | The machine (default this one) |
$ hop do agent.kind.remove <kind> [--option value…]
{"id":1,"call":"agent.kind.remove","args":{"kind":"…"}}
approval
approval.list read
The calls waiting on a machine for you to say yes
List the calls an AI program made with hop mcp --ask-first that wait on a machine for the person to say yes: each one's id, when it was asked, who asks (who), the command (call) and its arguments (args). event.watch says approval.asked when one comes and approval.ended when it is answered or gives up.
| Argument | Kind | What | |
|---|---|---|---|
machine | text | needed | Machine to ask |
$ hop do approval.list <machine>
{"id":1,"call":"approval.list","args":{"machine":"tower"}}
approval.answer never
Say yes or no to a call waiting on a machine
Answer a call waiting on a machine for the person to say yes (see approval.list): yes true lets it run, false refuses it. Only the person may: no grant is given this.
| Argument | Kind | What | |
|---|---|---|---|
machine | text | needed | Machine it waits on |
id | number | needed | Which call, as approval.list gives it |
yes | true/false | needed | true to let it run, false to refuse it |
$ hop do approval.answer <machine> <id> <yes>
{"id":1,"call":"approval.answer","args":{"machine":"tower","id":1,"yes":true}}
daemon
daemon.restart act
Have a machine's daemon become the Hop installed there now, keeping its sessions
After a newer Hop is installed on a machine, have the daemon that holds its sessions become that build. Every session is kept: the programs in them carry on without noticing, with their screens and history, and whatever shows them stays attached. When it cannot be done safely (the installed build cannot take the sessions over, or is the one already running) nothing changes and why says so. lost lists any session that did not survive, which should be none.
| Argument | Kind | What | |
|---|---|---|---|
machine | text | needed | Machine whose daemon to restart |
force | true/false | Restart even when the build installed is the one already running |
$ hop do daemon.restart <machine> [--option value…]
{"id":1,"call":"daemon.restart","args":{"machine":"tower"}}