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

CommandLevelWhat it does
machine.listreadThe computers Hop can reach
machine.contextreadWhat is going on on a machine: apps, programs, folders, ports, sessions
machine.statusreadWhether each machine is up, its load, battery and Hop helpers
machine.editriskyChange a machine's name, or the user, address or port Hop signs in to it with
session.listreadThe terminal sessions on a machine, or on every machine
session.readreadWhat a session shows, as plain text
session.sendactType into a session
session.startactStart a terminal session that keeps running on its machine
session.endactEnd a session and whatever runs in it
session.end_allactEnd every session on a machine
shell.runriskyRun a shell command on a machine and return what it printed
file.readreadRead a file (up to 2 MB) or list a folder on a machine
file.writeriskyWrite a file on a machine (replacing it whole)
file.copyriskyCopy a file or folder from one machine to another (or within one)
file.listreadA folder's entries on a machine, each with its kind, size and date
file.findreadWhere a relative path a program printed is, on a machine
file.searchreadFiles and folders under a folder whose name holds some text
file.moveriskyMove or rename a file or folder on a machine
file.mkdirriskyMake a folder on a machine
file.trashriskyPut a file or folder in a machine's trash, from where file.restore puts it back
file.restoreriskyPut a file or folder back out of a machine's trash
file.openactOpen a file with a machine's own app, on that machine's screen
file.syncriskyMake a folder like another, on one machine or between two (rsync, one way)
port.listreadThe TCP ports something is listening on, on a machine
window.listreadThe app windows open on a machine's screen
window.lookreadA picture of one app window
window.elementsreadWhat one app window holds: its buttons, fields, menus and text
window.actactWork one app window with the mouse and keyboard
window.closeactClose an app window: its app is asked to quit
app.listreadThe apps installed on a machine
app.openactOpen an app on a machine and give its window's id
app.hiddenreadThe apps a machine runs out of sight, in displays of Hop's own
app.quitactQuit an app a machine runs out of sight
app.revealactMove an app a machine runs out of sight to that machine's own screen
app.iconsreadThe icons of apps installed on a machine
view.statereadWhat the Hop window has open: tabs, panes, which is in front
view.openactOpen a terminal, page, folder, window or app in a new tab
view.popupriskyRun a command in a terminal floating over the Hop app, gone when it ends
view.showactBring a tab, pane, machine's tabs or page to the front
view.closeactClose a tab or pane (its session keeps running)
view.commandactDo one of the window's own commands, or list them
view.runactDo anything the window can by its action id, or list every action
view.keysactPress the window's own shortcuts
view.settingsactRead every setting, read one, or change one
view.elementsreadWhat is on the window's screen to press or fill, each with a ref
view.pressactPress something view.elements listed
view.fillactType into a field view.elements listed
view.searchreadSearch everything the window knows, as its search box does
view.typeactType into a pane: a terminal or an app window
view.actactWork an app window shown in a pane with the mouse and keys
view.lookreadSee a pane as the person does: a picture, or a terminal's lines
folder.listreadThe folders a machine knows of, best first, to find one by name
event.watchreadStream changes on machines: sessions, windows, ports, up and down
waitreadWait until something is so: a session done, a port open, a window, a machine
element.findreadFind elements in a window by what they are: button "Play"
element.pressactPress an element: a button, link, checkbox or menu item
element.fillactType into a field, replacing what it held
person.notifyactShow the person a notification on a machine's screen
person.askactAsk the person a question on a machine's screen and wait for the answer
permission.listreadWhat Hop may do on each machine, what is missing, and how to fix it
permission.setriskyTurn seeing or working a machine's windows on or off in Hop
permission.askactAsk a Mac's person to let Hop see and work its windows
steps.runriskyRun a list of Hop calls in order, on the machines they name or others
mcp.addriskyConnect the AI apps on a machine to Hop (adds Hop's MCP server to each)
font.listreadThe fonts installed on a machine, and which are monospaced
workspace.listreadThe workspaces kept on a machine, or on every machine
workspace.getreadOne workspace: its windows and what each pane shows
workspace.saveactKeep a workspace on a machine
workspace.removeactForget a workspace kept on a machine
workspace.foldersreadProject folders on a machine, or on every machine, to start a workspace in
usage.listreadHow much of their plans' limits the AI programs on a machine have used
pad.listreadWhich machines take game controllers, and the map each uses
pad.map.getreadWhat a controller's buttons and sticks do on a machine, or in one app there
pad.map.setactChange what a controller does on a machine, or in one app there
agent.listreadEvery AI agent in a terminal, on every machine: working, needs you, done
agent.reportactTell a machine's daemon what an AI agent in a session is doing
agent.hooks.addriskyHave the AI agents on a machine tell Hop each step they take (their hooks)
agent.hooks.removeriskyTake Hop's hooks out of the AI agents' settings on a machine
agent.kindsreadThe kinds of AI agent a machine's Hop knows, built in and taught
agent.kind.addactTeach a machine's Hop an AI agent it does not know, with no code
agent.kind.removeactForget an AI agent a machine's Hop was taught
approval.listreadThe calls waiting on a machine for you to say yes
approval.answerneverSay yes or no to a call waiting on a machine
daemon.restartactHave 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

MCP machines

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

MCP context

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.

ArgumentKindWhat
machinetextneededMachine 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

CLI hop statusMCP machine_status

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.

ArgumentKindWhat
machinetextMachine 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

MCP not a tool

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.

ArgumentKindWhat
machinetextneededThe machine to change
nametextIts new name in Hop
addresstextWhere SSH goes, whole: host, user@host, user@host:port, or a Host from ~/.ssh/config
usertextThe user to sign in as; empty to leave it to ssh
hosttextIts host name or IP address
portnumberThe port SSH listens on; 0 to leave it to ssh (22, unless the SSH config says)
plaintrue/falseKeep 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

MCP sessions

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.

ArgumentKindWhat
machinetextMachine 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

MCP session_readShows what is on the machine, not only facts about it

Read what a session shows: its last lines as plain text, scrolled-off history included.

ArgumentKindWhat
machinetextneededMachine the session is on
nametextneededSession name
linesnumberHow 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

MCP session_sendRuns or types whatever it is given

Type text into a session, as if at its keyboard. With enter, press Enter after it.

ArgumentKindWhat
machinetextneededMachine the session is on
nametextneededSession name
texttextneededWhat to type
entertrue/falsePress 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

MCP session_newRuns or types whatever it is given

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.

ArgumentKindWhat
machinetextneededMachine to start it on
commandtextShell command to run in it
cwdtextFolder to start in (default: home)
nametextName for it: letters, digits, - and _
historynumberLines 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

MCP session_end

End a session and whatever is running in it.

ArgumentKindWhat
machinetextneededMachine the session is on
nametextneededSession 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

MCP not a tool

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.

ArgumentKindWhat
machinetextneededMachine 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

CLI hop runMCP runShows what is on the machine, not only facts about itRuns or types whatever it is given

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.

ArgumentKindWhat
machinetextneededMachine to run it on
commandtextneededShell command
timeoutnumberSeconds 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

MCP read_pathShows what is on the machine, not only facts about it

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.

ArgumentKindWhat
machinetextneededMachine the path is on
pathtextneededFile or folder
limitnumberRead 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)

