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
hopCLI, daemon, hub, mcp, api
Hop.appthe desktop window
hop-traythe tray icon
iPhone, iPad, Apple TVthe Swift apps
Your appanything else

each holds the libraries it needs

Libraries
libhopcommands, addresses, grants
hop-muxpanes as data
hop-vtthe terminal engine
HopTerminala terminal view for iOS
HopSessionsreading a session
hop-padcontroller maps
hop-streamvideo, sound, input · planned

libhop asks its host, which uses SSH

On each machine
hop daemonsessions, workspaces
hop-windowswindows, video, mouse, keys
hop relaya stream's far side
The dashed box is a planned crate. Today its code is a module of the 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

LibraryWhereLanguageOne line
libhoplibhop/RustEvery Hop command (noun.verb), JSON in and out, with no I/O of its own
libhop C interfacelibhop/ffi/C, Swiftlibhop for any language that can call C
hop-muxmux/RustA multiplexer as data: workspaces, tabs, split panes, keys, drawing
hop-vtvt/RustGhostty's terminal engine: bytes in, screen and history out
hopvt C interfacevt/ffi/Chop-vt for Swift, Kotlin, C or a game engine
HopTerminalapple/HopTerminal/SwiftA native terminal view for iPhone and iPad
HopSessionsapple/HopSessions/SwiftWhat a session is and what it is doing, from its title and screen
HopCommandsapple/HopCommands/Swiftlibhop for an Apple app, with the app's own SSH as its host
hop-sdksdk/ts/TypeScriptEvery command as a typed call, over hop api or HTTP
hop.pysdk/python/PythonThe 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.

A callerCLI, SDK, AI, your app
The gatemay this caller run it?
libhopchecks arguments, picks the script
The hostfinds the machine, runs the script
SSHyour keys, one shared connection
The machineruns it, prints the answer
The answer comes back the same way, as a JSON object or an error with a code.

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

A programa shell, an agent
A ptyon its machine
hop daemonholds the session
hop-vtits screen and history
Attachframes, over SSH
A viewerthe app, a phone, any terminal
A viewer that attaches first gets the bytes that redraw the screen as it is now. The copy that counts is the daemon's.

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 inUse it when
hop api as a child processA script or program on a machine that has hop
ssh <host> hop apiThe program runs somewhere without Hop
hop api serve with a tokenA browser, a web app, or a program on another machine
hop mcpAn AI program
hop do, hop callA 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.

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:

Rules that keep this working