Use
For AI
hop mcp gives an AI tool the same reach you have: every machine's sessions, files, ports and app windows, and the Hop window in front of you. It speaks the Model Context Protocol, so it works with Claude Code and any other tool that does.
Set it up
For every AI app on this computer at once:
$ hop mcp add # Claude Code, Claude Desktop, Cursor, VS Code, Windsurf, Gemini CLI, Codex $ hop mcp add tower # the same on another machine $ hop mcp add --levels read # a look, but no hands
It finds the apps that are there, adds Hop to each one's settings (keeping the old file beside it as .before-hop) and says what it did. Or by hand, in Claude Code:
$ claude mcp add hop -- hop mcp
The next time Claude Code starts, it runs hop mcp and talks to it over stdin and stdout. Ask it something that needs another machine: "why is the build on tower failing?"
For a tool configured with JSON, the server is the command hop with the argument mcp:
{
"mcpServers": {
"hop": { "command": "hop", "args": ["mcp"] }
}
}
If the tool cannot find hop, give its full path (~/.local/bin/hop after ./install.sh).
What an agent can do
Each tool is one of Hop's commands, so it does exactly what the same command does from the command line. In short, an agent can:
- Get its bearings.
machines, thencontextfor one: its system, open apps, busiest programs, the folders work is happening in, ports and sessions.machine_statuschecks them all at once. - Work in terminals. Read any session (
session_read), type into it (session_send), start long jobs as sessions you can open in Hop to watch (session_new), andwaitfor one to finish. - Run commands and move files.
run,read_path,write_pathandcopy_path, between any two machines. - Use apps. List windows, read what one holds as text (
window_read), look at it as a picture (window_look), and press its buttons and fill its fields by name (element_press,element_fill). - Tell and ask you.
notifyshows a notification on your screen, andaskputs up a dialog and waits for your answer, a way to get your yes before something drastic. - Drive the Hop window. See your tabs (
hop_state), open a terminal, page, folder or app beside you (hop_open), and look at a pane as you see it (hop_look).
Reading a window as text is much cheaper for a model than a picture. Hop's instructions to the agent say so, and say to start with machines and context.
Every tool
Made from Hop's list of commands. Each links to its entry in the reference.
| Tool | Command | Level | What it does |
|---|---|---|---|
machines | machine.list | read | The computers Hop can reach |
context | machine.context | read | What is going on on a machine: apps, programs, folders, ports, sessions |
sessions | session.list | read | The terminal sessions on a machine, or on every machine |
session_read | session.read | read | What a session shows, as plain text |
session_send | session.send | act | Type into a session |
session_new | session.start | act | Start a terminal session that keeps running on its machine |
session_end | session.end | act | End a session and whatever runs in it |
run | shell.run | risky | Run a shell command on a machine and return what it printed |
read_path | file.read | read | Read a file (up to 2 MB) or list a folder on a machine |
ports | port.list | read | The TCP ports something is listening on, on a machine |
windows | window.list | read | The app windows open on a machine's screen |
window_look | window.look | read | A picture of one app window |
window_read | window.elements | read | What one app window holds: its buttons, fields, menus and text |
window_act | window.act | act | Work one app window with the mouse and keyboard |
apps | app.list | read | The apps installed on a machine |
app_open | app.open | act | Open an app on a machine and give its window's id |
hop_state | view.state | read | What the Hop window has open: tabs, panes, which is in front |
hop_open | view.open | act | Open a terminal, page, folder, window or app in a new tab |
hop_show | view.show | act | Bring a tab, pane, machine's tabs or page to the front |
hop_close | view.close | act | Close a tab or pane (its session keeps running) |
hop_command | view.command | act | Do one of the window's own commands, or list them |
hop_run | view.run | act | Do anything the window can by its action id, or list every action |
hop_keys | view.keys | act | Press the window's own shortcuts |
hop_settings | view.settings | act | Read every setting, read one, or change one |
hop_ui | view.elements | read | What is on the window's screen to press or fill, each with a ref |
hop_click | view.press | act | Press something view.elements listed |
hop_fill | view.fill | act | Type into a field view.elements listed |
hop_search | view.search | read | Search everything the window knows, as its search box does |
hop_type | view.type | act | Type into a pane: a terminal or an app window |
hop_act | view.act | act | Work an app window shown in a pane with the mouse and keys |
hop_look | view.look | read | See a pane as the person does: a picture, or a terminal's lines |
machine_status | machine.status | read | Whether each machine is up, its load, battery and Hop helpers |
write_path | file.write | risky | Write a file on a machine (replacing it whole) |
copy_path | file.copy | risky | Copy a file or folder from one machine to another (or within one) |
wait | wait | read | Wait until something is so: a session done, a port open, a window, a machine |
element_find | element.find | read | Find elements in a window by what they are: button "Play" |
element_press | element.press | act | Press an element: a button, link, checkbox or menu item |
element_fill | element.fill | act | Type into a field, replacing what it held |
notify | person.notify | act | Show the person a notification on a machine's screen |
ask | person.ask | act | Ask the person a question on a machine's screen and wait for the answer |
workspaces | workspace.list | read | The workspaces kept on a machine, or on every machine |
agents | agent.list | read | Every AI agent in a terminal, on every machine: working, needs you, done |
event.watch is not a tool, because it streams; an agent uses wait instead.
An agent at another computer
The hop_* tools drive the Hop app on the computer the agent runs on. When you are sitting at a different one (the agent runs on tower, you are on the laptop), they take on: the computer whose Hop app to drive. The app listens on a file only you can open (~/.config/hop/app.sock), never on the network; another of your machines reaches it over your own SSH.
Safety
An agent with hop mcp can do anything on your machines that you can over SSH. Add it only to tools you trust with that. Here is what keeps it in bounds:
- Levels. Every tool is read, act or risky (see Concepts). In Claude Code, each tool asks before it runs unless you allow it. A sensible start is to allow the read tools and keep asking for the rest.
- Only what you give it.
hop mcp --levels read,act --machines towerlists only the tools of those levels and refuses every other machine;claude mcp add hop -- hop mcp --levels readgives an agent a look but no hands. Without them it can do what you can. - Machines you have closed. What you turn off for a machine (
hop permissions tower --off control, or Settings → Machines) is refused to agents too, and the permission commands are not tools, so an agent cannot turn it back on. - Passwords stay secret. When an agent reads a window's elements, a password field's value is never read out. It sees that the field is there, not what is in it.
- No guessing. Pressing or filling an element refuses when the selector matches more than one. The agent has to say which.
- Real screens. The window tools act on the real screen of a computer someone may be using. Hop's instructions tell the agent to do what was asked and nothing more there.
- You see it. Sessions an agent starts are ordinary sessions: open them in Hop to watch, or end them. The app says so when another program starts driving it, and Settings → AI tools and scripts turns that off.
{
"permissions": {
"allow": [
"mcp__hop__machines", "mcp__hop__context", "mcp__hop__machine_status",
"mcp__hop__sessions", "mcp__hop__session_read", "mcp__hop__ports",
"mcp__hop__windows", "mcp__hop__window_read", "mcp__hop__window_look",
"mcp__hop__element_find", "mcp__hop__wait"
]
}
}
AI chat, in the app
The app comes with an AI chat add-on (Settings → Add-ons): a chat panel beside your tabs that reaches every machine. It is answered by Claude Code, Codex or Gemini CLI on this computer, as you are signed in to them, so a Pro or Max plan or your own API key pays for it, not Hop. The button at its top chooses the program and the model, and what it may do through Hop: only talk, look at your machines (Hop's read tools), or look and act. A chat with Claude Code is one of its sessions, so it remembers what it saw. For long work, run claude in a terminal tab after hop mcp add.
See also the recipe An AI that works across all your machines.
Agents in your terminals
Run Claude Code, Codex, Gemini CLI, opencode, Cursor's agent, aider, Amp, Goose, Crush, Qwen Code, Copilot CLI, Droid, Kimi or Auggie in any Hop terminal, on any machine, and Hop knows which it is and whether it is working, waiting for you, or done. Each machine's Hop daemon decides, so the tabs, the AI chat's list, the Machines page, the phone and hop agents all say the same, with the time it last changed: "finished 3:12 PM", "working · 4m". hop agent hooks add has Claude Code and Codex tell Hop each step themselves, which is exact; the others are read from their screens and titles.
An agent Hop does not know is taught with a few lines of data, on the machine it runs on. Say how to know it (its program's name, or patterns for its command line, title or screen) and, if you like, which screen lines mean it is working, asking or done:
hop agent kind add zai --programs zai,zai-cli --display Zai --color '#3366ff' \
--working '^\* thinking' --asking 'Approve\?' --machine tower
hop agent kinds tower # built in and taught
hop agent kind remove zai --machine tower
That writes ~/.config/hop/agents/zai.toml on tower, which you can also write by hand:
kind = "zai" display = "Zai" programs = ["zai", "zai-cli"] titles = ['^zai: '] working = ['^\* thinking'] asking = ['Approve\?'] color = "#3366ff"
The daemon there reads it within a few seconds. A file for a built-in kind adds to it: kind = "cursor-agent" with programs = ["cursor"]. The same is agent.kinds, agent.kind.add and agent.kind.remove from hop api and the SDKs.