CLI hop writeMCP write_path

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.

ArgumentKindWhat
toaddressneededWhere: machine:path, such as tower:~/proj/notes.md
texttextThe contents, as text
base64textThe 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)

CLI hop cpMCP copy_path

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.

ArgumentKindWhat
fromaddressneededWhat to copy: machine:path
toaddressneededWhere 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

MCP not a tool

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.

ArgumentKindWhat
folderaddressneededThe 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

MCP not a tool

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.

ArgumentKindWhat
machinetextneededMachine to look on
pathtextneededThe 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

MCP not a tool

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.

ArgumentKindWhat
folderaddressneededThe folder to search: machine:path, such as tower:~/proj
querytextneededText 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

CLI hop mvMCP not a tool

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.

ArgumentKindWhat
fromaddressneededWhat to move: machine:path
toaddressneededIts 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

CLI hop mkdirMCP not a tool

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.

ArgumentKindWhat
folderaddressneededThe folder to make: machine:path
uniquetrue/falseNever 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

CLI hop trashMCP not a tool

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.

ArgumentKindWhat
pathaddressneededWhat 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

MCP not a tool

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.

ArgumentKindWhat
trashedaddressneededWhere it is in the trash: machine:path
toaddressWhere 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

MCP not a toolRuns or types whatever it is given

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.

