Build
Build on Hop
Anything Hop can do, your program can do too: a Stream Deck button, a Raycast command, a launcher for the TV, a phone app, a whole new app. This page is for people building those.
Pick a way in
| You are writing | Use |
|---|---|
| A shell script | hop call, or the CLI with --json |
| A program in any language | hop api: JSON lines over stdio, locally or over SSH |
| TypeScript or Python | The SDKs, which speak hop api for you |
| A web page or a web app | The HTTP API with a token, or the TypeScript SDK over it |
| A Rust program | libhop, directly |
| An app in Swift, C, or anything that calls C (Kotlin, Go, Zig, C#) | libhop through its C interface, with a host of your own |
| Something inside the Hop app | An add-on (a .js file in the add-ons folder), or a theme |
Add-ons
Add-ons, small scripts that run inside the Hop app, are written up in The Hop app.
libhop
libhop is a Rust library holding Hop's list of commands: their names, arguments, levels and the logic of each, meaning the script it runs on a machine and how it reads the answer. The hop command, the desktop app, hop mcp and hop api are all made on it. So a command added there works everywhere at once.
libhop does not start processes, read Hop's config or draw anything. Whoever embeds it gives it a host, which provides three things:
- The machines: which there are, and how to find one by name.
- Running a script on one: given a machine, a shell script and stdin, return the exit status, stdout and stderr.
- The Hop window on this device, optionally, for the
view.*commands.
The desktop host reads ~/.ssh/config and config.toml and runs scripts with OpenSSH over shared connections. The iPhone and iPad app's host is its own SSH library (apple/HopCommands). Because every command is written against the host and not against SSH, it runs the same on each.
Every libhop command can be tested against a fake host that answers scripts with canned output, so tests need no machines.
The C interface
libhop/ffi builds libhop as a C library (libhop.a and a shared one) with one header, libhop/ffi/include/hop.h. Everything crosses it as JSON, so the header does not change when commands are added.
Hop *hop_new(HopHost host); /* libhop with your host */
char *hop_call(Hop *hop, const char *name, const char *args);
/* → {"ok": …} or {"error": {"code", "message"}}; blocks until done */
char *hop_stream(Hop *hop, const char *name, const char *args,
bool (*event)(void *context, const char *json), void *context);
/* calls `event` with each event until it returns false */
char *hop_parse_words(const char *name, const char *const *words, size_t count);
/* command-line words → the command's JSON arguments */
char *hop_schema(void); /* every command, as JSON Schema */
void hop_free(char *text);
void hop_release(Hop *hop);
The HopHost you pass is a struct of callbacks: machines (the machines, as JSON), resolve (one machine by name: its SSH destination and whether it is this device), exec (run sh -c script there with some stdin, and fill in the exit status, stdout and stderr), an optional view, and free. libhop may call them from several threads at once, since a command can ask several machines at the same time.
$ cargo build -p libhop-ffi $ cc -o myapp myapp.c -Ilibhop/ffi/include target/debug/libhop.a -framework CoreFoundation # on a Mac
libhop/ffi/tests/host.c is a complete small host that runs scripts on the computer it is on.
Swift
libhop/ffi/swift/LibHop.swift wraps the C interface. Your host is a Swift type with machines(), resolve(_:) and exec(_:script:input:).
let hop = LibHop(host: MyHost())
let found = try hop.call("window.list", ["machine": "tower"])
for try await event in hop.stream("event.watch", ["types": ["session.state"]]) {
print(event["address"] ?? "")
}
A failed call throws a HopError with the error's code and message.
For an app, apple/HopCommands is a Swift package of the same: libhop's C library as an xcframework (iPhone and iPad, Apple TV, both simulators, a Mac, built by its build.sh), and a host made of two async closures, the machines and running a script on one. Each call runs on a thread of its own and is awaited, so the main thread never waits. Hop's iPhone and iPad app uses it with its own SSH as the host.
let hop = HopCommands(
machines: { [HopMachine(name: "tower", dest: "me@tower.local", local: false)] },
exec: { machine, script, input in try await mySSH(machine).run(script, input) })
let listed = try await hop.call("file.list", ["folder": "tower:~/proj"])
From any language: hop api
If your program can start a process and read lines, it can use every command. Start hop api, read the hello, write {"id": 1, "call": "window.list", "args": {"machine": "tower"}}, read answers until one has "id": 1. The For programs page has the whole protocol and an example.
To reach a machine that is not this one, run it there: ssh -T tower hop api. To make typed calls, read hop api schema: every command's arguments are a JSON Schema.
Rules for a stable API
Others build on these commands, so they change carefully.
- Versioned. The protocol and command names are version 1. The hello says which version is speaking.
- Additive only. Within v1, changes add things: new commands, new optional arguments, new fields in results. Nothing is renamed or removed, and no argument becomes needed.
- Breaking needs a new version. v2 would be a new set of names, and v1 keeps answering beside it.
- Error codes are stable. Match on
code, not on the message, which is for people and may be reworded. - Ignore what you do not know. A result can gain fields at any time.
Adding a command to Hop
If you are changing Hop itself, these keep the list consistent:
- A new capability is a command in
libhop/src/commands/, never a CLI-only or MCP-only addition. The CLI, MCP, the SDKs and these docs pick it up from there. - Name it
noun.verb:machine,session,shell,file,port,window,element,app,event,person,view. - Take addresses (
tower:~/x,tower:window/Godot), not a machine and a path as two arguments. - Say the level honestly. Anything that writes, runs arbitrary code or reaches outward is risky.
- Return an object with stable field names. Write its text form for people, and keep nothing in the text that is not in the object.
- Test it against the fake host.
The command reference is made from the same list by site/docs/build-reference.mjs, which reads hop api schema. Run it after adding a command and the docs and search are up to date.