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:

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.

ToolCommandLevelWhat it does
machinesmachine.listreadThe computers Hop can reach
contextmachine.contextreadWhat is going on on a machine: apps, programs, folders, ports, sessions
sessionssession.listreadThe terminal sessions on a machine, or on every machine
session_readsession.readreadWhat a session shows, as plain text
session_sendsession.sendactType into a session
session_newsession.startactStart a terminal session that keeps running on its machine
session_endsession.endactEnd a session and whatever runs in it
runshell.runriskyRun a shell command on a machine and return what it printed
read_pathfile.readreadRead a file (up to 2 MB) or list a folder on a machine
portsport.listreadThe TCP ports something is listening on, on a machine
windowswindow.listreadThe app windows open on a machine's screen
window_lookwindow.lookreadA picture of one app window
window_readwindow.elementsreadWhat one app window holds: its buttons, fields, menus and text
window_actwindow.actactWork one app window with the mouse and keyboard
appsapp.listreadThe apps installed on a machine
app_openapp.openactOpen an app on a machine and give its window's id
hop_stateview.statereadWhat the Hop window has open: tabs, panes, which is in front
hop_openview.openactOpen a terminal, page, folder, window or app in a new tab
hop_showview.showactBring a tab, pane, machine's tabs or page to the front
hop_closeview.closeactClose a tab or pane (its session keeps running)
hop_commandview.commandactDo one of the window's own commands, or list them
hop_runview.runactDo anything the window can by its action id, or list every action
hop_keysview.keysactPress the window's own shortcuts
hop_settingsview.settingsactRead every setting, read one, or change one
hop_uiview.elementsreadWhat is on the window's screen to press or fill, each with a ref
hop_clickview.pressactPress something view.elements listed
hop_fillview.fillactType into a field view.elements listed
hop_searchview.searchreadSearch everything the window knows, as its search box does
hop_typeview.typeactType into a pane: a terminal or an app window
hop_actview.actactWork an app window shown in a pane with the mouse and keys
hop_lookview.lookreadSee a pane as the person does: a picture, or a terminal's lines
machine_statusmachine.statusreadWhether each machine is up, its load, battery and Hop helpers
write_pathfile.writeriskyWrite a file on a machine (replacing it whole)
copy_pathfile.copyriskyCopy a file or folder from one machine to another (or within one)
waitwaitreadWait until something is so: a session done, a port open, a window, a machine
element_findelement.findreadFind elements in a window by what they are: button "Play"
element_presselement.pressactPress an element: a button, link, checkbox or menu item
element_fillelement.fillactType into a field, replacing what it held
notifyperson.notifyactShow the person a notification on a machine's screen
askperson.askactAsk the person a question on a machine's screen and wait for the answer
workspacesworkspace.listreadThe workspaces kept on a machine, or on every machine
agentsagent.listreadEvery 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:

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