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 writingUse
A shell scripthop call, or the CLI with --json
A program in any languagehop api: JSON lines over stdio, locally or over SSH
TypeScript or PythonThe SDKs, which speak hop api for you
A web page or a web appThe HTTP API with a token, or the TypeScript SDK over it
A Rust programlibhop, 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 appAn 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 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.

Adding a command to Hop

If you are changing Hop itself, these keep the list consistent:

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.