Scripts are the plugin API.

Drop an executable into ~/.config/scuttlarr/scripts/ and its trigger word joins the launcher grammar — no restart, no store, no manifest file. Any language. The bundled scripts (json, ip) are reference implementations and yours to edit.

The contract — two invocations

<script> manifest — print a JSON manifest to stdout, exit 0

{
  "trigger": "uuid",
  "name": "UUID",
  "description": "Generate a v4 UUID"
}

<script> query <args> — called on every keystroke (debounced)

{
  "items": [
    {
      "title": "Copy 3f9c1e2a-7b4d-4c8e-9a1f-2d6b8e4c0a55",
      "subtitle": "v4 · fresh every keystroke",
      "action": { "type": "copy", "value": "3f9c1e2a-7b4d-4c8e-9a1f-2d6b8e4c0a55" }
    }
  ]
}

actionscopy puts text on the clipboard, open opens a URL, file or app, none is informational. altAction runs on ⌥⏎.

timeoutsManifest 1.5s, query 3s. A slow script gets killed, not waited for. stderr is ignored; non-zero exit = no results.

rulesUp to 8 items shown. Triggers are whole-word, first registration wins. clip is built-in and can’t be claimed.

python gotchaThe scripts dir is sys.path[0] — a script named json.py shadows the stdlib. Bundled scripts del sys.path[0] first; do the same.

Network is your business for scripts: fetch what you like, and mind the timeouts above.

Config

Everything lives in ~/.config/scuttlarr/config.json — watched and hot-applied, in sync with the settings window both ways. Themes are token overlays; unknown names fall back safely so a hand-edit can’t blank the UI.

{
  "theme": "scuttlarr",
  "themes": { "my-theme": { "accent": "#ff176c" } },
  "bar": {
    "enabled": true,
    "layout": {
      "left":   [{ "id": "workspaces" }, { "id": "agents" }, { "id": "frontApp" }],
      "center": [{ "id": "clock" }],
      "right":  [{ "id": "wifi" }, { "id": "battery" }]
    }
  },
  "agents": { "askMode": false, "askProvider": "claude" },
  "desktop": {
    "tiling":  { "enabled": false, "managed": true, "modifier": "alt", "gaps": 8,
                 "workspaces": 6, "float": ["com.raycast.macos"] },
    "borders": { "enabled": false, "width": 5, "style": "round" },
    "cornerRadius": null
  }
}

Bar modules live in explicit left / center / right zones and render in the order you list them. The clock is an ordinary module — put it wherever you like. Displays with a notch have no usable center, so they take an optional bar.notchedLayout of the same shape; without one, the main layout applies with the center folded into the head of the right zone.

desktop is the tiling layer, off by default. Turn on tiling.enabled (or pick tiling in setup) and scuttlarr renders ~/.config/aerospace/aerospace.toml from these few knobs and reloads AeroSpace live. Set tiling.managed to false and the file is yours — scuttlarr never writes it again. Borders (JankyBorders) are opt-in from Settings → Desktop and take their colours from the theme; cornerRadius sets macOS’s hidden window-corner default (1–26, apps relaunch to pick it up).

Panel triggers

Some trigger words open a full keyboard-driven TUI panel inside the launcher window instead of returning rows. They fuzzy-match like apps, so you don’t have to type them exactly. Esc walks back; focus returns exactly where it was — including over a full-screen app.

agents ⏎coding agent sessions

usage ⏎token monitor

updates ⏎app updates

awake ⏎keep-alive sessions

wifi ⏎networks & power

dns ⏎network info

audio ⏎volume & devices

clipboard ⏎history & search

screenshots ⏎latest captures

aerospace ⏎workspaces & tiling

help ⏎commands & keys

usage ⏎ and agents ⏎ are gated on the agent settings — both are off until you turn them on.

Uninstall

No installer, no daemons left behind. Four paths and it’s gone:

$ rm -rf /Applications/scuttlarr.app \
     ~/.config/scuttlarr \
     ~/Library/Application\ Support/com.mitchmalone.scuttlarr \
     ~/Library/LaunchAgents/scuttlarr.plist

Installed with Homebrew? brew uninstall handles the app; the three dotfile paths are still yours to remove. AeroSpace (installed alongside as a cask dependency) and JankyBorders (if you opted in) stay until you brew uninstall them too — ~/.config/aerospace is only scuttlarr’s if its first line says so.