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.
- Choose one from the page, where each is drawn small.
- Change a copy of any, or start a New theme from the one in use. The editor puts each change on the whole window as you make it; nothing is kept until you save.
- Import a theme by pasting its JSON: one of Hop's, or a VS Code colour theme (the
.jsonfile inside its extension). Its workbench and terminal colours are mapped to Hop's. - Copy any theme's JSON to share it.
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" }
}
| Group | What it sets |
|---|---|
type | dark or light |
colors | background, 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 |
machines | each 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 |
tabs | style: raised, underline, flat or round; height 22–44, width 110–340, bar 32–68 (pixels) |
shape | corners in pixels: controls, tabs, panes, cards, popups, tools; and paneBorder 0–3 |
layout | gap between panes, 0–24 |
fonts | ui and mono: fonts installed on the computer, by name; size 11–18 |
terminal | background (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:
- shapes, arrows and dingbats (DejaVu Sans Mono);
- braille spinners, media symbols such as ⏺ and ⏸, and the block graphics of old computers (Noto Sans Symbols 2);
- the Nerd Font icons that prompts like Starship and editors like Neovim use (Nerd Fonts' symbols), so you need not install a patched font.
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:
- Terminal → Font: any font on the computer, by name. The field offers the monospaced ones installed (in a browser, Chrome can list them once you allow it), and draws a line of what terminals print in the font as you type. Empty is JetBrains Mono. It is also the font for code everywhere in the window.
- Terminal → Text size and Line height (1 to 2 times the text).
- Terminal → Ligatures, off unless you turn it on: runs like
=>,!=,===and->are drawn as the one sign the font makes of them, still a cell per character. Off, code in the window has none either. - Look → Window font: the font for everything else; empty is the theme's.
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:
| Uses | Lets it |
|---|---|
run | run commands on your machines (hop.run), which can do anything you can there |
read | read your tabs and what is in front: a terminal's text, program and folder (hop.tabs, hop.read, hop.selection, hop.here) |
control | open tabs, type, do Hop's actions (hop.open, hop.type, hop.do, hop.show) |
settings | read and change Hop's settings beyond its own (hop.setting) |
network | reach the internet, through Hop (hop.fetch) |
look | restyle 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 |
commands | call 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 line | Gives |
|---|---|
commands | every 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.