Herald Os Tailor

Tailor Herald OS

Herald OS is meant to be shaped by the person using it, and by you on their behalf. Use this when they ask to change how Herald OS looks or behaves: "make me a calm green theme", "use a bigger font", "add a shortcut for Obsidian", "do this every time I log in".

Ground rules:

• Change settings through os_ui commands, never by editing ~/.hermes/herald-os/prefs.json while the shell runs (it rewrites that file).
• Say what you changed and how to undo it in one sentence ("Switched to Dusk; say 'use the ocean theme' to go back").
• Ask before anything large or hard to undo, and keep a copy of any file you replace.

Themes

A theme recolours everything at once: the shell, your own CLI skin and, on Herald OS Linux, the compositor, GTK apps, the lock screen and the terminal.

• os_ui action=run command=theme.list, then theme.set args={"theme": "<name>"}.
• From an image: theme.generate args={"image": "<path>", "name": "<label>"} (optional "scheme": "dark" | "light"). It saves the theme, makes the image the wallpaper and applies it.
• From a description ("a sunset theme", "something like old paper"): write the theme yourself. Create ~/.config/herald-os/themes/<name>/theme.json with write_file, then run theme.set. <name> is the folder name: lowercase letters, digits and dashes. The file:

{
  "name": "sunset",
  "label": "Sunset",
  "description": "Warm dusk orange on deep plum.",
  "shell": { "scheme": "dark" },
  "wallpaper": "default",
  "colors": {
    "bg": "#170d14", "bg2": "#26131f", "surface": "#2e1726",
    "fg": "#fbefe9", "fg_dim": "#c4a0a4",
    "accent": "#ff8a4c", "accent_strong": "#ffa36e",
    "border_active": "#ff8a4c", "border_inactive": "#3e1f30",
    "urgent": "#ff6b6b", "ok": "#5fd39a", "warn": "#f2c25e"
  },
  "gtk": { "color_scheme": "prefer-dark", "theme": "Adwaita-dark" }
}

Every colour is #rrggbb. Text (fg) needs at least 7:1 contrast against bg, the accent at least 3:1. Dark themes keep bg very dark; light themes set "scheme": "light", a very light bg, dark fg, and "gtk": {"color_scheme": "default", "theme": "Adwaita"}. bg2 and surface are a few steps from bg toward the accent (dark) or toward white (light). A "terminal" block (background, foreground, cursor, a 16-colour palette) is optional; the shell derives one when it is missing. "wallpaper" is "default" (the drawn Herald wallpaper, tinted to the theme) or an image file inside the theme's folder.

• Someone shared a theme repository: theme.install args={"url": "https://…"}. Only colours and images are kept.
• Undo: theme.set args={"theme": "herald-ocean"}, the default.

Fonts and wallpaper

• font.list (optional filter), then font.set args={"family": "Inter"} for the interface or {"family": "JetBrains Mono", "kind": "mono"} for code and the terminal. "default" resets.
• wallpaper.set args={"image": "<path>"}, or "default" for the drawn wallpaper.

Widgets

A widget is a small web page that sits in the menu bar (a 24 px strip), on the Overview (a card) or in its own window. Make one when they want something to glance at: "a strip with the weather", "a CPU meter", "a countdown to Friday".

1. Write it into ~/.config/herald-os/plugins/<id>/ with write_file. <id> is lowercase letters, digits and dashes, and is the folder name.
2. manifest.json:

{
  "id": "weather-strip",
  "name": "Weather strip",
  "version": "1.0.0",
  "description": "The temperature here, in the menu bar.",
  "entry": "index.html",
  "placement": ["menubar"],
  "size": { "width": 90, "height": 96 },
  "permissions": ["storage"],
  "hosts": ["api.open-meteo.com"]
}

• placement: any of menubar, overview, panel. size.width is its menu-bar width (up to 240), size.height its Overview card height.
• permissions: only what it needs. stats (CPU, memory, disks, battery), notify, storage (its own small key-value store) and run:<command.id> for each Herald OS command it runs, such as run:page.open. Commands that change things still ask the person.
• hosts: the HTTPS hosts it fetches from. Nothing else is reachable, and the API must allow cross-origin requests (most public JSON APIs do).

3. index.html loads the SDK and its own script file. Inline <script> is blocked; inline styles are fine. Keep the background transparent so it sits on the shell's glass.

<!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <script src="herald-plugin://sdk/widget.js"></script>
    <script src="widget.js" defer></script>
  </head>
  <body style="margin: 0; font: 500 11px/24px system-ui; color: var(--herald-fg)">
    <span id="out">…</span>
  </body>
</html>

4. The SDK in widget.js:
   • await herald.stats() gives { cpuPercent, memoryUsed, memoryTotal, disks, battery, uptimeSeconds }.
   • herald.notify(title, body), herald.storage.get(key) and herald.storage.set(key, value).
   • herald.run('page.open', { name: 'missions' }) runs a Herald OS command it was granted.
   • herald.placement is where it sits (menubar, overview or panel), also set as data-placement on <html> for CSS.
   • The theme arrives as CSS variables: --herald-bg, --herald-surface, --herald-fg, --herald-fg-dim, --herald-accent, --herald-line, --herald-ok, --herald-warn, --herald-urgent; herald.onTheme(colors => …) hears changes.
5. Never turn it on yourself. Say: "It's in Settings > Plugins; turn on Weather strip there after checking what it asks for." os_ui action=run command=plugin.manage shows that page. Once it is on, every saved change reloads it, so iterate by editing the files.
6. To share it, the folder is a git repository; others install it with herald-os plugin add <url> (it arrives turned off for them too).

The menu bar

• bar.layout lists the items left to right (search, widgets, voice, indicators, usage, wifi, bluetooth, sound, battery, notifications, clock) and which are shown.
• bar.hide item=bluetooth, bar.show item=battery. The status lights (indicators: recording, dictation, switches that are on) always show; say why if asked to hide them.
• bar.move item=clock position=first (also last, a number with 1 leftmost, or before= / after= another item).
• bar.clock hours=24 (12, system), seconds=true, date=none (short, long).
• bar.reset puts it all back. Settings > Appearance > Menu bar shows the result.