The Hop app

The desktop app (and the same window in a browser, from hop hub): tabs from every machine, made to look the way you like with themes, and given more to do with add-ons.

Themes

A theme sets how the whole window looks: every colour, the terminal's sixteen colours, the corners of buttons, panes, cards and popups, the tab bar's style and sizes, the gap between panes, and the fonts. Settings → Look → Theme has Hop's own (Ember, Midnight, Forest, Graphite, Paper, which is light, Contrast and Studio); More, and your own… opens the Themes page.

Settings' highlight colour and fonts, when you pick them, go over the theme's own.

Safe to take from anyone

A theme is data, never code. Hop reads it through a fixed list of what it may set, and each value must be what that entry takes: a colour as #hex, a number within its range, one of a few words, or a font's name. Anything else is left out. So no theme can run anything, load anything from the internet (no url(), no web fonts) or reach past the one value it sets. Restyling Hop with code is an add-on's, and it has to say so (look, below).

What a theme file holds

Your themes are kept in settings.json under "themes", by name. Every group, and every value in it, may be left out:

{
  "name": "Harbor",
  "type": "dark",
  "colors": { "background": "#0b1a24", "panel": "#132a3a", "text": "#d6e4ee", "accent": "#ff9e64" },
  "tabs": { "style": "underline", "height": 30 },
  "shape": { "panes": 6, "controls": 6 },
  "layout": { "gap": 6 },
  "fonts": { "ui": "Inter", "mono": "JetBrains Mono", "size": 13 },
  "terminal": { "foreground": "#d6e4ee", "green": "#9ece6a", "red": "#f7768e" }
}
GroupWhat it sets
typedark or light
colorsbackground, background2, panel, card, line, text, dim, faint, strong, tabText, accent, onAccent, link, ok, warn, bad, on, paneFocus, ink (what hover and raised things are lightened with), shade (wells and shadows): each #rgb, #rrggbb or with alpha
machineseach machine's colour is a hue from its name; saturation 0–100 and lightness 20–85 (percent) set how vivid and light they all are. Light themes default to darker ones
tabsstyle: raised, underline, flat or round; height 22–44, width 110–340, bar 32–68 (pixels)
shapecorners in pixels: controls, tabs, panes, cards, popups, tools; and paneBorder 0–3
layoutgap between panes, 0–24
fontsui and mono: fonts installed on the computer, by name; size 11–18
terminalbackground (empty: the pane's), foreground, cursor, selection, and black … white, brightBlack … brightWhite

Fonts

Terminals are drawn in JetBrains Mono, which comes with Hop, so they look the same on every computer whatever it has installed. Whatever font you choose, Hop fills in what it lacks with fonts of its own, each made to fit a terminal's cells:

None of these takes a character that should be a colour emoji. Terminals also measure characters as Unicode 11 does, so emoji and wide characters take the two cells programs leave them.

In Settings:

In settings.json these are font, fontSize, lineHeight, ligatures and uiFont. A theme can set fonts too (its fonts group, below); Settings' go over the theme's. Programs can ask which fonts a machine has with font.list.

Add-ons

Settings → Add-ons lists the ones that come with Hop (AI chat, Machines at a glance, Containers, Weather, Pip and more); Add puts one to work at once. Add-ons' buttons wait under the puzzle piece, as a browser's extensions do: pin one to keep it in the bar (AI chat and Timer start pinned, and adding one pins its buttons), and its ⋯ or a right-click opens its settings and keys, its code, or removes it. An add-on can also offer themes (hop.theme), which are checked like any theme.

An add-on is one .js file in the app's add-ons folder, run with hop: buttons, panels, popovers, overlays, kinds of pane, actions with keys, its own settings, and ways to open tabs, run commands and type. Settings → Add-ons has an editor (+ Write your own) and lists everything hop offers under Writing your own.

// Name: Uptime
// About: How long each machine has been up, from a button.
// Icon: ⏱
// Uses: run

hop.button('Uptime', '⏱', () => {}, {
  popover: { title: 'Uptime', start: async body => {
    body.textContent = await hop.run(hop.machine, 'uptime');
  } },
});

Notifications

A terminal in a tab you are not looking at that waits for you, fails or finishes tells you so in a notification from Hop (Settings turns each off). Clicking it brings Hop forward at that tab and pane; if the tab was closed since, its session opens again in a new one. On a Mac, Hop asks once whether it may notify you, the first time it has something to say. An add-on's hop.notify(title, body, options) shows one too, with Hop's icon, which an add-on cannot change. options.image adds a picture, a PNG or JPEG of at most 2 MB, as a data: address or its bytes; options.onClick is called when it is clicked, once Hop has come forward. An add-on's notification never names a tab or pane, and one that did not come with Hop has its name before its title.

hop.notify('Tea', 'Your tea is ready', {
  image: 'data:image/png;base64,iVBORw0KGgo…',
  onClick: () => hop.toast('Enjoy'),
});

Phrases

An add-on can teach the palette words that do something. A pattern is words and slots; several patterns can be ways to say one thing:

hop.phrase(['Set a timer for {duration}', 'Set a timer for {duration} for {label:text}'],
  ({ duration, label }) => start(duration, label));
hop.phrase('Remind me at {when:time} to {what:text}', ({ when, what }) => …);

Slots are {duration} (milliseconds, from "10 minutes", "10m", "1h 30m", "90 seconds", "an hour", "half an hour"), {number}, {text} (the rest of the words, as typed) and {time} ("3pm", "15:30", "noon": the next such moment, in milliseconds); {name:type} gives one a name of its own. Reading is forgiving: any case, the little words (a, the, for, to) left out or put in, and the words before the first slot left out, so "timer 10m" is "Set a timer for 10 minutes". A phrase typed in full is listed as it reads filled in, ready to do; one still being typed ("set a ti") is listed as a suggestion ("Set a timer for …") that fills in the box. Phrases go with their add-on, and work from a sandbox too. hop.duration(text) reads a length of time the same way.

Its // Uses: line says what it reaches beyond its own things, and Hop shows that before it is added:

UsesLets it
runrun commands on your machines (hop.run), which can do anything you can there
readread your tabs and what is in front: a terminal's text, program and folder (hop.tabs, hop.read, hop.selection, hop.here)
controlopen tabs, type, do Hop's actions (hop.open, hop.type, hop.do, hop.show)
settingsread and change Hop's settings beyond its own (hop.setting)
networkreach the internet, through Hop (hop.fetch)
lookrestyle anything in Hop's window with CSS (hop.css), so it could hide or disguise parts of it; nothing that fetches (url(), @import) is allowed
commandscall Hop's own commands (hop.call) and watch its events (hop.events); see below

An add-on with no // Uses: line may use everything but Hop's commands.

Hop's commands

hop.call(name, args) runs any of Hop's commands through the app, the same ones the CLI, hop api and the SDKs call, and answers with its JSON object, or fails with its error (code and a sentence). Several calls go at once without waiting on each other. hop.events(filter, fn) watches event.watch and gives each event to fn; it returns a function that stops it, and it stops with the add-on.

// Uses: commands(agent.list, event.watch)

const { agents } = await hop.call('agent.list');
const stop = hop.events({ types: ['agent'] }, event => {
  if (event.type === 'agent.state' && event.state === 'needs_you') hop.toast(`${event.label} needs you`);
});

Its commands use says which, by level or by name:

On the lineGives
commandsevery command that only looks (read) and says what there is: sessions, windows, ports, AI agents, files by name
commands(read, act)every read and act command of that kind; each level is named on its own
commands(agent.list, event.watch)those commands, by their full names
commands(session.send)a command that runs or types whatever it is given (starting a terminal with a command, typing into a terminal or a window, opening an app by a command line): given only by its name, never by a level, so commands(act) gives only what acts without running or typing anything (ending sessions, closing windows, quitting apps)
commands(file.read)a command that shows what is on a machine (what a file holds, what a terminal shows, a window's picture or words): given only by its name, never by a level
commands(file.write)a risky command: given only by its name, never by a level

The reference marks each command that shows what is on a machine or runs what it is given. Before you add an add-on, Hop says what each one it names lets it do, on which machines: "read any file on tower, keys and passwords included", "type and run anything in the terminals on tower".

The window's own commands (view.*; an add-on has hop.tabs, hop.open and hop.do), permission.set and steps.run are never an add-on's. Every machine a call reaches, in an argument or an address such as tower:~/notes, must be one you chose for the add-on, and a command that asks every machine asks only those. What it says to you through person.notify and person.ask is led by its name. Hop checks each call in the page and again in the app, so a sandboxed add-on cannot reach further by what it sends. A command named that runs or types what it is given, or a risky one, can do anything you can on its machines: give it only to add-ons whose author you trust.

An add-on that did not come with Hop runs only once you trust it, and then in its own sandbox: an iframe with its own origin and a content policy that allows no network, which the app also forbids to navigate. It cannot touch Hop's page, storage or bridge to your machines; it can only send hop calls, which Hop answers or refuses by its Uses line. Inside a sandbox, hop's answers arrive later, so await them (which works in Hop's page too). What it draws in a popover, panel, pane or overlay is sent as a description and built again by Hop from a short list of plain elements: no scripts, links, outside pictures or url() in styles. Its overlays never take clicks, and Hop's own sheets and questions are drawn above anything it draws.