Build
The libraries
Hop is a few libraries with thin programs on top. Each library does one job, does no more I/O than that job needs, and is meant to be useful to a program that is not Hop. This page says what each is for and how they link up.
The picture
A program picks the libraries it needs and passes plain data between them: JSON and bytes. The libraries do not import each other. Everything a machine holds stays on that machine, and every machine is reached over your own SSH.
Programs
each holds the libraries it needs
Libraries
libhop asks its host, which uses SSH
On each machine
hop command (src/udp/).Programs that are not built from the libraries reach Hop from outside: the SDKs and any language over hop api, AI tools over hop mcp. Nothing needs the desktop app to be open.
At a glance
| Library | Where | Language | One line |
|---|---|---|---|
| libhop | libhop/ | Rust | Every Hop command (noun.verb), JSON in and out, with no I/O of its own |
| libhop C interface | libhop/ffi/ | C, Swift | libhop for any language that can call C |
| hop-mux | mux/ | Rust | A multiplexer as data: workspaces, tabs, split panes, keys, drawing |
| hop-vt | vt/ | Rust | Ghostty's terminal engine: bytes in, screen and history out |
| hopvt C interface | vt/ffi/ | C | hop-vt for Swift, Kotlin, C or a game engine |
| HopTerminal | apple/HopTerminal/ | Swift | A native terminal view for iPhone and iPad |
| HopSessions | apple/HopSessions/ | Swift | What a session is and what it is doing, from its title and screen |
| HopCommands | apple/HopCommands/ | Swift | libhop for an Apple app, with the app's own SSH as its host |
| hop-sdk | sdk/ts/ | TypeScript | Every command as a typed call, over hop api or HTTP |
| hop.py | sdk/python/ | Python | The same, in one file with no dependencies |
Each folder has a README with an example, what the library does not do, and how to build and test it.
libhop: the commands
The idea is your computers as an API. Everything on every machine you own has an address, and everything you can do to it is a command. Hop is only the first caller.
What it is. One list of commands such as session.list, window.look and file.copy. Each has a name, a JSON schema for its arguments, a level, and the logic: which script to run on a machine and how to read the answer. The command line, the MCP tools, hop api, both SDKs and the reference are all made from that list.
What it does not do. It never starts a process, reads a config file or draws anything. The program that embeds it supplies a host: which machines exist and how to run a script on one. On a desktop that is OpenSSH; in the iPhone and iPad app, the app's own SSH. It also does not carry bytes that flow: a terminal's output and a window's video run through their own libraries.
What else it is good for. Anything that should act on a person's machines: a Raycast or Stream Deck plugin, a launcher for a TV, a CI job, an AI agent, a whole other app.
let args = serde_json::json!({ "machine": "tower" });
let windows = libhop::call(host, "window.list", &args)?;
Build on Hop has the host and the C and Swift interfaces.
How one command travels
Every caller goes the same way. Only the left edge differs: words on a command line, a JSON line, an MCP message, an HTTP request.
- libhop decides what to run and how to read the answer. The host decides how it gets there.
- Many calls run at once. Over MCP,
hop apiand HTTP each call runs on its own and answers when it is done, so a slow one never holds up the rest. - You, at a terminal, are not gated. A program with an API token may use only its levels on its machines.
hop-mux: a multiplexer as data
What it is. The model behind Hop's tmux replacement: workspaces of tabs, each tab a tree of split panes, and the views people look through. Also key parsing, key bindings (tmux's by default), layout into cells, the status line, and painting frames onto a real terminal.
What it does not do. No I/O. It knows nothing about ptys, sessions or which terminal engine fills a pane. Changes go in as Ops, what changed comes out as Events, and a pane's contents arrive from outside as a Grid. Ops and the model are plain JSON.
What else it is good for. Any program that wants split panes with tmux-like keys: a TUI dashboard, a test harness that drives panes, another terminal app.
let mut model = Model::default();
let pane = json!({ "kind": "terminal" });
let events = model.apply(Op::NewWorkspace { name: Some("work".into()), pane })?;
hop-vt: the terminal engine
What it is. Ghostty's own terminal engine (libghostty-vt), built and linked in statically. Feed it the bytes a program writes. Ask it for the screen as text, as cells with styles, or as the bytes that redraw the same screen on another terminal.
Who uses it. The daemon on each machine, to keep every session's screen and history, so that anything attaching later sees it as it is.
What else it is good for. Reading what a terminal program is showing without a terminal: tests for CLI tools, a recorder, a server that keeps screens for clients that come and go.
let mut term = Terminal::new(80, 24, 5000); // columns, rows, lines of history term.write(bytes); // what the program wrote let last = term.text(10); // the last ten lines, as plain text
vt/ffi/ is the same engine behind a small C interface (hopvt.h), for anything that draws a terminal itself. Building it needs Zig 0.17.
How a terminal session flows
HopTerminal: a terminal view for iOS
What it is. A Swift package: a terminal view for iPhone and iPad, with the screen kept by hop-vt and drawn natively with Core Text. Touch, a hardware keyboard, and the row of keys a phone lacks.
What it does not do. It knows nothing about SSH, ptys or Hop. You give it bytes and it gives you bytes.
What else it is good for. Any iOS app that needs a real terminal: an SSH client, a container console, a serial monitor.
let view = TerminalView()
view.onInput = { bytes in connection.send(bytes) }
connection.onData = { bytes in view.feed(bytes) }
HopSessions: reading a session
What it is. A Swift package of pure rules: which program a title names, whether its screen says it is working or waiting for an answer, what to call it in a list, and what is worth a notification when the list changes.
What else it is good for. Anything that lists coding agents across machines: a widget, a watch app, a menu bar tool.
Programs.fromTitle("README.md - NVIM") // "nvim"
Session(name: "build", title: "✳ Claude Code").isAgent // true
The SDKs
sdk/ts (package hop-sdk) and sdk/python/hop.py make every command a call: hop.window.list({ machine: 'tower' }). Both speak hop api, and both are made from libhop's list, so they cannot drift from it. For programs has examples.
| Way in | Use it when |
|---|---|
hop api as a child process | A script or program on a machine that has hop |
ssh <host> hop api | The program runs somewhere without Hop |
hop api serve with a token | A browser, a web app, or a program on another machine |
hop mcp | An AI program |
hop do, hop call | A shell script |
The streaming pieces
These carry a window's video, sound and input between a machine and a viewer. They are modules today, written so that each end can be replaced.
- The helper,
hop-windows. One program per platform with the same messages. It lists windows, streams one as video, and performs the viewer's mouse, keys and controller. - The link. Sealed UDP packets, sent again when lost, put back in order, with parity so most losses need no round trip. SSH starts the stream and hands over the key.
hop relayruns on the window's machine, between the helper and the viewer. - The controller mapper. What each button and stick does on a machine, or in one app there. Pure: lines in, lines out.
Planned. The link becomes a crate, hop-stream; the mapper is already one, hop-pad. A command, stream.open, will return an offer that an app hands to hop-stream. libhop's command list becomes a registry, so a program links only what it uses. None of this is built yet.
Extending Hop
There are no loadable plugins. Hop is extended in two ways:
- By composition, at build time. Your program links the libraries it needs and passes data between them.
- From outside. Your program speaks
hop api, with a grant of its own when it comes over HTTP.
Rules that keep this working
- A new capability is a libhop command. Name it
noun.verb, take addresses, return a JSON object. Never add it only to the CLI, MCP, the app or a phone. - Libraries do no I/O beyond their job. libhop asks its host. hop-mux is handed grids. HopTerminal is handed bytes. That keeps them usable elsewhere and testable without machines.
- The control plane stays small. A command belongs in libhop when a script with no screen would want it and it works with no app open. Bytes that flow go through their own library.
- State lives on the machines. Sessions, workspaces and windows keep going when the caller goes away.