ArgumentKindWhat
pathaddressneededWhat 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)

CLI hop syncMCP not a tool

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.

ArgumentKindWhat
fromaddressneededThe folder to copy from: machine:path
toaddressneededThe folder to make like it: machine:path (made when missing)
dry_runtrue/falseOnly say what would change
deletetrue/falseAlso delete what is in to but not in from (a mirror)
excludelistNames 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

CLI hop portsMCP ports

List the TCP ports something is listening on, on a machine, with the program behind each.

ArgumentKindWhat
machinetextneededMachine 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

CLI hop windowsMCP windows

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.

ArgumentKindWhat
machinetextneededMachine to ask
iconstrue/falseGive 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

CLI hop shotMCP window_lookShows what is on the machine, not only facts about it

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.

ArgumentKindWhat
machinetextneededMachine the window is on
windownumberneededThe window's id, from window.list
maxnumberLongest 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

CLI hop elementsMCP window_readShows what is on the machine, not only facts about it

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.

ArgumentKindWhat
machinetextneededMachine the window is on
windownumberneededThe 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

MCP window_actRuns or types whatever it is given

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.

ArgumentKindWhat
machinetextneededMachine the window is on
windownumberneededThe window's id, from window.list
stepslist of stepsneededWhat 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

MCP not a tool

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.

ArgumentKindWhat
machinetextneededMachine the window is on
windownumberneededThe window's id, from window.list
forcetrue/falseEnd the app if it has not quit when asked
apptextClose 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

CLI hop appsMCP apps

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.

ArgumentKindWhat
machinetextneededMachine to ask
detailtrue/falseGive 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

MCP app_openRuns or types whatever it is given

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.

ArgumentKindWhat
machinetextneededMachine to open it on
apptextneededThe 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

MCP not a tool

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).

ArgumentKindWhat
machinetextneededMachine 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

MCP not a tool

Quit an app that runs in a display of Hop's own (see app.hidden), and everything it started there.

ArgumentKindWhat
machinetextneededMachine it runs on
windowtextneededIts 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

MCP not a tool

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.

ArgumentKindWhat
machinetextneededMachine it runs on
windowtextneededIts 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

MCP not a tool

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.

ArgumentKindWhat
machinetextneededMachine the apps are on
appslistneededThe 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

MCP hop_state

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.

ArgumentKindWhat
ontextThe 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

MCP hop_openRuns or types whatever it is given

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).

ArgumentKindWhat
machinetextneededMachine the thing is on
ontextThe 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)
kindtextterminal, web, files, window or app (default terminal)
sessiontextterminal: a session's name, to show that one
runtextterminal: a line typed into it as it starts
urltextweb: an address, such as http://localhost:3000/
pathtextfiles: the folder or file
windownumberwindow: its id, from window.list
apptextapp: 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

MCP not a toolRuns or types whatever it is given

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).

ArgumentKindWhat
ontextThe 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)
machinetextMachine to run it on (default: the pane in front's)
commandtextWhat to run, as a shell line (default: a shell)
cwdtextFolder to run it in (default: the pane in front's, else home)
titletextWhat its frame says (default: the command)
widthtextIts width: "80%" of the window, or columns (default 80%)
heighttextIts height: "80%" of the window, or rows (default 80%)
keeptrue/falseStay 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

MCP hop_show

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).

ArgumentKindWhat
ontextThe 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)
tabnumberTab to go to
panenumberPane to go to
machinetextShow this machine's tabs; "all" for every machine's
pagetexthome, 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)

MCP hop_close

Close a tab or one pane of the Hop app. A terminal's session keeps running on its machine.

ArgumentKindWhat
ontextThe 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)
tabnumberTab to close
panenumberPane 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

MCP hop_command

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.

ArgumentKindWhat
ontextThe 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)
idtextThe command; leave out to list them all
tabnumberTab to do it in
panenumberPane 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

MCP hop_run

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.

ArgumentKindWhat
ontextThe 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)
idtextThe action; leave out to list them
argslistWhat it takes, if anything (tab takes a number 1–9)
tabnumberTab to do it in
panenumberPane 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

MCP hop_keys

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.

ArgumentKindWhat
keystextneededThe shortcut
ontextThe 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

MCP hop_settingsRuns or types whatever it is given

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).

ArgumentKindWhat
ontextThe 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)
nametextA setting
valuetextIts 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

MCP hop_ui

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.

ArgumentKindWhat
ontextThe 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)
wheretextOnly this part: bar, palette, popup, page, or "pane 3"
findtextOnly 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

MCP hop_click

Press something view.elements listed, by its ref.

ArgumentKindWhat
reftextneededIts ref, such as e12
ontextThe 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

MCP hop_fillRuns or types whatever it is given

Type into a field view.elements listed, replacing what it held; with enter, then press Enter.

ArgumentKindWhat
reftextneededIts ref
texttextneededWhat to put in it
ontextThe 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)
entertrue/falsePress 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

MCP hop_search

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.

ArgumentKindWhat
querytextneededWhat to look for (a machine's name narrows it to that machine)
ontextThe 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)
picknumberOpen 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

MCP hop_typeRuns or types whatever it is given

Type into a pane of the Hop app: a terminal (as at its keyboard) or an app window. The person sees it happen.

ArgumentKindWhat
texttextneededWhat to type
ontextThe 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)
panenumberThe pane; the one in front when left out
entertrue/falsePress 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

MCP hop_actRuns or types whatever it is given

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.

ArgumentKindWhat
panenumberneededThe app window's pane
stepslist of stepsneededWhat to do, in order
ontextThe 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

MCP hop_lookShows what is on the machine, not only facts about it

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.

ArgumentKindWhat
ontextThe 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)
panenumberThe pane; the one in front when left out
linesnumberTerminal: 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

MCP not a tool

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.

ArgumentKindWhat
machinetextMachine to look on; leave out for all of them
scantrue/falseWalk 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

CLI hop eventsMCP not a tool (it streams)Streams events until cancelled

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.

ArgumentKindWhat
machineslistMachines to watch (default: all of them)
typeslistOnly these types, or kinds of type: ["session.state", "window"] (default: all)
everynumberSeconds between looks (default 2)
initialtrue/falseFirst 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

CLI hop waitMCP waitShows what is on the machine, not only facts about it

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.

ArgumentKindWhat
foraddressneededWhat to wait for: tower:session/build, tower:port/3000, tower:window/Godot, tower:~/out.txt, mac:Calculator >> button "7", tower
statetextThe state to wait for (see above)
timeoutnumberSeconds 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"

CLI hop findMCP element_findShows what is on the machine, not only facts about it

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.

ArgumentKindWhat
targetaddressneededThe 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

CLI hop pressMCP element_pressShows what is on the machine, not only facts about it

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.

ArgumentKindWhat
targetaddressneededThe 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

CLI hop fillMCP element_fillShows what is on the machine, not only facts about itRuns or types whatever it is given

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.

ArgumentKindWhat
targetaddressneededThe element: machine:app >> selector, such as mac:Calculator >> button "7" (or machine:window/12 >> …)
texttextneededWhat to put in it
entertrue/falsePress 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

CLI hop notifyMCP notify

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.

ArgumentKindWhat
texttextneededWhat to say
titletextA title (default Hop)
ontextThe 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

CLI hop askMCP ask

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.

ArgumentKindWhat
questiontextneededWhat to ask
choiceslistThe answers to choose from, the yes first (default ["Yes", "No"])
timeoutnumberSeconds to wait for an answer (default 120)
ontextThe 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

CLI hop permissionsMCP not a tool

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.

ArgumentKindWhat
machinetextOne 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

MCP not a tool

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.

ArgumentKindWhat
machinetextneededThe machine
whattextneededsee or control
ontrue/falseneededtrue 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

CLI hop allowMCP not a tool

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.

ArgumentKindWhat
machinetextThe 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

MCP not a toolShows what is on the machine, not only facts about itRuns or types whatever it is given

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.

ArgumentKindWhat
stepslist of stepsneededThe calls, in order: [{"call": name, "args": {…}}, …]
ontextRun them on this machine instead
machinesobjectWhere each machine's steps run instead: {"tower": "server"}
keep_goingtrue/falseGo 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)

MCP not a tool

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.

ArgumentKindWhat
machinetextThe machine (default this one)
appstextOnly these, comma-separated (default: every one found)
levelstextWhat 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

MCP not a tool

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).

ArgumentKindWhat
machinetextneededMachine 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

MCP workspaces

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.

ArgumentKindWhat
machinetextMachine 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

MCP not a tool

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.

ArgumentKindWhat
machinetextneededMachine the workspace is kept on (its home)
nametextneededWorkspace 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

MCP not a toolRuns or types whatever it is given

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.

ArgumentKindWhat
machinetextneededMachine the workspace is kept on (its home)
nametextneededWorkspace name: letters, digits, '.', '-' and '_'
workspaceobjectneededThe workspace: { windows: [...], active? }
if_updatednumberSave 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

MCP not a tool

Remove a workspace from its home machine. Its terminal sessions keep running; only the layout is forgotten.

ArgumentKindWhat
machinetextneededMachine the workspace is kept on (its home)
nametextneededWorkspace 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

MCP not a tool

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 ~.

ArgumentKindWhat
machinetextMachine to look on; leave out for all of them
rootslistFolders to look in, with ~ for home (default: the usual homes of code)
only_rootstrue/falseOnly 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

CLI hop usageMCP not a tool

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.

ArgumentKindWhat
machinetextMachine 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

MCP not a tool

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.

ArgumentKindWhat
machinetextOne 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

MCP not a tool

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).

ArgumentKindWhat
machinetextneededThe machine the windows are on
apptextOne 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

MCP not a tool

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"}}.

ArgumentKindWhat
machinetextneededThe machine the windows are on
apptextOne app there, by name (Godot); left out, the machine's own map
mapobjectThe whole map: buttons, left, right, dead, speed
presettextA ready-made map: pad, desktop or wasd
resettrue/falsetrue 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

CLI hop agentsMCP agents

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.

ArgumentKindWhat
machineslistMachines 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

MCP not a tool

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.

ArgumentKindWhat
sessionaddressneededThe session the agent is in: tower:session/build
eventtextneededThe hook's event: Stop, PermissionRequest, …
reportobjectWhat the hook was given, as JSON (session_id, message, tool_name, …)
kindtextThe 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)

MCP not a tool

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).

ArgumentKindWhat
machinetextThe machine (default this one)
appstextOnly 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

MCP not a tool

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).

ArgumentKindWhat
machinetextThe machine (default this one)
appstextOnly 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

MCP not a tool

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.

ArgumentKindWhat
machinetextThe 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

MCP not a tool

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.

ArgumentKindWhat
kindtextneededIts id: acme, my-agent
machinetextThe machine (default this one)
displaytextWhat people call it: Acme
programslistIts program's names: acme, acme-cli
argslistPatterns for its command line: acme/dist/cli\.js
titleslistPatterns for its terminal's title: ^acme\b
screenlistPatterns for a line it draws near the bottom, that says it is this agent
workinglistPatterns for a screen line that means it is working
askinglistPatterns for a screen line that means it asks something
donelistPatterns for a screen line that means its turn ended
icontextA letter or two, or a Hop icon's name
colortextIts 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

MCP not a tool

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.

ArgumentKindWhat
kindtextneededIts id
machinetextThe 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

MCP not a tool

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.

ArgumentKindWhat
machinetextneededMachine 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

MCP not a tool

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.

ArgumentKindWhat
machinetextneededMachine it waits on
idnumberneededWhich call, as approval.list gives it
yestrue/falseneededtrue 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

MCP not a tool

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.

ArgumentKindWhat
machinetextneededMachine whose daemon to restart
forcetrue/falseRestart 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"}}