Palettes

The palettes of pal's own extensions. Each is an extension with a pal.json manifest, in zcag/pal-extensions (the games in zcag/pal-games); a path below such as calc/index.ts or test/calc.test.ts is in that repo; its settings go under [extensions.<name>] in the config file unless noted, and the per-palette keys (enabled, alias, hotkey, icon) go under [palettes.<id>]. See Config.

Three words used below. An input palette is never in the index: its rows come from the extension on every keystroke inside it, and the root only has the palette's own row. A live palette is listed again every time the panel shows (not twice within 2 s, and with a ttl only once its last listing is older than that), so its rows are current at the root. A palette that is neither is indexed: listed once, searched from the index, refreshed with ⌘R; a scripts palette keeps its listing across restarts for the extension's ttl (an hour by default) unless it sets its own.

At the root every palette also has a tier (Extensions): primary for what is reached by name (Applications, Windows, Menu Bar Items, Bookmarks, Quicklinks, Snippets, Recent Files, Browser Tabs, System, SSH Hosts), ranked up and capped at 8 rows per palette; catalog for the big static lists (Emoji, Unicode Characters, Colors, both Icons palettes, a data file of 100 rows or more), ranked down and capped at 3, the rest behind a "12 more in Emoji" row; normal for everything else, capped at 6. [palettes.<id>] tier overrides it.

Every palette that ships, by extension. The id is the config key ([palettes.<id>]) and the heading of its section; a multi extension's second account gets the same palettes under <name>@<suffix>-<palette> (Config).

Applications (apps)

Installed applications with their own icons.

• macOS: .app bundles in /Applications, /System/Applications and ~/Applications, one level deep so the Utilities folders come along. A row from ~/Applications or an extra folder has the folder as its subtitle; the two usual roots say nothing. The details (⌘I) lead with the folder over the name, running and the version as chips. The bundle id is a keyword, so com.apple. or anthropic finds the app. Enter opens the bundle path with the system opener.
• Linux: .desktop entries from every XDG data dir (~/.local/share, $XDG_DATA_DIRS, the flatpak exports), first directory wins per desktop id. Entries with NoDisplay, Hidden, a TryExec that is not installed, or an OnlyShowIn/NotShowIn that excludes $XDG_CURRENT_DESKTOP are skipped. Comment (else GenericName) is the subtitle; GenericName, Keywords, the binary and the desktop id are keywords. Enter launches through gio launch, else gtk-launch, else the parsed Exec. Terminal=true entries run in $TERMINAL, else the first of kitty, foot, xterm found on PATH.

Running apps, System Settings panes and actions

• A running app carries a green running tag (as of the last listing: the palette is indexed, so the tag is refreshed by ⌘R, a settings change, and after a Quit or Hide from the panel) and its actions are Open, Quit (⌘Q), Hide (⌘H), Reveal in Finder (⌘⇧R), Copy path (⌘C), Copy bundle id (⌘⇧C); an app that is not running has Quit and Hide last, and both answer "is not running" as a toast rather than launching it. Quit asks the app through AppleScript (so it can ask you to save; a save dialog left up is the app's to finish) and falls back to SIGTERM for a bundle Launch Services does not know. Hide goes through System Events (an Automation prompt for pal once).
• Keywords: the bundle id as before, plus CFBundleDisplayName and CFBundleName when they differ from the folder name (Chrome finds Google Chrome). Localised names (InfoPlist.strings) are not read: they are binary plists in most system apps and would cost a spawn per app.
• System Settings panes are rows: 35 common panes (Keyboard, Displays, Privacy & Security, Wi-Fi, ...) with the System Settings icon, System Settings as subtitle, settings/preferences and a few words per pane as keywords. Enter opens the pane (x-apple.systempreferences:<id>), ⌘C copies that url. A curated table (macOS 13+ ids), not a scan of /System/Library/ExtensionKit: the extensions there mix panes with intents and widgets and carry no display names.
• Linux: a .desktop file's [Desktop Action …] groups ("New Window", "New Private Window") are the row's secondary actions, run from their own Exec (there is no launcher CLI for an action); Copy path too. The parser is apps/desktop.ts.

Settings, [extensions.apps]:

Blackjack (blackjack)

A hand of blackjack on a felt table. Enter on the palette's row (or its hotkey) opens the table as a view level: a surface, the extension's own page, with the Kenney deck dealt from a shoe in the corner. The title line shows the phase ("Place your bet", "Your turn", "Dealer busts"), the footer the primary move, and ⌘K lists every legal move with its key.

• Betting: ↑ / + and ↓ / - move the bet by the minimum (or click the chips), Enter deals: player, dealer, player, then the hole card face down.
• Playing: ↑ or H hit, ↓ or S stand, → or D double down (first two cards, one card then stand), ← or P split (a pair, once; split aces take one card each; the hands slide apart). Enter stands too. Totals show on a badge over each hand ("Soft 17"); on stand the hole card turns over and the dealer draws to 17.
• Settled: the result and the net for the hand; a win glows, a bust shakes, a blackjack gets its own flourish, and the chips go to the dealer or come back with the winnings. Enter for the next hand. N starts a new game (asks first) with a fresh bankroll and record.
• Every move is a button on the rail under the felt too, with its keys on it; the arrows and Enter play a whole hand one-handed.
• Escape leaves at any point; the hand, the bankroll and the record persist (in the extension's storage), so the table is as you left it next time.

Rules: dealer stands on 17 (soft 17 too unless dealer_hits_soft_17), blackjack pays 3:2, a dealer blackjack is checked at once, doubling after a split is allowed, no surrender. The shoe is decks decks and is reshuffled before a deal once under a quarter of it is left (the bar on the shoe). Insurance is offered on an ace only with insurance = true (↑ or i takes it; ↓ or Enter declines), costs half the bet and pays 2:1.

The page plays with the extension's own rules (game.ts, the file the host tests), so the table and the tests cannot disagree; the surface node it rides on is in Extensions.

[extensions.blackjack]
decks = 6                     # 1..8
starting_bankroll = 1000
min_bet = 10                  # also the step for + and -
dealer_hits_soft_17 = false
insurance = false

Bookmarks (bookmarks, bookmarks-history)

Hand-picked links from a JSON file: a JSON array of objects with name and url, plus optional subtitle (the address when absent), icon (a glyph, emoji or hex colour; a row with a url and no icon gets the site's favicon) and keywords (a list of strings); the previous pal's bookmarks file reads as is.

[
  { "name": "Home Assistant", "url": "http://ha.lan", "keywords": ["ha", "home"] },
  { "name": "GitHub", "url": "https://github.com", "icon": "🐙" }
]

Actions:

Browser bookmarks

The browsers' bookmarks join the JSON file: Chrome, Brave, Edge, Chromium, Vivaldi and Arc (every profile's Bookmarks JSON, the profile name from Local State when there is more than one), Safari (~/Library/Safari/Bookmarks.plist, read through plutil -convert xml1 since the JSON form refuses the Reading List's dates; the Reading List itself is left out) and Firefox (every profile's places.sqlite, copied first because the running browser holds it locked, then bun:sqlite; tags and place: queries left out). Every source is read on every list.

• The file's rows come first, then each browser in the browsers setting's order; a url two sources have is listed once, the first wins. Browser rows sit in a section per browser and profile (Chrome, Chrome (Work), Safari, Firefox), carry the folder path as an accessory (Bookmarks Bar / Dev) and as keywords, and get the site's favicon. A bookmark saved without a name (Chrome's bar keeps those) is named by its bare address (calendar.google.com) and says nothing twice under it.
• Actions: Open in browser (Enter), Copy link (⌘C), Copy as markdown (⌘⇧C, [name](url)), and on a browser row Open in Chrome/Safari/... (open -a on macOS, the browser's binary on Linux).
• Safari's file needs Full Disk Access: without it the Safari section is one inert row saying so (System Settings > Privacy & Security > Full Disk Access, add pal).

Settings, [extensions.bookmarks], in addition to file:

Settings, [extensions.bookmarks]:

Browser History (bookmarks-history)

A second palette of the extension, input rather than indexed: every keystroke searches the visit history the same browsers keep (the browsers setting; Safari's History.db is behind Full Disk Access and is not read), by title and address, newest first, fifty rows at most, a url once. Chrome, Brave, Edge, Chromium, Vivaldi and Arc are every profile's History (SQLite, the urls table; Chrome's clock counts microseconds from 1601), Firefox every profile's places.sqlite (moz_places, microseconds from 1970). A running browser holds its file locked, so each is copied under pal's cache (~/Library/Caches/pal/bookmarks, ~/.cache/pal/bookmarks on Linux) before it is read; the copy is taken again when the file's mtime moved, at most every 30 seconds, so a keystroke never copies a large history twice. Hidden entries (a redirect Chrome keeps for autocomplete) and pages never visited are left out; no browser with a history is one inert row saying which are read.

• The row: the page's title (the address when it has none), the address under it and as the favicon's source, when it was last visited on the right, the browser and profile as the section (Chrome (Work)).
• Actions: Open in Chrome/Firefox/... (Enter, the browser it came from: open -a on macOS, the browser's binary on Linux), Copy link (⌘C), Open in default browser (⌘O).

Calculator (calc)

An input palette: what you type is answered on every keystroke. Three parsers take the query in turn: dates and time zones, currencies, then mathjs for arithmetic and units. The result is the row's title, the query as it was understood is the subtitle (12 USD to TRY), and a second row carries another form when there is one: the other bases of an integer, a fraction, the reverse conversion, the ISO date. A query that does not parse lists nothing, so nothing flashes while typing; with nothing typed the palette shows three hint rows.

Actions on every result row: Enter copies the result as shown, ⌘Enter pastes it into the app in front, ⌘⇧C copies it without grouping or symbols (583.68, 1000000), ⌘⇧E copies expression = result.

What works (every line below is checked by test/calc.test.ts in pal-extensions):

Details:

• Currencies are the 30 the ECB fixes (USD, EUR, GBP, TRY, JPY, CHF, ...); no crypto, the source has none. Symbols ($ € £ ₺ ¥ ₹ ₩ ₪ zł, HK$, R$, ...), names (dollars, lira, euro, quid, yen, TL) and ISO codes in any case are understood; to, in, as and → join the two sides; 1k, 2.5m are thousands and millions; the amount may be an expression. A bare usd is the rate (1 USD to TRY). Results use the currency's own decimals (JPY none); the accessories carry the rate and rates <date>, the detail pane the rate, its inverse, both names, the date and the source. A target still being typed (12 usd to tr) answers for the source alone meanwhile; an unknown target lists nothing, a currency the set lacks is an inert No rate for X row.
• Rates come from the ECB reference rates through https://api.frankfurter.dev/v1/latest (no key, one fix per working day), fetched on the first currency query, never before. The first query without a cache shows an inert Fetching exchange rates… row, and the next keystroke has the numbers. The set is kept in the extension's storage with its date and fetch time, and refreshed in the background once it is a day old; meanwhile, and whenever the network is away, the cached set answers with its date on the row. A failed fetch is retried after a minute. PAL_CALC_OFFLINE=1 in the host's environment disables fetching (the tests), PAL_CALC_RATES_URL points it elsewhere.
• Units are mathjs's, plus the spellings people type: gb/mb/kb (bytes; mathjs's own kb is a kilobit), kph/kmh/mph, kw/kwh, mo/yr/hr/wk, ha, sqm, tsp/tbsp, lbs, and f/c/k as degrees on either side of a to. 5 ft 3 in and 5'3" add up. Unit and rate results show at most 6 significant digits whatever precision says.
• Precision is significant digits for a number below 1 and for the fraction of one above; integers are never rounded (123456789*1000 is exact). Numbers past 1e15 or under 1e-6 go exponential.
• Locale sets grouping and the decimal separator both ways: under tr (or de), 1,5 + 2 is 3,5 and 1.000.000 / 3 is 333.333,3333; under en a 1,000 is a thousand. Dates and relative phrases follow it too.
• Dates are ISO (2026-12-25, with an optional 12:00), 25 dec, dec 25, 2026, 25.12.2026, 25 aralık (Turkish month names, with or without their letters), the words now, today, tomorrow, yesterday, a weekday in English or Turkish (friday, cuma) with an optional next/last/this (gelecek/geçen/bu), and next week, last month. Times are 24 h whatever the locale. The clock is the SDK's (PAL_NOW pins it in the tests). Arithmetic takes days, weeks, months, years, hours, minutes (and d, w, mo, y, h, min), chained (today + 1 month - 2 days); months keep the day of month, clamped. Day counts are calendar days (DST-proof); A - B is A minus B, A to B reads left to right. A date-shaped query that is no date (2026-02-30) lists nothing rather than falling through to arithmetic.
• Zones are IANA ids in any case, utc+3-style whole-hour offsets, the common abbreviations (utc, cet, est, pst, jst, aest, ...) and 120-odd city and country names (tokyo, new york, sf, ldn, india, hong kong). ist is Istanbul here (the airport code), India is india, delhi, mumbai; any IANA id's city also works (caracas, ho chi minh), and a few Turkish names (londra, moskova). Without a source zone the local one (the system's) is meant; the time is today's in the source zone. 3pm in tokyo is your 3pm in Tokyo, 3pm tokyo Tokyo's 3pm here. All from the runtime's time zone data, no network.
• Unix time: a bare 10-digit number starting with 1 (2001 to 2033; 13 digits for milliseconds) is a unix time, so 1759000000 at the root answers with its date; @ reads any. Other numbers stay numbers (5321234567).
• Durations add and subtract d, h, m, s (and their spelled forms), compound or not (3h20m). m means minutes only beside an hour, so 45m + 10m is still metres.

What does not:

• Crypto (1 btc to usd): frankfurter carries no crypto; it lists nothing.
• Currencies outside the ECB set (12 usd to aed): nothing, or a No rate row once the set is loaded.
• A trailing operator or an open parenthesis (1 +, (1+2): nothing until the expression closes. A trailing = is fine.
• Variables do not persist between keystrokes: x = 5 shows 5, but a later x is undefined.
• 10x3 without spaces (0x would be hex); write 10 x 3 or 10*3.
• Half-hour offsets as utc+5:30; use the zone (india).
• Public holidays: workdays counts Monday to Friday only.

At the root, a query that reads as sums, a conversion, a date or a time (2+2, 15% of 80, 12 usd to try, 5 km to miles, 3 days from now, today + 3 days, next friday, time in tokyo, tokyo time, what week is it, unix time, 1759000000) is answered inline under a Calculator section above the hits, with the same actions (Enter copies the result). A bare number or a single word never wakes it (mon is on the way to Monitor, friday answers only inside the palette), and a phrase without a digit or a date word answers only when the date parser reads it whole, so time machine and screen time stay app searches. The check costs about 5 µs a keystroke. A query nothing matched gets an "Ask Calculator" fallback row that opens the palette with it typed.

Settings, [extensions.calc]:

Clipboard History (clipboard-history)

What you copied, searchable, with images. Text, images and file lists are recorded by a watcher that runs while pal runs; the search is SQLite full-text search over the text, ordered pinned first, then newest. The palette opens with the detail pane showing: the source app over the entry's name, the kind and pinned as chips, its numbers large (characters and lines, pixels and size, a file count), then the full text (fenced), the image or the file list, and when it was copied. A row that is a single url gets the site's favicon; the source app and the time are accessories, and a pinned entry sits under Pinned. An entry you have named (⌘⇧R) is titled by its name from then on, with the text's preview as its subtitle, and a search finds it by the name as well as by the text (the name is matched as a substring, the text by prefix words).

Actions:

primary_action = "copy" swaps the first two, so Enter copies and ⌘Enter pastes. Marked rows (⇧↓, ⌘-click): Copy puts their texts on the clipboard joined one per line (a file list its paths, an image its title) as one copy, Delete removes each.

Paste needs the Accessibility permission on macOS: the paste is a synthesised Cmd+V, which the system only delivers from a process on the Accessibility list. Without it pal shows the system prompt once per run and a toast, "Paste needs Accessibility. Grant pal in System Settings > Privacy & Security > Accessibility", instead of half-doing it. On Linux the paste is Ctrl+V through wtype, else ydotool (which needs ydotoold running); with neither, paste fails and the toast says so.

What is never recorded: anything a password manager marks as concealed or transient (the org.nspasteboard convention on macOS, the x-kde-passwordManagerHint type on Linux, read through wl-paste or xclip), pal's own concealed copies (a 1Password password, a verification code: marked the same way, and their clear-after restore), copies over 10 MB, and copies made while an app in the feature's exclude_apps is in front. Copying something already in history bumps it to the top instead of adding a duplicate.

Retention runs after every copy: unpinned entries older than max_age_days are deleted, then the unpinned tail past max_entries. Pinned entries never expire. A search lists at most 200 rows of what is left, newest first after the pinned ones; type more to narrow it.

Link: pal://clipboard/copy?index=0 puts a history entry back on the clipboard, 0 (the default) the newest (Links).

Pinned, filters and more actions

• Pinned entries sit in a Pinned section at the top; the rest follow without a header.
• A filter dropdown (Tab) by kind: All, Text, Images, Files (the core's kinds), Links (text that is one url) and Colors (text that is one #hex or rgb()/rgba() colour).
• A colour entry's icon is the colour itself (a tinted dot); an image row shows its size next to its dimensions.
• More actions: Open link (⌘O) on a url, Paste as plain text (⌘⇧V) on text (the entry's text pasted as text), Copy image file (⌘⇧C) on an image (the PNG the core keeps, as a file), Delete all unpinned (asks first; every unpinned entry deleted one by one, since the core's only bulk operation is Clear).
• The detail pane's header carries the entry's name when it has one. Names live in the history database next to the entry (name column, added on the first open of an older database), so they survive a restart and go with the entry when it is deleted.

Settings, [extensions.clipboard]:

What is recorded and for how long (exclude_apps, max_entries, max_age_days) is the Clipboard history feature's, [features.clipboard] (Features).

Clipboard (clipboard-rows)

What is on the clipboard right now, read as the things it could be: the Clipboard section of the empty root (before you type), and the same rows as a palette of their own. The rows are built from the history entry for the current clipboard, so what history never recorded (a concealed copy from a password manager, one made while an excluded app was in front, one over the size cap) never shows here either, and nothing leaves the machine except the page-title fetch below.

Each row's Enter is the one thing it is for; ⌘K has the rest, and every row ends in Hide from the root (⌘⇧H), which keeps the section away until the next copy:

A text is read as everything it is at once: 1700000000 is a number and a timestamp, a path is a path and a text. Text over 64 KB keeps its counts only. Every row has a detail pane (⌘I): the QR code large, the swatch wide, the JSON pretty-printed, the file list, the image itself.

Settings, [palettes.clipboard-rows.settings]:

Emoji (emoji)

A grid of every emoji in the bundled list, searched by name and keyword. The tile is the glyph; the name is the shortcode with spaces. A catalog at the root: 1906 rows, so a typed query shows at most three of them there and the rest behind the "more" row, ranked under the primary and normal rows that have the word.

Actions:

Settings, per palette, [palettes.emoji.settings]:

Sections, skin tone and shortcodes

• Sections: Recently used first (the last 24 you copied or pasted, kept in the extension's storage), then Unicode's groups in order (Smileys & Emotion, People & Body, ..., Flags). data.json now carries category and skin per emoji (from unicode-emoji-json; the names and keywords are emojilib's as before).
• The palette is live with a 30 s ttl: the order is the sections' own, never frecency's, and a show more than 30 s after the last listing lists again so the recents follow what you used.
• Search by shortcode: :thumbs_up: is a keyword next to thumbs_up.
• Actions: Copy emoji (Enter), Paste emoji (⌘Enter), Copy shortcode (⌘⇧C); paste_by_default swaps the first two.
• Skin tone: skin_tone (none by default) is applied to the emoji that take one (329 of them: hands, people) in the tile, on copy and on paste. The modifier goes after the first code point, which tones a single person and the first person of a family or profession sequence; a two-person sequence gets one tone, on its first person.
• Your words: the keywords setting adds search words per emoji (rocket: ship deploy), so a team's own names find them.

Settings, [extensions.emoji]:

Processes (processes)

What is running, from ps, listed again on every keystroke because the set changes constantly (an input palette; the root only has its own row). The query matches the name or a pid prefix. The row is the executable's name, its pid the subtitle with the full path after it on macOS (outside an app); the resident memory sits on the right, and a process above 10% CPU carries a NN% cpu tag (orange, red from 50%). Rows are sorted by CPU, then memory. On macOS a process that lives in a .app bundle gets that app's icon.

The filter dropdown scopes the list:

Actions:

A kill that fails (a process of another user, a pid that is gone) keeps the panel open with a toast carrying the OS's message.

Ports and Activity Monitor

• Kill by port: a query of : and digits lists what listens on TCP ports instead of processes: :3000 that port, :30 every port starting with 30, : alone every listener. One row per process and port with the port as a blue tag and the address as subtitle; a process ps knows gets its usual numbers and icon. ss -ltnp on Linux, else lsof -iTCP -sTCP:LISTEN (macOS ships it). Rows have the same kill and copy actions; a row's id is pid:port.
• Open in Activity Monitor (⌘O, macOS): brings Activity Monitor up and types the pid into its search field (⌘F, then the digits, through System Events; needs Accessibility, else the app just comes up).

Settings, [extensions.processes]:

Quicklinks (quicklinks)

Your own links, kept in the extension's storage and edited in the panel. At the root a typed web address (docs.rs/serde, https://…) gets one inline Open row under a Quicklinks section (https:// is assumed when there is no scheme), and a query nothing matched gets every link with a {query} in it filled with the query as a fallback row. Enter on a link opens it. A link whose url has a {query} placeholder (https://github.com/search?q={query}; Raycast's {argument} and {argument name="Repo"} are read the same way) drills in instead: the input fills the placeholder as you type, percent-encoded, and Enter opens the filled url (⌘C copies it). {selection} and {clipboard} in a url are filled without asking (the SDK's placeholders, Snippets below has the grammar; each value percent-encoded), so https://translate.google.com/?text={selection} opens in one Enter. The row shows the placeholder as a tag, the browser it opens with when one is named, and the url (without https://) as its subtitle; the icon is the site's favicon.

The root row Create Quicklink opens a form (name, url, keywords, and Open with: the default browser or one of the browsers installed: Safari, Chrome, Firefox, Arc, Brave, Edge, Chromium, Vivaldi, Zen; open -a on macOS, the command on Linux; a mailto: or an app's scheme goes to the system opener whatever the field says). The url and the name come filled from the tab in front when Browser Tabs can name one within 400 ms (a DevTools port, a scriptable browser); an extension can push the palette with args: { create: { name, url, keywords } } and the form comes filled with that. Edit (⌘E) opens the same form filled in, and a url the opener could not take (no scheme, not a path) is refused with the message under the field. Delete (⌃X) asks first. Keywords are extra words the search matches, space or comma separated.

Browse Library (the row after Create) is a level of 25 ready-made searches (Google, DuckDuckGo, Bing, Wikipedia, YouTube, GitHub, GitHub code, npm, crates.io, PyPI, MDN, Stack Overflow, Amazon, Google Maps, Google Translate, X, Reddit, Hacker News, IMDb, Spotify, Unsplash, Can I use, Rust docs, Homebrew, Apple Developer): Enter adds one to your links (once; the ones you have are tagged added), ⌘Enter searches with it without adding (the same drill-in), ⌘C copies its url.

Link: pal://quicklinks/open?name=<name> opens a quicklink by name or keyword; a {query} link opens the panel to fill it, or &query=<text> fills it from the link (Links).

Import and export

• Import Quicklinks / Export Quicklinks and Import Snippets / Export Snippets are rows after the list: each opens a form with one path field (~ expanded; export defaults to ~/Downloads/pal-quicklinks.json and ~/Downloads/pal-snippets.json). Export writes your own rows as a JSON array ({name, url, keywords?}, {name, text, keyword?}; no ids), replacing the file. Import reads such a file (Raycast's {name, link} quicklink export is read too), skips what you already have (a quicklink by url, a snippet by name and text), and says how many came in. A path that cannot be read or written is refused with the message under the field.

Settings, [extensions.quicklinks]:

The links themselves live in <data dir>/pal/storage/quicklinks.json (see Storage in Extensions), shared by every config profile.

Snippets (snippets)

Short texts by name and keyword, kept in the extension's storage and edited in the panel. Enter pastes the text into the app that was in front (needs Accessibility on macOS, like Clipboard History), ⌘C copies it instead. The keyword is a row keyword, so typing sig finds the signature; it shows as a tag, the first line of the text is the subtitle, and the whole text is in the detail pane (⌘I).

Placeholders in the text are filled in when it is pasted or copied:

{date}, {time} and {datetime} take two attributes. format= writes the moment with the tokens YYYY YY MM DD HH mm ss ddd (Wed) MMM (Sep), anything else in the format as it is: {date format=DD.MM.YYYY}, {time format=HH:mm:ss}, quotes around a format with spaces ({date format="ddd D MMM"}). offset= moves the moment first by a signed count of days, weeks, hours or minutes: {date offset=+1d}, {date offset=-2w}, {time offset=+3h}, {datetime offset=-90m format=HH:mm}.

Anything else in braces is left as it is, so a snippet of code keeps its braces. A snippet with placeholders carries a "dynamic" accessory. The grammar is the SDK's (expand in @zcag/pal, Extensions), the same one quicklinks fill a url with and Obsidian an appended line. An expansion by keyword (below) fills the plain forms only: format=, offset= and {snippet} are left as written there.

The root row Create snippet opens a form (name, keyword, text); Edit (⌘E) opens it filled in; a keyword with a space in it is refused (one word, so typing it finds the row whole). Delete (⌃X) asks first.

Link: pal://snippets/paste?name=sig pastes the snippet by name or keyword with the placeholders filled; &copy=1 copies it instead (Links).

The snippets live in <data dir>/pal/storage/snippets.json, shared by every config profile.

Expansion: the keyword typed in any app

On macOS a snippet's keyword typed in any other app can be replaced by its text in place: that is the Text expansion feature's, which keeps the snippets this palette edits (Features). A snippet saved here expands on the next keystroke. Linux has no expansion (no portable keyboard tap); the palette's Enter is the way to paste a snippet there, and pal://snippets/paste?name=sig binds one to a compositor key.

SSH Hosts (ssh)

Every Host in ~/.ssh/config that is a name rather than a pattern (*, ? and ! entries are skipped, a Host a b line gives two rows), in file order. Include lines are followed one level: ~, absolute and globbed operands work, a relative one is under ~/.ssh. A Match block ends the current host. user@HostName is the subtitle (both keywords, so the real name finds the alias), Port a tag.

With include_known_hosts on, the names in ~/.ssh/known_hosts (next to the config) come after, in a second section: [host]:port unwrapped, comma lists split, hashed lines, bare IPs and hosts already in the config skipped.

Actions:

Which terminal Connect opens:

• macOS: the terminal setting. auto takes the first installed of kitty, Ghostty, Alacritty, iTerm2, Terminal (Terminal is always there, so it is the fallback). kitty gets kitty -1 ssh host (a new OS window in the running instance when that was started single-instance), Ghostty and Alacritty open -na <app> --args -e ssh host, Terminal and iTerm2 an AppleScript that opens a window running the command. A terminal that is picked but not installed keeps the panel open with a toast.
• Linux: $TERMINAL, else the first of kitty, foot, alacritty, xterm on PATH; kitty and foot take the command as arguments, the others after -e. Same rule as the Applications palette's terminal entries.

Sections, ProxyJump and Ping

• The section is the file a host came from, relative to the config's directory (.ssh/config, .ssh/conf.d/work.conf); known hosts stay a last Known hosts section.
• ProxyJump is read: the row carries a via <jump> tag and the jump as a keyword, and Copy ssh -J command (⌘⇧J) copies ssh -J <jump> <host> (the plain command already goes through the config's ProxyJump; the -J form is for a machine without it).
• Ping (⌘P): one echo to the HostName (else the name), the round trip as a toast (marko.lan: 3 ms), or why it did not answer.

Settings, [extensions.ssh]:

Files (files, files-browse, files-selection, files-recent)

An input palette over the operating system's own file index: what you type is a name search on every keystroke, never a walk pal indexes itself. A typed path (~/Down, /usr/local/bin) completes instead of searching: the file itself when it exists, else the entries of its folder that start with the last segment (hidden ones only when the segment starts with a dot or show_hidden is on); at the root the same rows show inline under a Files section. A path ending in / (~/, /usr/local/) lists that folder whole, as browsing does. A root query nothing matched gets a "Search Files for “…”" fallback row that opens the palette with it typed. The row is the file name; the parent folder is the subtitle (home shortened to ~); the size and the modification date are accessories. .app bundles get their own icon, everything else a glyph by kind (folder, image, document, code, archive). Exact and prefix name matches come first, the rest in the backend's order, at most limit rows. With nothing typed the palette shows one hint row naming the backend and the folders it searches.

The backend is picked once when the extension loads:

Every search is one process: killed after 3 s, killed as soon as limit paths have been read, and killed when the next keystroke starts a new one. The exclude folders are pruned from the walk (fd, find) or dropped from the answer (Spotlight, locate); fd also stops eight levels down, since with fewer than limit matches it would otherwise walk the whole home. The backend picked is logged once at load ([files] backend: fd).

Contents are searched too. A plain query lists the name matches, then a second section, "In files", of files whose text contains the query, each row's subtitle the first matching line (12: the line collapsed to one line, then the folder). A query starting with ' or content: ('invoice total, Alfred's in prefix) searches contents only. The content backend, picked once at load and logged ([files] content: mdfind): Spotlight's text index on macOS (mdfind -onlyin <folder>... 'kMDItemTextContent == "*<query>*"cd', so PDFs and documents count, and only what Spotlight has indexed), rg --files-with-matches on Linux when ripgrep is installed, else grep -rlI. One process per keystroke, killed after 1 s: what it printed by then is the answer. The snippet is rg -n -m1 (or grep -n -m 1) per file, eight at a time; a file the tool cannot read as text (a PDF Spotlight matched) keeps the folder as its subtitle. A file both searches find is listed once, as the name match. The name matches show as soon as they are ranked; the "In files" rows join below them as each batch of snippets comes in. content_search = false keeps the second section off; the prefix still works.

The detail pane (lazy, asked when the cursor rests on a row) leads with the folder over the name, the kind and Finder's tags as chips, and the size and an image's pixels large, then when it changed. The tags and pixels are what Spotlight knows of the file on macOS (one mdls call, only when the pane asks; the colour index is dropped). On Linux a PNG's size comes off its header. For a text file under 64 KB the first 40 lines follow in a code block. No image preview: the app's icon:// scheme serves app icons, favicons and clipboard images only.

Actions:

Marked rows (Tab here, x while nothing is typed, ⇧↓, ⌘-click): Open, Reveal, Quick Look (one panel, arrows between them), Copy path (the paths one per line), Copy file, Compress (one archive) and Move to Trash run over all of them as one pick; Open with…, the terminal and the three forms stay one file's.

Browsing folders

Enter (or →) on any folder row, in a search, the recents, a completion or the root's inline Files section, pushes the Browse Folder palette (browse) with that folder: a level whose crumb is the folder's path (~/proj), led by a .. row and followed by the entries under the dropdown's sort. Enter, ← or Backspace on the .. row goes up, and ← or Backspace from any row does too while nothing is typed (LaunchBar's and Alfred's convention); → on a folder goes in. There is no .. row at /. Typing filters the listing by name (a case-insensitive substring); Tab cycles the sort:

Hidden entries (a leading dot) show only with show_hidden, which ⌘. flips from any row (it writes the setting, so every listing follows; the action's title says which way). A picture draws its own thumbnail in place of the kind glyph (icon://localhost/file, the app's scheme). A folder over 500 entries shows that many and a last, inert row counting the rest; typing narrows past the cap. File rows carry the same actions as search rows (⌘I for the pane; Tab, x, ⇧↓ mark rows as in Files), the .. row's pane describes the folder it leads to, and Open with… from a browsed row pushes the apps level on this palette. Inside Files, a typed path ending in / that names a folder lists it the same way (the .. row, every entry sorted by name, the cap), so ~/ is a way in without a search; a path without the slash still completes the last segment. Opened by name from the root (its own row, "Browse Folder") it lists the home folder.

Open with… drills into a level of the applications the OS registers for the file, each with its own icon: the default (what Enter would use) first with a default tag, the rest by name; typing narrows them by name or bundle id, and Enter opens the file with that app (open -a on macOS, gio launch on Linux) and hides the panel. On macOS the list is Launch Services' (NSWorkspace, every role); on Linux the file's MIME type (xdg-mime query filetype, else file) is looked up in the mimeapps.list files and every data dir's mimeinfo.cache, the default from xdg-mime query default, and a text/* file also gets the text/plain editors. A file nothing is registered for shows one hint row.

Copy file writes file URLs on macOS and text/uri-list on Linux (X11, or Wayland with the wlr data-control protocol; a compositor without it gets a toast saying so). The clipboard history records it as a files entry like any copy.

The Finder selection

Open pal over a Finder window (or the Desktop) with files marked and the empty root leads with a Selected in Finder section, nothing typed: each marked item as a file row with every action above, pictures with their thumbnails; with two or more, an N items row first (the names, the total size) whose actions run on all of them at once: Open all, Reveal all, Quick Look all, Copy paths, Copy files, Compress together, Move all to Trash (asks first), and whose Enter opens the palette with the whole selection. The root shows four item rows at most.

Finder Selection (files-selection) is the same as a palette of its own, for a hotkey or pal open files/selection: the N items row, then every marked item, typing filters them by name, marks and the multi actions work as anywhere. With nothing to list it says why: "Nothing is selected in Finder" with Finder in front, "Finder is not in front" otherwise (the front_app state), "Not available on Linux" there, since no file manager exposes its selection.

The selection is the core's selection.files() (Finder's selection over osascript, only while Finder is the app in front; ~190 ms, read once per panel show and cached), so it is what was marked when the panel came up: a folder shown with nothing marked is nothing, not the folder, and a selected dot file is listed whatever show_hidden says. The Images palette reads the same selection for its inputs, and {files} in a snippet or a quicklink fills in the paths.

Recent files and Quick Look

• Before you type, the Files palette lists the recently used files (a Recently used section) instead of the hints: on macOS Spotlight's kMDItemLastUsedDate over the last seven days within the configured folders (mdfind -attr, so the rows sort newest first), on Linux GTK's ~/.local/share/recently-used.xbel. Folders, hidden and excluded paths and files that are gone are left out; the date on the right is when the file was last used.
• Recent Files (files-recent) lists the same rows as a palette of its own: live (newest first is the order), listed again on a show once the listing is a minute old, with the same actions and detail pane.
• Quick Look (⌘Y) on macOS opens the file in qlmanage -p (every marked row in one panel). The System palette's "Quick Look Finder Selection" row does the same for what is marked in Finder without listing it first.

Settings, [extensions.files]:

The rename, move and copy forms and the archive command are the SDK's files (sdk/src/files.ts); Downloads uses them too, so the two palettes rename and move the same way.

System (system)

Sleep, lock, log out, restart, shut down, empty the trash, dark mode, volume, brightness, do not disturb, eject, show desktop, keep awake (for a while, until a time, or while an app runs, with a countdown on the bar), quit or unhide every app, dismiss notifications. The rows are indexed, so mute or sleep at the root finds them (each carries keywords: suspend, power off, bin); live because the Keep Awake row reads Allow Sleep with the time left while a run is on, and a live palette lists again on every show. pal hides the panel before running a command, so it lands on the desktop, not on pal.

Only commands this machine can run are listed:

Log Out, Restart, Shut Down, Empty Trash and Quit All Apps are destructive: with confirm_destructive on, Enter asks "(command) now?" first. A command that fails keeps the panel open with a toast carrying the tool's message.

Link: pal://system/run?id=<command> runs one by its id (sleep, lock, logout, restart, shutdown, empty-trash, dark-mode, volume-up, volume-down, volume-mute, brightness-up, brightness-down, dnd, eject-all, show-desktop, keep-awake (the toggle), quit-all, unhide-all, dismiss-notifications, and on macOS quick-look-selection, the one for a Quick Look hotkey: the HUD says "nothing is selected in Finder" when there is nothing to show); the route is declared with confirm, so a link always asks first (Links). pal://system/awake?for=1h&display=1 is Keep Awake's own (below).

Keep Awake

The row takes how long in the bar (Item.args): 45m, 2h, 1h30m, a bare number of minutes, a clock time (14:30, 2pm, until 14:30; tomorrow's when today's has passed), or forever; blank runs awake_default (an hour). A second field says whether the display stays up too (awake_display preselected). Enter starts it, the panel hides and the HUD says what it did (Awake for 45 min, Awake until 14:30, Awake until turned off); cmd+enter keeps awake until turned off; cmd+u opens a form with the same spelling, the display switch and an app to follow (one with a window open: the run ends when it quits, caffeinate -w). While a run is on the row reads Allow Sleep with the time left as a tag: Enter ends it (Sleep allowed), Keep awake for… takes the bar's fields for a new span, cmd+d flips the display; the row sits in the empty root's Now section meanwhile. A spelling that is neither a duration nor a time is a failure toast (under the field, in the form).

caffeinate does the timing itself (-t <secs>), so a run ends on time whether or not pal is up. pal keeps one record of the run (pid, until, display, app) in its storage and checks it against the live process on every read (the pid alive, its command line caffeinate's, the deadline not passed); the child is not killed with the host, so a restarted pal finds the same run back, and a record whose process is gone (or is something else after a reboot) is dropped silently. A run that ends while pal watches says so in the HUD (Keep awake ended, sleep allowed).

Bar item system/awake: a coffee glyph and the countdown (2h 40m, 12m, 45s; ∞ without an end), a monitor mark after it when the display is kept awake too, amber in the last five minutes (the ending rule, over system.awake_left); hidden while off, and [bar.items."system/awake"] show = "always" keeps a muted coffee whose click still opens the popover. The popover: the run on a card (what it is, since when, the time left large, a bar), the presets (the item's presets setting) as tiles on the digits 1..5 (a new end from now, on or off), the display switch on d (a run is restarted with the other flag; off, it is the next run's), u a field for a spelling, Enter allows sleep while on and starts the default while off, backspace allows sleep, o the System palette. The ticks are pal's own: a push when the countdown's text next changes (every minute; every second under one, or while the popover is up). States published: system/awake, system/awake_until (unix ms, null without an end), system/awake_left (minutes, rounded up), system/awake_display.

Link: pal://system/awake?for=1h&display=1 (until=14:30, app=Xcode, off=1; bare toggles: the default duration, or off while on); pal call system/awake for=2h from a shell.

Trash count and dark mode

• Empty Trash shows what is in the Trash on the right (3 items, empty); ~/.Trash itself is readable only with Full Disk Access, and without it the row simply has no count. Linux reads ~/.local/share/Trash/files.
• Toggle Dark Mode carries the current appearance as a tag (dark violet, light amber), from defaults read -g AppleInterfaceStyle on macOS and GNOME's color-scheme on Linux.

Settings, [extensions.system]:

awake item settings, [bar.items."system/awake".settings]:

Windows (windows, windows-spaces)

Every open window with its app's icon, most recently used first on macOS and Hyprland (front to back on Sway and X11), never ranked by how often it was picked: row 1 is the window you came from, row 2 the one before it. Hyprland keeps that history; on macOS pal does, stamped on every app activation, when the panel shows, and by Focus, so a focus change inside one app shows up on the next activation. A live palette: the list runs on every show, so window titles are root results. The app name is the subtitle; the bundle id or window class is a keyword; a hidden app's window carries a hidden tag, a minimised one minimized, one on another workspace or space space <n> or other space, and the monitor when known.

Actions:

Marked rows (Tab here, x while nothing is typed, ⇧↓, ⌘-click): Close and Minimize run over all of them; Focus is one window.

• macOS: the list comes from CoreGraphics merged with the Accessibility API for the parts CoreGraphics does not give (another app's window title, whether it is minimised). Without the Accessibility permission the list still works (titles only when Screen Recording allows, else the app name), focusing falls back to activating the app, and close and minimise fail with "needs Accessibility permission". Focus shows the same one-time prompt and toast as paste when the permission is missing.
• Linux: the backend is detected, not configured. Hyprland when hyprctl and an instance signature exist (the newest $XDG_RUNTIME_DIR/hypr/* when the variable is missing, so a service-started pal works); Sway on SWAYSOCK; X11 on DISPLAY plus wmctrl. Hyprland has no minimise, so pal parks the window on the special:minimized workspace and Focus brings it back. Sway minimise is move scratchpad; X11 minimise needs xdotool. With none of the three the palette reports "no Hyprland, Sway or X11 (wmctrl) session".

Grouping and app actions

• Rows are grouped by app (a section per app, in the order the front window of each gives); the app name is a keyword as well as the subtitle.
• More actions: Hide app (⌘H, macOS: System Events hides the window's process), Show app in its place on a hidden app's window (⌘⇧H, macOS: the app comes forward with every window it had, and the panel hides), and on an app with more than one window Minimize all of this app (⌘⇧M) and Close all of this app (⌘⇧W, asks first).

Spaces

Spaces (windows-spaces) is the same capability one level up: a row per Space (macOS), workspace (Hyprland, Sway) or desktop (X11) in the order the desktop shows them, the apps on it as the subtitle (most recently used first, each once), the icon of the window used there last (a monitor glyph when nothing is open there), a current tag on the one in front and previous on the one left most recently, and the display when there is more than one. A full-screen app's space (macOS) is a row named by the app. The last row, Previous space, goes back to the one left most recently: a switch by pal or a swipe, pal watches the Space change either way.

Enter brings the space in front: the panel hides first. macOS has no public call to switch Spaces, so pal does what yabai does with SIP on: a synthesised Dock swipe at a velocity no finger reaches, one step per space between along that display's strip, which moves the strip without the slide (instant), and then raises the window used there last (the focus history, else the biggest, never a hidden app's) so the space comes up with it in front. Posting the swipe needs the Accessibility permission like paste (the HUD says so when it is missing). Linux asks the compositor (hyprctl dispatch workspace, swaymsg workspace, wmctrl -s).

Names: spaces = ["web", "term", "misc"] names the desktops by number (the first entry is Desktop 1). A named space's row is titled by it, the Windows rows say space term instead of space 2, and its row id is the name, which is what a global hotkey keys on:

[extensions.windows]
spaces = ["web", "term", "misc"]
back_and_forth = true
toggle = ["web", "term"]

[palettes.windows-spaces.item_hotkeys]
web = "ctrl+1"
term = "ctrl+2"
misc = "ctrl+3"
toggle = "ctrl+f"

An unnamed desktop's id is its number ("4"); last is Previous space. With back_and_forth on (Hyprland's workspace_back_and_forth), a space's key pressed while on that space goes to the previous one, so one key toggles between a space and where you came from; Enter on the current space's row does the same. toggle = ["web", "term"] adds a Toggle row (toggle) that flips between those two: on the first it goes to the second, anywhere else to the first, so toggle = "ctrl+f" in the hotkeys block is a fixed ping-pong between two spaces however you got where you are. pal run windows/spaces/term from a script or a compositor keybind is the same pick.

Settings, [extensions.windows]:

The switcher (Keyboard): the manifest suggests hold = "alt+tab" for this palette, so holding Alt and pressing Tab shows the windows flat with the cursor on row 2, Tab again steps down, Shift+Tab up, and letting go of Alt focuses the row under the cursor; typing filters meanwhile, Escape cancels. [palettes.windows] hold = "" turns it off, another chord moves it; on Linux a compositor keybind runs pal switch instead.

Window Management (window-management, window-management-arrange)

Move and resize windows from the keyboard, Raycast's set: one row per layout (halves, thirds, quarters, the maximize family, larger and smaller, a size typed in, a nudge by a step, the other display, fullscreen, minimize, restore), Enter applies it to the window you were in. pal hides its panel first, so the window with focus is the one behind the panel, not pal; the HUD then names the layout, or says why it did not happen ("Restore: nothing to restore", "Next Display: only one display").

These ids are what item_hotkeys (below) and the pal://window-management/layout?name=<id> route take (Links).

What it does not do

No custom layouts: the thirty-one layouts above plus the Resize to… form are the set; gap, step, cycle and the two percentages are the knobs. Larger and Smaller are a fixed 10%. Resize to… is a form, not a link: pal://window-management/layout takes the layout ids only.

"The screen" is the display the window's centre is on (the one it overlaps most when the centre is off every display), minus the menu bar, Dock, or bars, minus gap on every side; the halves, thirds and quarters are equal cells with gap between them. Restore remembers, per window and in memory until pal quits, the frame a window had before a run of layouts started: a run is any sequence of pal layouts, and moving the window by hand in between starts a new one, so Restore goes back to where you had put it.

With cycle on (a setting, off by default), a half applied to a window already at that half steps to the next size of its family, Rectangle's way: Left Half, then Left Two Thirds, then Left Third, then the half again (the right family likewise; the top and bottom halves have none). The HUD names the size the window landed on, and Restore still goes back to where the run started.

Actions:

Arrange Window (window-management-arrange) is the same thing the other way round: an input palette of the open windows (minimised ones left out); Enter on one lists the layouts with that window's title as the subtitle, and Enter on a layout applies it there.

Per-layout global hotkeys, which move the focused window without showing pal at all, are item_hotkeys under the palette in the config file (see Config); the moves and the resizes are the ones worth a key, since they repeat:

[palettes.window-management.item_hotkeys]
left_half = "ctrl+alt+left"
right_half = "ctrl+alt+right"
maximize = "ctrl+alt+enter"
restore = "ctrl+alt+backspace"
larger = "ctrl+alt+="
smaller = "ctrl+alt+-"
move_left = "ctrl+alt+shift+left"
move_right = "ctrl+alt+shift+right"
move_up = "ctrl+alt+shift+up"
move_down = "ctrl+alt+shift+down"
fullscreen = "ctrl+alt+f"
minimize = "ctrl+alt+m"

Coming from Rectangle, its default keys as one block, with cycle on so a half pressed again steps through the thirds as it does there:

[extensions.window-management]
cycle = true

[palettes.window-management.item_hotkeys]
left_half = "ctrl+alt+left"
right_half = "ctrl+alt+right"
top_half = "ctrl+alt+up"
bottom_half = "ctrl+alt+down"
top_left_quarter = "ctrl+alt+u"
top_right_quarter = "ctrl+alt+i"
bottom_left_quarter = "ctrl+alt+j"
bottom_right_quarter = "ctrl+alt+k"
left_third = "ctrl+alt+d"
center_third = "ctrl+alt+f"
right_third = "ctrl+alt+g"
left_two_thirds = "ctrl+alt+e"
right_two_thirds = "ctrl+alt+t"
maximize = "ctrl+alt+enter"
center = "ctrl+alt+c"
restore = "ctrl+alt+backspace"
larger = "ctrl+alt+="
smaller = "ctrl+alt+-"
next_display = "ctrl+alt+cmd+right"
previous_display = "ctrl+alt+cmd+left"

Toggle Fullscreen, Minimize and Unminimize are window state, not a frame: Restore does not undo them, and Unminimize picks its own window (the one Minimize last put away while it is still minimised, else the frontmost minimised one), so it has no Apply to… and is not offered for a picked window. Larger and Smaller scale each side by 10% about the centre and are then pushed back inside the screen where they fit; the moves stop at the screen's edge; both leave a window larger than the screen where it is.

• macOS: needs the Accessibility permission (the frame is set through the window's AXPosition and AXSize); without it Enter shows the same toast as paste and asks once. The displays are NSScreen's frames with visibleFrame for the usable part, so an auto-hidden menu bar or Dock gives the whole screen. Apps keep their minimum size and may round.
• Linux: Hyprland (movewindowpixel exact / resizewindowpixel exact; a tiled window is floated first, since an exact frame means nothing inside the tiling layout; the display is monitors -j with reserved taken out; Toggle Fullscreen is focuswindow then dispatch fullscreen 0, since that dispatcher takes no window), Sway (floating enable, move absolute position, resize set, fullscreen toggle; the workspace rect is the usable part), or X11 (wmctrl -i -r <id> -e, -b toggle,fullscreen; xrandr --listmonitors for the displays, wmctrl -d's work area for the usable part, xprop -root _NET_ACTIVE_WINDOW for the focused window). Minimize is the Windows palette's (special:minimized, the scratchpad, xdotool), Unminimize its focus. Sway and X11 are written to the tools' documented shapes and unit-tested on fixtures, not run against a live session yet.

Settings, [extensions.window-management]:

Store (store)

Every extension your registries list, in the panel: pal's own registry first, then any added in Settings › Extensions › Registries. An input palette: what you type narrows the list by name, title, tagline, category, keywords and palette titles; the dropdown (Tab) filters to Installed, Updates, Registries, or a shelf (Productivity, Developer, System, Media, Reference, Fun, Integration). Every row is one listed extension with its tile, its tagline as the subtitle, how it stands (update, needs a newer pal, not updated, comes with pal, installed, or why it cannot be installed here), the registry's name when it is not pal's, and the category on the right. What has an update leads the list under an Updates heading. Opened on All with nothing typed, the rest follows as Featured (three worth meeting first that are not installed: Spotify, GitHub, Solitaire, Calendar, Translate, Disk Space, Hue, Typing, in that order) and then a section per category, by title (the section names the category, so the row does not). A search or a filter is one list, the extensions whose title the words start first. The detail pane (⌘I) leads with where it comes from and its category over the title, how it stands as a chip, then the description, what it does (the listing's features), the palettes and the listing's screenshots, with the author, its status, its build (short hash and date), whether it updates by itself, platforms, the pal install line and, for pal's registry, a link to the page.

Install, Update and Remove go through the core (the SDK's extensions.install, update, remove) and wait until the extension is loaded or gone; a toast says how it went and the list relists in place. Whether something has an update is the core's one check; the palette compares nothing. One that comes with pal is turned off in Settings, never removed from here. The Registries filter lists each registry and an Add registry row; Enter opens Settings › Extensions › Registries.

The first listing in ten minutes and ⌘R fetch every registry, the cached rows shown meanwhile; a registry that did not answer says so above the list, with how old its list is. No settings.

Scripts and data files (scripts)

The zero-code tier: every [palette.<name>] table of a scripts config file becomes a palette, backed by a shell script speaking JSON lines or by a json / jsonl / toml data file. Each such palette has the id scripts-<name>. Its settings and the whole format are in Scripts and data files. A data-file table of 100 rows or more (the nerd and kde icon lists, chars) is a catalog at the root unless the table sets tier itself.

Home Assistant (home-assistant-entities, home-assistant-services, home-assistant-areas)

Home Assistant over its REST API (/api/states, /api/services, one /api/template render for areas), with a long-lived access token; multi, so a second home is [instances."home-assistant@cabin"] with its own url and token (Config).

Home Assistant (home-assistant-entities) is live: every entity of the domains setting, listed again whenever the panel shows, so a light's state at the root is the current one and kitchen light finds it from the root. Favourites come first in their order, then the domains in the setting's order, names sorted within. A row is the friendly name; the subtitle is the domain and the area (when the entity has one); the entity id, domain and area are keywords; the accessories are the state (a coloured tag for on/off/open/locked/playing and the other known states, the value with its unit otherwise) and when it last changed. The icon is the domain's glyph; a light that is on is a dot in its colour (rgb_color, else warm white). The filter (Tab) scopes it: All entities (the domains setting), Every domain (the rest after those), then Lights, Switches, Sensors, Binary sensors, Climate, Media players, People, Scripts, Automations, Scenes; a domain filter shows its domain whether or not it is in domains. The detail pane (lazy) shows the entity, its state and its attributes.

Actions, by domain (Enter is the first; ⌘K has them all):

Every row also has the domain's second action on ⌘Enter (turn on or off, set, pause), Copy entity id (⌘C), Show attributes (⌘⇧A: a level with the state and every attribute as rows, each copying its value, ⌘C its name) and Open in Home Assistant (⌘O: the automation or script editor, the history page for the rest). A service call keeps the panel open and lists again, so the row shows the new state, with a toast naming it; a call that fails is a failure toast with HA's answer. Entity ids are the row ids, so [palettes.home-assistant-entities.item_hotkeys] with "light.kitchen" = "ctrl+alt+k" toggles the kitchen light without showing pal.

Home Assistant Services (home-assistant-services) is every service from /api/services, by domain then name, the id (light.turn_on) as an accessory and a keyword, HA's name and description when it gives them (most core services carry none over REST; the key is title-cased instead). Enter opens a form: the target as a select of the entities the service takes (its domains, every entity for a service that targets any, no field for one without a target), then the service's fields from its description: a select selector is a select, a boolean one a checkbox, the rest text with the example as placeholder and a number's range in the help line. A group's fields are inlined; a collapsed group (HA's "advanced" section) is left out. The submit calls the service with the values coerced by selector (numbers, JSON for objects and anything typed as [...] or {...}, comma lists for entity selectors), empty fields left out, and toasts what changed; a number field that is not one comes back on the form. Copy service id is ⌘C. Listed once an hour.

Home Assistant Areas (home-assistant-areas) is every area that has an entity, with the count; Enter lists those entities. The mapping is one template render (areas(), area_entities(), area_name()), kept ten minutes for the entity rows' subtitles; an HA that refuses the template API leaves the rows without areas and the palette with a hint row.

When something is wrong every palette is one inert hint row that says what and where to fix it (Settings › Extensions › Home Assistant): no URL, a URL without a scheme, no token, a keychain:/env: token that did not resolve, a rejected token (401), a host that did not answer within the timeout, or one that could not be reached. Every request carries the timeout. A URL that redirects (an http:// one behind a proxy that answers 301 to https://) is followed with the token kept, since fetch would drop it on the new origin, and the log says which URL to set.

Settings, [extensions.home-assistant]:

Verification Codes (otp)

One-time codes out of your recent text messages, read straight from Messages' database (~/Library/Messages/chat.db, read-only, one SQLite query per listing). The last hours of incoming messages are scanned; a message counts when it talks about a code (code, kod, şifre, OTP, PIN, parola, passcode, verification, doğrulama, código, token and so on) and carries a run of 4 to 8 digits that is not part of an amount, a date, a time or a phone number; Google's G-123456 is taken by its digits. The row is the sender as Messages knows it (a shortcode like AKBANK, an alphanumeric originator, a number or an email; a number or an email that is in Contacts shows the contact's name, from the AddressBook database the same permission covers), the message text is the subtitle, the code is a green tag on the right with how long ago it arrived. Sections are Today and Earlier, newest first. A live palette: listed again on every show, so the code that just arrived is at the top, and the codes are root results while they are in the window. A message whose text is empty is read from its attributedBody (macOS Ventura and later keep the text there).

Actions:

Permissions and platforms:

• Full Disk Access: Messages keeps the database behind it, and without it SQLite answers "authorization denied" (SQLITE_AUTH); the palette then has one row, "Full Disk Access needed", whose action opens Privacy & Security, Full Disk Access. Grant it to pal, open the palette again. There is no other way to read Messages.
• A database SQLite reports locked (SQLITE_BUSY) is copied aside with its -wal and -shm and the copy is read; the copy is removed after.
• A database that is not there ("No Messages database"), or any other read error, is one inert row with the reason.
• Linux: one "Unavailable" row; there is no Messages.

The bar item otp/latest-code puts the newest code on the strip, green, for a minute after it arrived (hidden otherwise); a click copies it. The same reader, the same permission.

Popover keys of otp/latest-code (rendered every 10 s; the arrows move the cursor, a click sets it):

Settings, [extensions.otp]:

1Password (onepassword-items)

Your 1Password items through the op CLI. One op item list --format json per listing, kept for ttl seconds so the vault filters and a Refresh inside the ttl do not run the CLI (and its unlock prompt) again; ⌘R past the ttl asks it again. The row is the item's title, the vault and the username the subtitle, a glyph by category (login and password, secure note, card and bank account, identity, SSH key, API credential, server and database, and so on), the primary website's host on the right, favourites first with a favorite tag, then by title. The item's website hosts, username, category, vault and tags are keywords, so github.com finds the login. The detail pane leads with the vault over the title, the category, favorite and tags as chips, then the username, the website as a link and the update time. No secret is ever in a row, the index or a log: a pick runs op item get for that one field and puts the value on the clipboard.

Actions:

An item without the field (a secure note has no password, a login without TOTP has no one-time code) keeps the panel open with a toast carrying the CLI's message.

Signed in or not:

• Nothing signed in (or no account set up for the CLI at all) is one row, "Sign in to 1Password", whose action opens the CLI's sign-in page. Sign in with eval $(op signin) in a terminal, or turn on the desktop app integration (1Password, Settings, Developer), then ⌘R.
• With the app integration on, every CLI call that needs the vault shows 1Password's own unlock prompt (Touch ID on a Mac); pal waits up to a minute for it.
• op not installed (looked up on PATH, then /opt/homebrew/bin, /usr/local/bin, /usr/bin) is one row whose action opens the install page.

Settings, [extensions.onepassword]:

Browser Tabs (browser-tabs-tabs)

Every open tab of your browsers, in the browsers' own order, never ranked. A live palette: listed again on every show, so tab titles are root results. Three sources are merged:

• DevTools protocol: a Chromium browser (Chrome, Chromium, Brave, Edge, Vivaldi, Arc) started with --remote-debugging-port=<port>. The tab list is http://127.0.0.1:<port>/json; one WebSocket to the browser then asks every page whether a media element is playing, whether it is muted (the playing and muted tags), how far into its longest video it is, and which browser window it is in. Chrome 136 and later ignore the port flag on the default profile: it needs --user-data-dir too.
• AppleScript (macOS): the browsers in apps that are running, over one osascript run (JavaScript for Automation): Safari, and Chrome when nothing on the port already covers it. No playing or muted state this way.
• Firefox: its session file (sessionstore-backups/recovery.jsonlz4, the newest profile's, LZ4-decoded in the extension). Read-only, since Firefox has no scripting interface: its tabs list, and Focus can only raise its window.

The row is the tab's title (the url without its scheme when there is none), the host is the subtitle, the favicon comes from the url; a tab without a web url (chrome://settings) gets the browser's icon. On the right: where it is in one run (the browser's name when more than one is listed, window N when the browser has more than one window), and playing (green) or muted for a tab the protocol could ask. The url, the host and the browser's name are keywords. The details (⌘I) lead with the browser and window over the title, sound as a chip, then the address.

The filter dropdown scopes the list:

Actions:

Close and mute keep the palette open and list again. A focus, close or mute that fails keeps the panel open with a toast carrying the reason.

Permissions and platforms:

• Automation (macOS): the first AppleScript run asks whether pal may control Safari (and Chrome); a refusal makes every later run fail with error -1743, which the palette shows as one row, "Automation permission needed", whose action opens Privacy & Security, Automation. The DevTools and Firefox tabs still list under it.
• Nothing on the port, no scriptable browser running and no Firefox session is one row saying so.
• Linux: the DevTools and Firefox sources only.

Settings, [extensions.browser-tabs]:

GitHub (github-prs, github-issues, github-repos, github-notifications, github-search)

One extension, five palettes, one sign-in; multi, so a second account is [instances."github@work"] with its own token under [extensions."github@work"] (Config).

Signing in. The token setting when set (a personal access token with repo, notifications, read:org; the file holds a keychain: reference, never the value), else the gh CLI's login (gh auth token, asked at most every five minutes). Neither one gives a single hint row per palette saying how to sign in; Enter on it opens the token page. A token GitHub rejects is the same row with GitHub's message.

Requests. Every request has a 10 s timeout. Pull Requests, Issues and Search are one GraphQL request each, the filters' queries as aliases in it, so "All" and each filter come from the same answer; Repositories and Notifications are REST, which carries ETags: a re-list sends If-None-Match and a 304 costs nothing against the rate limit. The rows already normalised, with the ETag, are kept in the extension's storage (never a raw body), so a restart still has them and an outage shows the last rows with a note in the log. While the rate limit is exhausted a hint row at the top says when it resets.

Pull Requests. Yours (is:open author:@me), the ones waiting on your review (review-requested:@me), and yours merged within merged_days; filters (Tab) All, Mine, Review requested, Merged; the row is the title with owner/repo #n under it, a state dot (green open, grey draft, violet merged, red closed), tags for the checks (checks ✓ / ✗ / … from the status rollup), the review decision (approved, changes requested, review), draft, conflicts, and the updated date. The pane shows the body, then the latest comments and reviews, over the repository, author, branch, size, every check by name, who approved and who asked for changes, reviewers, labels and dates (fetched when the cursor rests on the row).

Issues. Assigned to you, mentioning you, opened by you (open ones); filters (Tab) All, Assigned, Mentioned, Created; an issue in two lists is listed once, in the first. Rows carry the first two labels, the comment count and the updated date; the pane the body, the latest comments and the milestone. Actions: Open, Copy URL (⌘C), Copy reference, Close (⌘⇧X, asks first). Create Issue at the top is a form: the repository (a select of the repositories with recent activity in the lists, then yours by push date), title, body; the submit opens the new issue.

Repositories. Yours (owner or collaborator, by push date), your default_org's recently pushed, and your starred ones, in that order and sectioned so; filters (Tab) All, Mine, Starred, Organisation. Rows: name, description, tags for private, archived and the language, stars, the push date; the pane adds forks, open issues, the default branch, the clone url and the local clone when one sits under repos_root (<root>/<name> or <root>/<owner>/<name>). Actions: Open on GitHub, Open in editor (⌘E, with a clone: code when on PATH, else the folder with the system opener), Open folder (⌘O), Copy clone URL (⌘⇧C, ssh or https per clone_protocol), Copy URL, Copy owner/name, Open issues, Open pull requests. Create Repository is a form (owner: you or the organisation, name, description, private).

Notifications. Unread threads, sectioned by reason (Review requested, Mentioned, Assigned, Your threads, Comments, State changed, CI, Security, Subscribed) and newest first inside one; the first row is the unread count (its actions: open the inbox, mark all read). A row's url is the subject's page (pull, issue, commit; a release or discussion falls back to the repository's page). Enter marks the thread read and opens it, so the count is honest when you are back; Mark as read (⌘⇧R) does not open; Mark all as read (⌘⇧A) asks first. The bar item github/notifications shows the unread count as a badge (hidden at zero) over the same cache; its popover has every unread thread (it scrolls), Open all (this palette) and Mark all read.

Popover keys of github/notifications (rendered every 300 s and on show, wake, network; the arrows move the cursor, a click sets it):

Search GitHub. GitHub's own search syntax, typed: free text, repo:owner/name, is:pr, author:login, label:bug. Results come nearest first, each once: Involved (involves:@me: you opened it, are assigned, were mentioned or commented), Your organisations (your account and every organisation you belong to), Repositories (yours first), Everywhere, Users. A query naming its own repo:, org: or user: skips the organisations tier, and its remaining matches are Other matches. Your pull requests and issues already cached by the two palettes above are also matched loosely against the query, so a typo GitHub's word search misses (directry) still finds them at the top of Involved, shown as you type, before GitHub is asked. Each tier is its own request, sent together, and each shows as soon as the ones above it are in, below what is already there; the whole search takes about as long as GitHub's slowest (about 2 s), and the search row's sweep runs until it lands. A pull request found this way comes without the fields GitHub computes per result (checks, review decision, conflicts, size, which tripled the wait); one that is also in your cached lists shows that copy, tags and all, and the pane fetches the checks by name. Filters Everything, Issues and PRs, Repositories, Users; a query carrying is:, repo:, author: or the like searches issues and pull requests only. The rows and actions are the palettes' above; users show their avatar and open their profile. A keystroke waits 300 ms for the next before asking. Give it an alias ([palettes.github-search] alias = "gs") and gs <text> at the root lands in it with the text typed.

Settings, [extensions.github]:

prs item settings, [bar.items."github/prs".settings]:

For the tests, PAL_GITHUB_API points the extension at another base url (a local server) and PAL_GITHUB_TOKEN is used as the token without asking gh.

Docker (docker, docker-images, docker-compose)

Three live palettes over the docker CLI (docker ps -a, docker images, docker compose ls -a, each with --format '{{json .}}'), listed again on show once their rows are older than ttl. Podman works through the same commands: set binary to podman, or install its docker alias. Without the binary, or with the daemon not answering, each palette is one inert hint row that says which.

Docker Containers (docker): every container, the running ones first in a Running section, the rest under Stopped. The row is the container's name, its image the subtitle; on the right the published ports, compact (80, 443; 8080:80 when host and container differ; a stopped one's status, Exited (0) 3 days ago, instead) and a state tag (running green, exited grey, paused and restarting amber, created blue, dead red). The id, the image and the Compose project are keywords; the detail pane leads with the project and image, the name, the state and status as chips, then lists id, command, created, ports, mounts and networks.

Docker Images (docker-images): repository:tag (the id for an untagged image), the id as subtitle, size and age on the right. Run (Enter) asks for a name and ports in a form (host:container pairs, comma separated; a malformed one is refused under the field) and runs docker run -d [--name] [-p …] <image>; Copy id (⌘C); Remove (⌘D, docker rmi, after a confirm).

Compose Projects (docker-compose): every project docker knows of, its folder as subtitle, its containers' states as one tag (4 running, 1 exited; running green, a mix amber, exited grey). Up (Enter, compose up -d), Logs (⌘L, compose logs --tail 200), Restart (⌘⇧R), Down (⌘D, after a confirm), Open project folder (⌘O). Every config file of the project is passed with -f.

The panel gives a pick 10 s. A command still running after 8 s (a stop whose process ignores SIGTERM and waits for docker's 10 s kill, a compose up that pulls) is left to finish on its own and the toast says so; ⌘R later shows the outcome. A failed command keeps the panel open with docker's last stderr line.

Which terminal Shell opens is the same rule as SSH Hosts' Connect: the terminal setting on macOS, $TERMINAL then kitty, foot, alacritty, xterm on Linux.

Settings, [extensions.docker]:

Services (services)

The OS's service manager, one live palette. What it lists depends on the platform; ttl is the same "list again on show once older than" as Docker's.

Linux, systemd. Filters (Tab): User (systemctl --user), System, Failed and Running (the last two span both managers, in a User and a System section). The row is the unit without .service, its description the subtitle; on the right the unit file's state (enabled, disabled; nothing for static, generated and transient units) and a tag with the active state: the sub state alone when active (running, exited, green), active/sub otherwise (inactive/dead grey, failed/failed red, activating amber). Units are what list-units --all has loaded, then the unit files it has not (a disabled service that never ran), inactive and without a description; templates, masked and alias files are skipped. An instance (app-foo@autostart.service) shows its template's enabled state.

A system unit's Stop, Restart and Disable ask first (a user unit's too with confirm_user). A system verb runs as systemctl --no-ask-password <verb>; when that is refused for want of authentication it is tried through sudo -n (a credential window opened by sudo -v in a terminal), then pkexec (a polkit agent's prompt, when one is running). When none is allowed the panel stays open with a toast quoting all three refusals. A verb still running after 8 s (a stop waiting on TimeoutStopSec, a polkit prompt) goes on without the panel; ⌘R shows the outcome. A journalctl for a system unit shows what your user may read.

macOS, launchd. Filters: Agents (the plists in the agent_dirs folders, one section per folder), Loaded (everything launchctl list knows, sorted; the application.* jobs of running apps skipped) and Running (those with a pid). The row is the label, the program from the plist (its Program, or the first ProgramArguments entry) the subtitle, and on the right the pid and a tag: running (green), loaded (blue, no process right now), exit N (red, the last exit was not 0), not loaded (grey, a plist launchd has not been given). A binary plist is read through plutil.

PAL_SERVICES_BACKEND=systemd|launchd forces a backend; the tests run both on one machine against fake binaries.

Settings, [extensions.services]:

Makefile Targets (make)

Every target of every Makefile under the projects folders, one section per project. A folder is scanned two levels deep for a Makefile, makefile or GNUmakefile (GNU make's own order when several are there); dot folders and node_modules, target, vendor, dist, build are not entered. Targets are read from the file's text, not from make -pn: a line beginning with one or more names and a colon (:=-style assignments, pattern rules and $(VAR) targets are not targets), .PHONY names included even when their rule is not literal, in file order. A description is the ## text on the rule's line, else the comment line right above it (a .PHONY: line in between is skipped).

The row is the target, its description the subtitle (the project folder without one), the project's name a keyword (so pal test finds it from the root); a phony target has phony as one too. The detail pane leads with the Makefile's path, the target and a phony chip, then the description and the recipe.

Run opens a terminal in the project folder running make <target>; the window stays open until Enter is pressed, so a quick target's output is not gone with it, and the HUD names the target. With terminal = "background" make runs unseen instead: a toast carries the exit status and the output's last line, and a failure opens the whole output in a show level too; a run still going after 8 s is left to finish on its own and the toast says so. The terminal is chosen as for SSH Hosts' Connect.

Settings, [extensions.make]:

Audio (audio)

Every audio output and input, in two sections, over the core's audio capability. The default of each direction carries a default tag, the volume is the accessory, a muted device is tagged muted; the subtitle says the direction and, when the OS reports it, the transport (bluetooth, usb, builtin). A headset shows once under Output and once under Input. Live: read again on every show. With no audio backend the one row says which tool is missing.

• macOS: the CoreAudio HAL, in-process (no tool to install): the device's UID is its id (stable across replugs), the volume is the virtual main volume the menu bar slider moves, with the per-channel scalar for a device without one; a digital output without a volume control has no volume accessory and no Mute action.
• Linux: wpctl (PipeWire), else pactl -f json (PulseAudio 16+).

No extension settings. volume item settings, [bar.items."audio/volume".settings]:

Bluetooth (bluetooth)

The paired devices over the core's bluetooth capability, connected ones first then by name, each with a glyph for its kind (headphones, speaker, keyboard, mouse, game controller, phone, computer), a connected tag and the battery as the accessory when the OS reports one (AirPods show L 80% · R 75% · Case 90%). Live: read again on every show. With no adapter the one row says so.

• macOS: the list is system_profiler SPBluetoothDataType -json (the one unprivileged source with the device type and the battery levels, ~80 ms); connect and disconnect are IOBluetooth's own calls (what blueutil does), so nothing has to be installed.
• Linux: BlueZ over bluetoothctl (devices Paired, info, connect, disconnect), each call time-boxed, and only with an adapter under /sys/class/bluetooth (without one bluetoothctl hangs rather than answering empty).

No extension settings. battery item settings, [bar.items."bluetooth/battery".settings]:

Privacy (privacy)

What is using the camera, the microphone or the screen right now, over the core's privacy capability: one row per app, what it holds and for how long (from the log line that first named it, else from when pal first saw it). Live: read again on every show, so camera or mic at the root answers who has it.

• macOS: the camera and the screen from what drives the menu bar's dots, Control Center's sensor-indicators log (Active activity attributions changed to ["cam:us.zoom.xos", "scr:com.google.Chrome"]): the last line of the past day, then log stream for every change, each bundle id named by its app (System, macOS's own capture, reads macOS). The microphone per app from CoreAudio's process objects (kAudioProcessPropertyIsRunningInput, macOS 14.2+), named by the app responsible for the process (ffmpeg in kitty reads kitty, ffmpeg in the subtitle). A camera CoreMediaIO sees running before the log names it is the device alone; an attached Screen Sharing session (screensharingd) is Screen Sharing.
• Linux: pactl -f json list source-outputs for the microphone (pavucontrol's peak meters left out), /proc/*/fd links into /dev/video* for the camera.

The bar item Camera, Mic & Screen (privacy/in-use) is off the strip until something is in use, then one glyph per sensor on an amber band, the apps in the tooltip; its popover is the same rows, each sensor a coloured glyph and word, the durations ticking while it is open. The core watches (every second on macOS, two on Linux, and at once on a Control Center log line, from the first time the extension asks) and fires the privacy trigger on a change, which the item's refresh.on names; the extension does not poll. No settings.

Wi-Fi (wifi)

The network the machine is on, the saved ones and what is in range, over the core's wifi capability, in sections Current / Known / Available plus a Wi-Fi row that turns the radio off or on. The current row's subtitle has the IP, channel and security, its accessories the signal (▂▄▆█ 92%) and a connected tag; a known network that a scan also sees carries its signal and an in range tag; an available one shows its security (Open for none) and channel. Live: read again on every show.

• macOS: CoreWLAN in-process for the interface, the radio, the current link (name, signal, channel, security) and a scan; networksetup for the preferred list, join, forget and the radio switch; ipconfig getsummary for the IP; security find-generic-password -wa <ssid> for a password (the keychain prompts; that dialog is yours to answer). A scan takes several seconds (the radio walks every channel; CoreWLAN and system_profiler take the same 9 s on an M-series laptop), so Available shows the last one (kept for a minute) and the Scan for Networks row runs a fresh one. macOS 15 and later show network names only to an app with Location Services (CoreWLAN answers nil, the CLIs <redacted>; wdutil info would say, but needs sudo), so the first time the palette lists with the names withheld while you are inside it, it asks, once: the system prompt, the same as Calendars (a listing at startup or on a show is held back, so nothing asks at first run or next to another prompt; the Wi-Fi names need Location access row asks on Enter meanwhile). Say yes and the next listing has the names; until then the current row reads "Connected network" with its IP and channel, and the Scan row counts the nearby networks whose names are hidden. A refusal keeps that row (Enter opens Privacy & Security > Location Services) and puts a Grant button in Settings > General > Permissions and on the Overview.
• Linux: NetworkManager over nmcli -t (device wifi list, which answers from NetworkManager's own scan cache, so Available lists at once; connection show for the saved ones; device wifi connect; connection delete; radio wifi; -s -g 802-11-wireless-security.psk for a password).

No settings.

Now Playing (media)

The playing track is also the empty root's Now section's row (nothing while nothing plays). One row per running player over the core's media capability: the track as the title, artist and album as the subtitle, the cover (the system's Now Playing artwork on macOS, else the player's artwork url, else the app's icon), the position as 12:34 / 1:06:03, the player's name and a playing / paused / stopped tag, playing ones first. A player with nothing loaded reads "Nothing playing" with the player's name; one playing without a track (Chrome with YouTube on macOS reports the position and nothing else) is its app's name with the position as the subtitle. Live: read again on every show, and the position is the core's estimate at that moment (it advances from the last report and the clock while playing). With no player running the one row says so; on Linux without playerctl it says to install it.

• macOS: Spotify and Music through AppleScript, only while the app is running (the check is NSRunningApplication, so pal never launches one to ask) and only once macOS lets pal automate it: the first Apple Event to an app is the system's Automation consent alert (Music adds its Media Library one), and pal never fires that from a listing or at launch. Until you allow it the app's track shows on the system-wide row below, and the palette has a row "Spotify is running; let pal control it directly" whose Enter lets macOS ask; refused in System Settings > Privacy & Security > Automation stays refused. Spotify's own row gives the artwork url and the track url. The system-wide Now Playing (any other player: a browser, VLC) is one more row, named and iconed from the app's bundle id, through the bundled MediaRemote adapter (mediaremote-adapter.pl plus a framework, run by /usr/bin/perl; the one source that works on macOS 15.4 and later, where nowplaying-cli gets null). The adapter runs as one stream child of pal for as long as pal does (started on the first look, restarted if it dies, ended with pal): every change the system reports lands in memory as it happens, with the cover, so a look costs microseconds and never a process. Nothing to install.
• Linux: playerctl over MPRIS, one row per player; the icon is the player's .desktop when one is named like it.
• Your other extensions' players (the player control, docs/design/controls.md): what the Apple TV, Spotify (its Web API, so any device) and Jellyfin play comes first, named by its app and device ("YouTube · Living room"), the position moved along from when it was read. Enter opens that extension's own view (the Apple TV's remote, Spotify's lyrics), ⌘Enter plays or pauses, ⌘→/⌘← skip, each on that player. A player that says it shows the same playback as a system row (Spotify on this Mac) drops that row. The bar item leaves alone a player whose extension's own item is on the strip (Spotify's lyric line, the Apple TV's remote), so one playback is never on the bar twice and no bespoke item is replaced; the rest it follows as before.

The bar item media/now-playing puts the playing track on the strip (hidden while nothing plays) with the track row (the cover, or the app's icon, at row size; a click opens the track) over Pause, Next, Previous, Copy Track and Open in its popover. On macOS the core's stream fires the item's media trigger the moment the track, the state or the cover changes, so the strip follows a skip at once; on Linux the extension polls the players every 5 s while one plays and pushes a track change itself.

Popover keys of media/now-playing (rendered every 30 s and on show, wake, media; the arrows move the cursor, a click sets it):

Settings, [extensions.media]:

now-playing item settings, [bar.items."media/now-playing".settings]:

The Playing card (media/playing, a glance-only item: "strip": false, in the default general.glance): one card for whatever plays, published players and the system's alike, a provider's own bar item showing it or not (the card is no strip, so nothing doubles). The one that started playing last leads: its track (the app when it names none), "artist · where" under it, its cover, its progress along the foot, rendered every 10 s while it plays. A second playing one is an "also: Weird Fishes · Spotify" line, a third and more "+N more"; with nothing playing the last paused one leads, muted; nothing at all is no card. The card's click and its ⌥N open the lead's own view (the Apple TV's remote, Spotify's lyrics, this palette for a system player); an also line opens that player's, "+N more" this palette.

Displays (displays, displays/brightness)

Every display with its mode and brightness, from displays/. One row per display: its name (the Displays pane's, "Built-in Liquid Retina XDR Display", "DELL U2720Q"), the mode it is in as the subtitle (2560×1440 @ 60 Hz · HiDPI, the rotation, the connection), main and mirror / mirrored tags, and the brightness as the accessory where something can read it. The typed argument on the row takes a percent or a step (40, +10) for ⌘B. Enter drills into the display:

• Brightness, Contrast, Volume (the last two over DDC, on an external monitor; Volume only when the monitor answers for it): a slider view. ← → move by the step setting, ⇧← ⇧→ by 1 %, 1…9 are 10…90 %, 0 is 100 %, m full, a click on the slider sets the clicked fraction. The built-in panel never goes below 5 % from here, so the screen stays readable. From the row, ⌘= and ⌘- step without opening the slider and ⌘B takes the percent typed in the bar.
• Input source: HDMI 1 / 2, DisplayPort 1 / 2, USB-C (the VCP 60 codes; LG's alternate codes by the setting), or another code typed in. ddcctl and ddcutil read which is active and tag it; m1ddc only sets.
• Resolution & scaling: every mode displayplacer lists, HiDPI ("looks like") first, then native, each with its refresh rate, the current one tagged. A mode that changes the resolution or the scaling asks first; the arrangement before is kept as an Undo row at the palette's root until it is used or forgotten.
• Rotation (0 / 90 / 180 / 270; rotating the built-in screen asks, with displayplacer's own warning), Mirror with… / Stop mirroring, Make main (the origins shift so the display sits at (0,0), the layout otherwise kept), Sleep displays (System's own command).

At the root too: Night Shift on / off when the nightlight CLI is installed, Sleep displays, and the presets: "Save current arrangement as…" keeps displayplacer's own reproduce line (one command per output on Linux) under a name; each preset is a row with Apply, Rename (⌘R), Overwrite with the current arrangement (⌘S) and Delete (⌘⌫), its commands in the detail pane. Live: read again on every show (the tool listings are cached for 20 s, ⌘R reads afresh). What is missing for the displays there are is a Setup row each, Enter copying the install command.

Settings, [extensions.displays]:

brightness item settings, [bar.items."displays/brightness".settings]:

Bar item displays/brightness: the chosen display's brightness as a glyph (three steps of the same sun) and the percent; a scroll on the item moves it by the step. The popover is a card per display with its mode line and a slider (↑ ↓ move between them, ← → and the digits set the one the cursor is on, n Night Shift, Enter opens the display in pal, p the palette). Hidden by its rules (Settings > Bar) while only the built-in display is connected, whose keyboard keys already set it, and while nothing installed can set any display; show = "always" keeps it muted with the level.

Routes: pal://displays/brightness?value=50|+10|-10&display=main|external|builtin|<id>|<name> (also contrast, volume), pal://displays/input?source=hdmi1|hdmi2|dp1|dp2|usbc|<code>, pal://displays/mode?mode=<n>|1800x1169|1800x1169@60|2560x1440 hidpi|3024x1964 native, pal://displays/preset?name=<name>, pal://displays/night-shift?state=on|off|toggle.

Unicode Characters (unicode)

A grid of 1795 characters one pastes rather than types (a catalog at the root: three rows there, the rest behind the "more" row), from unicode/data.json: arrows, math, Greek, currency, quotes and dashes, punctuation, typographic and zero-width spaces, superscripts and fractions, accented Latin letters (the Turkish, German, French, Nordic and Spanish sets), letterlike symbols, the Mac keyboard glyphs (⌘ ⌥ ⇧ ⌃ ⎋ ⏎ ⌫ ⇥ ⏏ and the control pictures), check marks, box drawing and block elements, geometric shapes, miscellaneous symbols, dingbats, enclosed numbers and letters. The tile is the glyph (a space shows as the open box ␣); the name is the Unicode name in lower case; the section is the block. The search matches the name, the code point (2192 or u+2192), the HTML entity names (rarr, nbsp), the LaTeX command where there is an obvious one (\rightarrow, \alpha), the character's Unicode 1.0 name (command key) and plain words (cmd, turkish, tick, eur).

The last twelve characters copied lead the grid in a Recent section (kept in the extension's storage) and leave their block while they are there. The section is rebuilt when the palette lists again (at start, on ⌘R); between listings the core's frecency already moves a picked tile up.

Actions:

The detail pane (⌘I) shows the glyph large, the block, the code point, both HTML forms, the UTF-8 bytes (E2 86 92), the LaTeX command and the aliases.

The table is generated: bun run unicode/build.ts fetches UnicodeData.txt (names) and the WHATWG entities.json (entity names), applies the sections, LaTeX and keyword tables in the script, and writes data.json (160 KB), which is committed. The whole UCD is not shipped; add a range or a code point to the script's SECTIONS to widen the table.

Settings, per palette, [palettes.unicode.settings]:

Colors (colors-picker, colors, colors-history, colors-convert)

Four palettes over one colour maths (the SDK's colors, sdk/src/color.ts) and one history. At the root a hex, an rgb()/hsl()/oklch()… notation or a CSS name answers inline under a Convert Colour section (the first four notations; Enter opens the picker on it). Colour Picker is a view level: a large swatch on a sunken well over a hue strip and a saturation/value plane (both drawn by the app from the colour, the ring marking where it sits), the colour in hex, rgb, hsl, hwb, oklch, oklab, lab and display-p3 with its CSS name (or the nearest, in OKLab), the nearest Tailwind and Material tokens, the contrast on white, on black and against the previous colour with the WCAG level as a badge, and to the right nine tints, nine shades and the complementary, analogous, triadic, split and tetradic harmonies as tiles. The keys edit the colour in place: ←/→ turn the hue 5°, ↑/↓ move the lightness 2 points, -/+ the saturation 5 points, ⇧ makes an arrow step three to five times bigger, m switches to OKLCH (lightness, chroma and hue; a chroma step stops at the sRGB gamut edge instead of clipping) and back. ⇥ moves the focus from the swatch to the tints, the shades and each harmony row in turn (⇧⇥ back): the arrows then walk the row, the label names the tile and Enter takes it. A digit or # opens a text field in the search row with that character; type any notation and Enter applies it, Escape closes the field (a notation that does not parse stays in the field with a toast). c (and Enter on the swatch) copies in the notation the format setting names, ⌘C always the hex, ⌘⇧R rgb, ⌘⇧H hsl, ⌘⇧O oklch, ⌘⇧L lab, ⌘⇧P display-p3, ⌘⇧N the CSS name, hwb and oklab from ⌘K. p picks from the screen: the panel hides, the system's loupe appears (NSColorSampler on macOS, the screenshot portal on Linux), and the panel comes back in the picker on the picked colour (unchanged after Escape). h opens the history, n the named sets, u goes back to the previous colour, r makes a random one. The colour, the model and the history live in the extension's storage, so Escape and a restart lose nothing.

Named Colours is a grid of 995 swatch tiles (a catalog at the root: three rows there, the rest behind the "more" row), one section per set, with a filter per set in the dropdown (⇥ cycles them): the 148 CSS names, Tailwind 3.4 (slate 500), the Material 3 baseline tonal palettes (primary 40, generated from the seed #6750A4 with Google's material-color-utilities), the 2014 Material palette (red a200), Apple's system colours in the light and the dark appearance (blue, gray6), Catppuccin's four flavours, Rosé Pine's three variants, Nord, Solarized, and pal's own tokens. The search matches the name, the hex, the token spelling (slate-500, systemBlue, mocha/mauve) and the set. Enter opens the tile in the picker; ⌘Enter copies it in the chosen notation, ⌘⇧C the hex, ⌘⇧N the token. The detail pane (⌘I) adds where the token is used: the Tailwind utilities, the Material 3 role, the UIColor/NSColor name and what Apple uses it for, the role a theme gives it (Catppuccin's mauve is keywords, Nord's nord8 the primary accent). The last twelve opened lead in a Recent section. The sets setting narrows what All lists; the dropdown reaches every set regardless.

Colour History (live, so its rows at the root follow every pick and copy) lists every picked and copied colour, newest first, one row per colour, with the hex, where it came from (the screen, typed, a set with its token, the picker, the converter) and when; the CSS name (or ≈ the nearest) is the accessory, the chosen notation when it is not hex. The first row is Pick Colour from Screen, which is also at the root: the loupe, then the colour copied in the chosen notation with the HUD naming it, and remembered. Enter on a colour opens it in the picker, ⌘Enter copies it, ⌘D removes it, ⌘⇧D clears the history (with a question). The history_size setting caps it (50).

Convert Colour is an input palette: type a colour in any notation and the rows are its conversions, each with a swatch. It reads hex in every length with or without the hash (#f80, ff880080), rgb()/rgba() in the comma and the space syntax with percentages and alpha (rgb(255 136 0 / 50%)), a bare triple (255 136 0), hsl()/hsla() with hue units (deg, turn, grad, rad), hwb(), oklch(), oklab(), lab() (CIE Lab against D50, as CSS means it), color(display-p3 …), color(srgb …) and the CSS names. The rows: every notation, the CSS name (or the nearest one, tagged close, near or far by its OKLab distance), and the contrast ratio on white and on black, each tagged with what it passes for normal text (AAA at 7, AA at 4.5, AA large at 3, else fail, WCAG 2). Enter opens the picker on the colour, ⌘Enter copies the row; a contrast row only copies. Something that is not a colour gives one inert row saying so.

The rows of the sets are generated by bun run colors/build.ts (the CSS table from color.ts, the tokens read from tokens.css, Tailwind and Material fetched from unpkg, Material 3 computed with the library from esm.sh, Catppuccin from its GitHub palette; Apple, Rosé Pine, Nord and Solarized are hand-kept in sets.ts) into data.json (72 KB), committed. The maths is unit-tested against the CSS Color 4 reference points (test/colors.test.ts in pal-extensions).

Settings, [extensions.colors]:

Per palette, [palettes.colors.settings]:

Icons (icons, icons-freedesktop, icons-iconify)

The two glyph grids are catalogs at the root: three rows each there, the rest behind the "more" row, and a glyph named exactly what was typed (git) sits under the primary rows that have the word, not above Google Chrome. Nerd Font icons is a grid of every glyph in the Symbols Nerd Font the app bundles (app/src/assets/fonts, Nerd Fonts 3.5.1): 10995 glyphs, one section per set in a fixed order (Material Design, Font Awesome, Codicons, Octicons, Devicons, Seti, Weather, Font Logos, Font Awesome Extension, Powerline, Powerline Extra, Pomicons, IEC Power, Custom, Extra, Indent). The tile is the glyph, the name is the set's name with spaces (account circle), the code point is the subtitle and the nf-md-account_circle name a keyword, so md-account or f0009 finds it. The last twelve picked lead in a Recent section.

The detail pane names the set and the Nerd Fonts version, the code point, the CSS class and the \u{f0009} escape; it does not draw the glyph large, since the pane's text is the UI font and only the icon box uses the bundled symbols font.

Freedesktop icon names is a second grid: the 114 freedesktop names the SDK's xdg() maps to a glyph (sdk/src/icons.ts, what a script's icon_xdg may say), each drawn with its glyph and its Nerd Font name as the subtitle. Enter copies the name; the glyph (⌘Enter) and the code point (⌘⇧U) are the other actions. Only the names in that table are listed: pal draws no other, so a longer list would show names that render as nothing.

Iconify Icons is a third grid, an input palette over Iconify's public API (api.iconify.design, no key): every set it hosts (Material Design Icons, Tabler, Lucide, Phosphor, Simple Icons, Heroicons and the rest, some 200k icons), searched by name 250 ms after the last keystroke: /search?query= answers the names and the sets, then one /<prefix>.json?icons= per set the SVG bodies, cached per word and per icon for the process. Each tile is the icon's own SVG, filled mid-grey so it reads on both themes (Iconify draws in currentColor, which a picture cannot inherit); the set's name is the section. Nothing typed lists nothing (the placeholder says what to type); no hit, a rate limit (429) or an unreachable API is one hint row, and a failed search is not cached so ⌘R asks again.

The glyph table is generated: bun run icons/build.ts fetches glyphnames.json at the pinned release and writes data.json (282 KB, [name, code] pairs by set), committed; bump the version in the script together with the font. A listing is eleven thousand rows (about 3.4 MB over the host's pipe) on every start, as the palette has no ttl; the rows carry the least they can for that.

Settings, [extensions.icons]:

Per palette, [palettes.icons.settings] and [palettes.icons-iconify.settings]:

Night Parade (night-parade)

A survivors game: the Night Parade of One Hundred Demons marches through an abandoned village tonight, and you last until dawn. Enter on the palette's row opens it as a view level whose body is the extension's own page (a surface). The design, and why each part is there, is night-parade/DESIGN.md.

• A night is fifteen minutes in three acts (Dusk, Midnight, the Hour of the Ox), each with its own crowd and scripted events, mini-bosses at 2:30, 7:30 and 12:30 and bosses at 5:00, 10:00 and 15:00. Beat the Oni and dawn breaks.
• Weapons fire on their own. The arrows (or WASD) move, space dashes (you can't be hurt in a dash), and each level offers three choices (four with luck): 1 2 3 or the arrows and Enter; R rerolls, X skips, B banishes, each with charges from the shrine.
• Sixteen weapons, each with eight levels and an evolution when you carry its item; sixteen items; six heroes, four of them unlocked by playing. Your attacks break the enemy shots they touch.
• Enter, P or ⌘K's Pause stops the night; the pause card shows your build and stats, Q gives the night up. Escape leaves (the panel hidden pauses it); Backspace is back on the page's own screens.
• Between nights: gold buys lasting blessings at the shrine, the codex keeps what you've found and defeated, and harder omens open after the first dawn. The save is the extension's storage; sound and music are the page's own settings (M mutes).

Network (network)

This machine's addresses, one row per value: the value is the row's name so it reads at a glance, the label is the subtitle, Enter copies. Live, listed again when the panel shows and the last listing is over a minute old; ⌘R lists now. The palette opens with the detail pane showing.

Every tool runs with a 3 s timeout and a missing one just leaves its rows out. The tunnel interface carrying the Tailscale addresses (utun4, tailscale0) is folded into the Tailscale rows. When nothing has an address, or there is no route, an inert row says so; the public IP row says why when the fetch fails.

The SSID on macOS: since Sonoma the system redacts the network name for a process without Location Services access (ipconfig getsummary prints <redacted>, networksetup -getairportnetwork says not associated), and pal's own grant does not reach the tools it runs: ipconfig under a granted pal still prints <redacted> (checked on hornet). So when the summary is redacted the palette asks the core's wifi capability, which reads the name in-process (CoreWLAN) and has it once pal holds Location access (the Wi-Fi palette asks for it); until then the Wi-Fi row is labelled by kind (en0 · Wi-Fi) and the detail pane says what is missing.

Actions:

No Flush DNS: on macOS it is dscacheutil -flushcache; killall -HUP mDNSResponder, which needs sudo, and the host has no way to ask for a password; run it from a terminal.

The detail pane lists every field of the row: interface, kind, SSID, security, IPv4, IPv6, MAC and status for an address; city, region, country, organisation and when it was fetched for the public IP; the resolver order for a DNS server.

Settings, [extensions.network]:

Timer (timer-timers)

Named countdown timers over the timer CLI (~/.local/bin/timer in the owner's dotfiles): the CLI keeps the timers, one detached process per timer that fires on its own (confetti, a chime, a phone ping) and one KV file per timer under its state directory. pal is a view of that directory and asks the CLI for every change, so a timer started from a terminal and one started here are the same thing. Live: listed again on every show; the empty root's Now section shows the most urgent one (running, paused or just landed) with its own actions, nothing when there is none.

One row per timer, most urgent first (landed, then running soonest first, then paused): the name, what is left and when it lands (or "Paused at 12:34", "Landed 0:42 ago"), a state tag. Then New timer, a form: a duration (25m, 90s, 1h30m, 2:30, a bare number is minutes; the CLI parses it and its complaint comes back under the field), an optional name (the duration otherwise; a name already taken restarts that timer), and a checkbox to ring the phone out loud when it lands (--ring). The same from a link: pal://timer/start?duration=25m&name=tea (&ring=1 rings; Links).

Start Pomodoro is the last row while no pomodoro runs. It starts a work timer (Pomodoro 1 of 4, pomodoro_work minutes) and the cycle then runs itself: when that timer lands the extension stops it and starts the break's (Break 1 of 4, pomodoro_break), then the next round, after the last round the long break (pomodoro_long_break), then round 1 again, each a timer of the CLI's own (its chime and phone ping fire as for any timer), each announced on the HUD ("Pomodoro. Break: 5 min"). The pomodoro's row wears an apple, the phase as a tag (work violet, break green) and "Round 2 of 4, work" before what is left; the bar item reads 18:27 · 2/4 while working and 4:59 · break on a break. A finished work round counts toward Pomodoros today: N, an inert row at the bottom (sixty days of counts in storage); the session is in storage too, so a host restart picks it up. Stopping the pomodoro's timer (here, or timer stop in a terminal) ends the cycle; so does a landed one the CLI reaped while the host was down.

Actions, by state:

Every pick runs the CLI (timer pause <id>, resume, add 5m <id>, stop <id>, done) with the state directory as TIMER_DIR and lists again; a refusal is a toast with the CLI's words.

The bar item (timer/timer, Extensions): the soonest timer's remaining time as the title with a fill for how far along it is, blue, then amber past two thirds, red past nine tenths, muted while paused; a landed timer is the alarm (its name, or "Done" for an unnamed one, in red) until the CLI's badge ttl (5 minutes) or a Dismiss removes it. Hidden with no timer at all. A click opens this palette. The second-level countdown is pushed by the extension itself (a watch on the state directory plus a 1 Hz tick while a timer runs); the core asks every 10 s and on wake besides.

Popover keys of timer/timer (rendered every 10 s and on wake; the arrows move the cursor, a click sets it):

A pomodoro's card carries the phase as a tag next to when it lands. The key hints are two rows, the card's keys then the popover's own, and the second ends with today's finished rounds (3 today).

Settings, [extensions.timer]:

Calendar (calendar-today, calendar-schedule, calendar-quick, calendar/upcoming)

Two live palettes, one input palette (Quick Add) and a bar item over one source and one cache; Today also suggests the empty root's Now section its row: the event the strip speaks for (the current one, else the next inside horizon_hours) as a Today row, Join first when it has a call; and in place of it, a row per call about to start (Standup over starts in 3 min · Zoom · 10:00 – 10:30, then started 4 min ago): from call_lead minutes before it (5 by default) until ten minutes in or its end, the earlier start first when two overlap, declined and all-day events never; Enter joins, ⌘C copies the link, ⌘Enter opens the event. Quiet (no sound, no notification), read against the clock on every show of the panel, the events from the cache when that is under a minute old (calendar/source.ts). The source is a setting: system is the core's calendar capability (pal_core::calendar: EventKit on macOS, so every account Calendar.app has is one store and one permission; khal on Linux, read through its list --json); google is the Calendar API v3 read directly per account; auto (the default) is google once an account is listed, else system. Every reader goes through load, which keeps the last window fetched (local midnight to days ahead, two at least) and answers it while it is younger than the caller's allowance: a palette show takes up to a minute, the bar's minute tick five, a refresh nothing. A fetch that fails leaves the last events in place as stale, so a source that is away costs the strip its freshness, not the meeting.

Today is the day's events in time order, whatever their state: the row is the title, the time range with how long (10:00 – 10:30 · 30 min · Room 4, All day), the calendar glyph tinted with the calendar's colour, and the state as the first tag: in 12 min (in 2 h 5 min) in blue, now, 25 min left in green, over in grey, today for an all-day one; then declined / maybe, the head count, Join when there is a call. Once no timed event is left today a Nothing else today row names the next timed event's day (Next: Concert, tomorrow 19:00, Next: Review, Sat 19 Sep 09:00; Nothing today on a day that never had one) and tomorrow's rows follow under their own section. The bar's popover opens the same palette with args: { rest: true }: the over ones dropped and tomorrow always there.

My Schedule is the week: sections Today, Tomorrow, This week (within seven days), Later (up to the days setting); events that have ended are gone, an all-day one lasts until its midnight; the current event carries a now tag, else the next one in 12 min (in 2 h further out, nothing past a day); the calendar's colour as the row's dot, the head count, Join, declined or maybe. The last row is New event on the system source.

A call is Google's conferenceData video entry point (else hangoutLink), or the first Zoom, Google Meet, Teams, Webex, Jitsi, Whereby or GoTo meeting link in the event's url (system), location, then notes or description; Outlook safelinks are unwrapped and & unescaped. A Zoom marketing page or a docs link does not count.

The filter dropdown is one entry per calendar (read when the host loads, so a calendar added later shows at the next start; a Google account's are named by account, Personal (personal)). The detail pane is the notes as markdown (a Google description as text, its HTML stripped; the title when there are none) over when with the duration, the calendar and its account, the location, the call or link, the organizer, every attendee with their reply as a coloured tag, your own reply, and whether it repeats.

The bar item (calendar/upcoming, Extensions): the next event's name as the title with the time as a segment after it (in 12m, 25m left while it runs), so the target's max_chars clips the name and never the time; while one runs the next due under the same rules adds an in 8m segment in its own colour, its name in the tooltip. Hidden when nothing timed starts within horizon_hours (10), so a clear evening is a clear strip. The event is the first that has not ended, timed unless hide_all_day is off, not declined unless hide_declined is off, starting inside the horizon; a running one counts until it ends (a click joins its call, not the next one's). Colour by escalation, the boundaries inclusive: muted far off, amber from warn_minutes (15) before the start, red from urgent_minutes (5), green while it runs; sketchybar draws the same names through the bar module's colour map. A dot badge says there is a call. The tooltip is the title, the time range and the calendar. A click opens Today in the popover (the rest of today and tomorrow, Enter joins). The core asks every five minutes and on wake, the network coming back and the minute tick; a minute tick renders from the cache (0.1 ms through the host in the tests; the count-down needs no fetch), every other reason fetches (about 80 ms for a week from EventKit on hornet, 250 to 350 ms for two Google accounts whose token commands hop over ssh). A failed fetch keeps the last item as stale; no cache and no source is hidden.

Popover keys of calendar/upcoming (rendered every 300 s and on minute, wake, network; the arrows move the cursor, a click sets it):

Google. Each account is one entry of accounts, name = command: the command prints an access token for the Calendar API on stdout (a bare token, or the JSON an OAuth endpoint answers with access_token and expires_in); pal runs it through sh -c, keeps the token in memory until its expiry (30 minutes for a bare one, a minute's margin), mints again once on a 401, and never writes a token anywhere: the command is the secret's owner, so nothing secret sits in the config. gcloud auth application-default print-access-token after an application-default login with the calendar.readonly scope (documented, not verified here), a keychain helper, a broker behind ssh (quote the remote command for its shell: ssh archer "curl -s 'http://…/token?aud=calendar'"). An entry reads the account's primary calendar; a table in the file, { name, token_command, calendars = ["primary", "<id>"] }, reads more. Events are read with events.list (singleEvents, timeMin/timeMax, the conferenceData entry points), the calendars from calendarList (their colour, title and access role), all accounts at once. One account away is logged and the rest list; every account away keeps the last events read behind a hint row. Google rows open in the browser and are not deleted or created from here.

On Linux, khal new prints no id and reads dates in the formats of its own [locale] section; with none set (the C locale's %c), khal cannot parse a timed event back, so pal refuses one with the format to set (datetimeformat = %Y-%m-%d %H:%M) rather than saving it wrong. All-day events go through either way.

New event is a form: a title; a day in words (today, tomorrow, fri, next mon, next week, 2026-09-20, 20.9, 20 sep, sep 20); a start and an end time (14:30, 2pm, 2:30 pm, 1430, noon; an end before the start is the next day); an all-day checkbox (then the end may be the last day, 22.9); the calendar (the writable ones, or the backend's default); a location; notes. A field that does not parse shows its complaint and keeps what was typed; the backend's refusal (a read-only calendar) comes back under the title.

Quick Add Event (calendar-quick, an input palette) is the same write from one typed line, parsed as you type (calendar/quick.ts, pure, on parseDay and parseTime): a title first, then in any order a day (tomorrow, fri, next tue, 20 sep, 2026-09-20, on monday), a time or a range (10:00, 2pm-3pm, 14:00 to 15:30, 9-10am), for 45m (else default_length, 30 minutes), at <place> (free text at the end, unless a time follows the at), @ <calendar> anywhere (in <calendar> too when a writable calendar starts with the word; an in in a title stays), all day. No time makes it an all-day event; no day means today, or tomorrow once the time has passed (an amber tomorrow tag says so). The one row reads the event back, dentist · Fri 18 Sep 14:00 to 15:00 · Room 4 · Home calendar, the calendar's colour on the glyph and the start as a date accessory; a line that is only a day, or nothing, is a hint row naming the grammar; a calendar name nothing matches falls to the default and the row says so. Enter creates it through the form's write (calendar.create, the cache dropped, the "Added" toast); a refusal is a failure toast. The palette declares fallback: "Add “{query}” to the calendar", so a root query nothing matched offers the line as an Add row. The permission rows are the others'; a Google source refuses the write as the form does.

Permission. macOS lists an app under Privacy & Security > Calendars only after it has asked once, so while the state is not_determined the palette is one row, Grant calendar access, whose Enter shows the system prompt (the panel hides while it is up; open the palette again after answering). denied and restricted are one row that opens that pane. The app carries NSCalendarsFullAccessUsageDescription (and the pre-14 NSCalendarsUsageDescription) in its Info.plist; without the string macOS ends the process instead of asking. On Linux without khal the one row says so. The Google source needs no permission: a token that fails shows on the listing.

Settings, [extensions.calendar]:

upcoming item settings, [bar.items."calendar/upcoming".settings]:

Not built: accept and decline (EventKit has no public API to change a participant's status; Raycast does it through the private EKParticipant setter; the Google tokens this is built for are read-only), a second calendars palette toggling visibility (an extension cannot write its own settings), reminders, an OAuth flow of pal's own (a Google client id would have to ship with it).

Flashcards (flashcards, flashcard-packs, flashcard-add)

Spaced repetition for the minute a build takes (flashcards/, its README has the detail). Enter on Flashcards opens a view level whose body is the extension's own page (a surface) on the next card due across every pack in practice; each answer is saved as it is given, so Escape at any point loses nothing. The first open asks what to learn.

• A card on a stack: Space flips it to the meaning and an example sentence; → (or Space) Knew it throws it right, ← Didn't know left, or drag it; each button says when the card comes back (four buttons with buttons: Barely and Too easy too, 1–4). FSRS schedules (ts-fsrs, desired retention 90% by default).
• Sessions of session answers (10) with a bar along the top, then a summary: the words missed, new and mastered as chips, the share of everyday speech the known words cover and what the session added; Enter keeps going, d drills the misses, s the stats page (streak and best, heatmap, the week ahead, each pack).
• A pack with reverse makes the back-to-front card of a word once the word is learned, and it is typed: case, punctuation and one of several meanings are fine; a missing accent, article or one slip is close. Tab gives a letter; a' types á, n~ ñ.
• New cards in pack order (new_per_day, 15), one after every three reviews; the two cards of a word never on the same day; the day runs to 4 am. A noun's article is coloured by gender.
• ? lists the keys; Tab says the word (a deck's recording, else the best system voice installed); ⌘Z undoes, from the summary too; ⌘E writes your own meaning; ⌘K: suspend, learn more, the refresher (the cards missed this week, lapsed three times or fading, drilled without touching the schedule), mute, the packs folder. While cards are due, a row in the root's Now section.

Flashcard Packs lists the bundled packs (Spanish: Jeff Doozan's 6001 most common words with example sentences, everyday phrases) and the files in the packs folder (an Anki deck as .apkg, with its recordings; TSV, CSV, an Anki plain-text export, or JSON), what is practised first, each with mastered, learning and new; Enter studies one alone, ⌘Enter adds it to practice or takes it out, ⌘R its refresher. Add Flashcard takes front = back into My cards. Browse Anki Decks searches AnkiWeb's shared decks as you type (nothing typed: the language being learned): cards, audio, pictures, how many liked it; the description and sample cards in the pane; Enter downloads the deck in the background into practice, ⌘Enter opens it on AnkiWeb. The first open's b, a row in Flashcard Packs and ⌘K lead there.

Games (games)

Every game as a showcase: the game the cursor is on at the top, its own store screenshot cut to the game itself, its title and tagline beside it, and every game's cover under it in a grid of five: two rows in view and the top of the next, sliding up a row as the cursor goes down. A cover is the part of a store screenshot the game picked to show itself up close (cover, docs/design/screenshots.md). What came out in the last week comes first, newest first, marked New (the listing's released, docs/registry.md); then the installed games, then every game the registries list for this machine that is not installed, marked Not installed; each of those by name. Nothing is kept here: every open reads the installed extensions' manifests and lists each view palette of a loaded extension the store shelves under Fun.

• right or tab walks to the next game, left or shift+tab back, round the ends; down and up move a row, in the same column; a letter or a digit jumps to the next game starting with it; a click on a cover goes to it. The title line says where you are ("3 of 15"), and the next open lands on the same game.
• enter opens the game as its own level (Escape comes back). On one not installed it installs it from its registry, waits for it to load, then opens it (Installing… meanwhile); an install that fails says why on the game until the next try.
• cmd+l on a game with leaderboards opens them.

The pictures are each game's cover shot (else its first), its -dark twin (docs/registry.md), downloaded once into pal's cache folder (~/Library/Caches/pal/games, ~/.cache/pal/games on Linux) and fetched again after a week; a game whose picture is not there yet shows its glyph until it lands. No settings.

2048 (2048)

The sliding-tile game in the panel, keyboard only. Enter on the palette's row (or its hotkey) opens the board as a view level: the search input gives way to the score, the footer shows the primary key, ⌘K lists every move with its key.

• Moving: the arrows or hjkl slide every tile that way; equal neighbours merge once per move, a 2 (or a 4, one in ten) lands on a free cell. A move that changes nothing spawns nothing and is not counted.
• U takes the last move back (one move, undo setting), game over too.
• The first 2048 shows a banner: Enter keeps going, N starts over. Game over shows the score, Enter for a new game. N mid-game asks first.
• Escape leaves at any point; the board, the score, the move count and the best score persist (in the extension's storage).

Tiles are the view vocabulary's tile nodes on a sunken well, drawn by the app with its tokens (paper for 2, the neutral tint for 4, then solid tiles walking the tag palette's hues warm to cool, grey at 1024, the accent at 2048), so the board follows the theme; a slid tile glides to its new cell, a merge pops in place, the spawned tile pops a beat later. The arrows and hjkl are one action each with two keys.

[extensions.2048]
undo = true

Wordle (wordle)

The five-letter word game in the panel, keyboard only. Enter on the palette's row (or its hotkey) opens the board as a view level: the search input gives way to the puzzle's name ("Daily #259", "Practice"), the footer shows the primary key, ⌘K lists the moves with their keys (the letters route without being listed).

• Typing: the letter keys fill the row, Backspace takes one back, Enter submits; a word not in the list is a red badge over the board. A typed letter pops in; a submitted row flips tile by tile: green in place, amber elsewhere in the answer (a repeated letter only as often as the answer has it), grey otherwise. The on-screen keyboard keeps each letter's best mark. Tiles and keys are tile nodes drawn by the app with its tokens, on a sunken well, so the board follows the theme.
• Daily (daily, on by default): one puzzle a day seeded from the local date, started when the palette opens on a new day. Once it is over, N starts a practice game on a random word; with daily off every game is one and ⌘N starts another mid-game.
• Hard mode (hard_mode): greens stay in place, ambers must be used; a slip is named in the badge. A game keeps the mode it started with.
• The result view: the praise or the answer, played, win %, streak and best, the guess distribution as bars; C (or Enter) copies the emoji grid with the puzzle number and the score.
• Escape leaves at any point; the game and the stats persist (in the extension's storage).

The word lists ship with the extension, built from public domain sources (12dicts and ENABLE; the README says how): 2551 answers, 8878 allowed guesses, 69 KB in all. Nothing is fetched.

[extensions.wordle]
daily = true
hard_mode = false

Minesweeper (minesweeper)

The mine-clearing game in the panel, by mouse or one hand on the keys. Enter on the palette's row (or its hotkey) opens the board as a view level whose body is the extension's own page (a surface): the search input gives way to the game's line ("7 mines left", "Cleared in 1:11"), ⌘K lists the moves.

• Moving: the arrows or hjkl move the cursor (the ringed cell).
• Opening: Enter or a click. The first open is always safe (the mines are laid after it, never on it or around it) and opens an area; an empty cell floods open. Enter or a click on a number whose flags are all placed opens around it (the chord, "open around" in the hint line); both buttons or the middle one do the same. A held button shows the cells it would open pressed.
• Flagging: /, F or Space, or a right-click; the counter is the mines less the flags.
• The end: won when every safe cell is open (the mines left are flagged), lost on a mine, which goes off red among the rest; a wrong flag is crossed out. Enter or the face starts a new game; N does at any time, asking first mid-game.
• The level: D opens the picker (left, right, Enter), or click a level; it writes the difficulty setting.
• One-handed: the arrows, Enter and / (just above the arrows) play a whole game.
• Escape leaves at any point; the board, the clock, the best time and the won count per level persist (in the extension's storage).

The clock starts on the first open and counts only while the board is on screen: leaving the view pauses it, coming back resumes it, and a run pal never ended (a quit, a crash) is cut off at the last move; T (or clock = false) hides it while it keeps counting. The board is the classic one redrawn: square raised cells that press flat, the classic number colours tuned per theme, an LED counter and clock around the face. An open lifts the caps ring by ring from the cell opened; a mine goes off with a blast before the rest pop out; a cleared board plants its flags under confetti. The cells scale to the page, so the 30 by 16 expert board fits the compact panel.

[extensions.minesweeper]
difficulty = "beginner"       # intermediate (16x16, 40), expert (30x16, 99); from the next board; D on the board too
clock = true                  # false hides the running time while you play (times still count); also T

Snake II (snake)

Snake II as the Nokia 3310 plays it, on the phone's own 84 by 48 screen. Enter on the palette's row opens it as a view level whose body is the extension's own page (a surface): the SNAKE II splash, then the phone's menu (New game, Level, Mazes, Top score, Instructions), lit green, and the game unlit, as the phone keeps its backlight. Every screen, sprite, maze, rule, delay and tone comes from the real 3310 firmware (v6.07) run in an emulator, and the tests replay 123 runs recorded from it frame by frame. The panel's title line keeps the top score in view ("Top score 213"), so it reads without the phone's Top score screen. That and a turn queue (queue_turns, on: a second turn pressed within one step waits for the next instead of being lost as on the phone) are pal's additions; the README lists every one under "Not the phone".

• Steering: the arrows are the phone's 2 4 6 8 while playing; the digits, * and # are the keypad (1 3 7 9 turn across the way the snake goes, * and # turn left and right). Only the last key before a step counts; a key back the way the snake came is dropped.
• Enter is the phone's left soft key (Menu, Select, OK, More), Backspace its C; in a menu the up and down arrows are its scroll keys (Page Up and Page Down anywhere).
• Levels 1 to 9 (656 ms a step down to 88 ms), No maze and Mazes 1 to 5, food worth the level, a bonus creature after every fifth food with its countdown from 20, worth 5 x level + 5 + 2 x the countdown.
• A step into a wall or the body waits about 100 ms and tries again with any turn pressed meanwhile: a late turn still saves the snake.
• Game over blinks the snake, then the score; a new top score gets the fireworks and the jingle.
• C or Menu in play pauses (Continue first in the menu); Escape and the panel hiding pause too, and Continue is there next time, across restarts. C on the Snake II menu, or a digit on any of its screens (the phone's dialer), leaves the game and closes the view.
• The level, the maze, the top score, a paused game and the phone's random numbers persist in the extension's storage; the numbers start again from 1 when pal starts (the phone's power-on), so the first food after it is where the phone puts it.

[extensions.snake]
tones = true                  # the buzzer: eating, a crash, the top score's jingle; cmd+T on the game

Solitaire (solitaire)

Klondike in the panel, by mouse or one-handed on the arrows and Enter. Enter on the palette's row (or its hotkey) opens the table as a view level whose body is the extension's own page (a surface): a felt with real cards, as large as the panel allows. The search input gives way to what the cursor is on ("Pile 4 · 9♣ 8♥"), what you carry ("Moving 7♥ and 2 more") or why a move was refused ("7♥ can't go on 9♠"); ⌘K lists draw, undo, finish and new game.

• The mouse: drag a card (and the cards under it) onto a pile; the piles it can go on light up, a drop anywhere else glides it back. Or click the cards, then the pile; a double-click sends a card where it goes, a click on the stock draws.
• The cursor: ← → walk the stock, the waste, the foundations and the seven piles (wrapping; h l too); on a pile ↑ ↓ take more or fewer cards of its face-up run, and past it move to the row above or below (k j too).
• Enter picks up what the cursor's ring holds; the cards ride on the pile under the cursor, and Enter drops them where it is. An illegal drop puts them back with the reason. Enter again on the pile they came from sends them where they go: the card's foundation, else the first pile that takes them. Any foundation takes a card onto its own suit's.
• Enter on the stock, or space (d) anywhere, turns one card (three with draw = "3") onto the waste, and the waste back over once the stock is out; passes are unlimited. U or Backspace undoes (a hundred moves back, the turned-over card too), or puts down the cards held.
• Once the stock and the waste are played out and every card is face up, the rest flies home one card at a time (Enter finishes at once), and a win bounces the cards off the foundations. N deals a new game, asking first mid-game.
• Escape leaves at any point; the game, the moves, the time and the record (games won of played) persist (in the extension's storage). The time counts only while the table is open; T (or clock = false) hides it from beside the table, and the win still says how long it took.

Every card glides to where it goes and turns over with a flip, the deal goes out row by row from the stock, and a column fans out while it has room and tightens as it grows, never past where a card's rank shows.

[extensions.solitaire]
draw = "1"                    # or "3"
clock = true                  # false hides the running time while you play; also T

Vortex (vortex)

Turn round the centre and slip through the gaps as walls close in on the beat, in the manner of Super Hexagon. Enter on the palette's row opens it as a view level whose body is the extension's own page (a surface), drawn in WebGL2 with its own synthesised music. The design, and why each part is there, is vortex/DESIGN.md.

• ← → (or A D) turn; Shift turns slowly. Turning into a wall's side stops you against it; a wall reaching you ends the run.
• Ranks at 10, 20, 30, 45 and 60 seconds; a minute clears a stage and opens the next and the stage's hyper. Six stages, each with its own song, colours, camera and patterns; the walls land on the song's beat.
• A stage is a chart, the same walls every run, written to its song; Endless runs every stage in turn with new walls each time, and the daily has the same walls for everyone all day (both open once Pulse is cleared).
• On the stages, ← → choose, ↑ picks a cleared stage's hyper, P practises from a rank you reached, C opens your look (shapes and trails opened by medals, the ghost on or off), space plays. After a death (and its slow replay), space is the next run and Backspace the stages; M turns the sound off.
• Escape (or closing pal) pauses a run; space carries on. Each board's best, tries and time persist in the extension's storage. One setting, volume.

Yahtzee (yahtzee)

Solo Yahtzee: five dice, three rolls a round, thirteen rounds. Enter on the palette's row (or its hotkey) opens the game as a view level whose body is the extension's own page (a surface): the dice on a tray with Roll beside them, the scorecard under them in two columns and the total at the bottom, all of it in view at once, compact included. The title line says the round and the roll ("Round 4 · Roll 2 of 3", "Choose a category"); ⌘K lists Roll and every category the dice may go in, the one that adds most first.

• Every open category shows what it would score with the dice as they lie. A picked row (hover, or the keys) rings the dice it counts, shows on the total what it would add (bonuses included) and, for an upper box, its share of the bar to 63.
• The keys, one hand: space (or R, or ↑ on the dice) rolls; ← → pick a die and Enter holds it (1 to 5 hold directly); ↓ goes to the card, on the category that adds most, where the arrows move between the open ones (↑ past the top is back to the dice) and Enter scores. After the third roll the cursor is on the card by itself. N starts a new game, asking first mid-game.
• The mouse: click a die to hold it, Roll to roll, a row to score it.
• The dice tumble when thrown (held ones stay put), a score drops into its row while the total counts up, a Yahtzee gets a banner and confetti, and game over shows the final score with the best and the average.
• Escape leaves at any point; the game and the record (games, best, average) persist in the extension's storage.

Rules (Hasbro's): 35 for 63 or more in the upper section; a further Yahtzee pays 100 while the Yahtzee box holds 50, and plays as a Joker: its number's upper box if open, else any open lower box (a full house and the straights at full value), else an upper box for 0. No settings.

Typing (typing)

A typing test in the manner of monkeytype. Enter on the palette's row opens it as a view level whose body is the extension's own page (a surface): the options on a bar at the top, three lines of common English words, a caret that glides from letter to letter. The title line names the test ("Typing · time 30"); ⌘K lists a new test, every length and mode, and the toggles.

• Time (15, 30, 60, 120 seconds), words (10, 25, 50, 100) or zen (type anything, Enter ends it), with punctuation and numbers on top; picked on the bar, with the arrows before the first key, or from ⌘K.
• Settings (also switched from ⌘K): pace_caret (off, pb, average, last), a fainter second caret gliding at that speed to race; stop_on_error (off, letter, word), which refuses a wrong letter, or a space out of a wrong word; clock (on by default; ⌘T), the seconds left in a time test or so far in zen, which off hides (the test still ends on time, the result says how long it took).
• The clock starts on the first key. Right letters turn full colour, wrong ones red, extra ones trail, a word left wrong is underlined; Backspace goes back into a word only if it was left wrong (alt+backspace takes the whole word).
• The result: wpm, accuracy, raw speed, consistency, the letters right, wrong, extra and missed, and a chart of the test second by second; a new personal best for that kind of test is marked, else the best and the average of the last ten. Under 75% accuracy a test is not counted.
• Stats and history (the stats button on the bar, S on the result, or ⌘K): all tests or one kind, the totals and averages, a progress chart with the average of ten, the bests for every length and the table of past tests.
• Tab starts a new test at any point, R on the result repeats the same words. Escape leaves (a test in progress is dropped); the options and the records persist in the extension's storage.

Crossword (crossword)

Daily crosswords: Crosshare's English minis (crosshare.org), in the manner of the NYT Mini, and the Turkish papers' kare bulmaca (HaberTürk, Cumhuriyet, Sabah). Enter on the palette's row opens a view level whose body is the extension's own page (a surface): the grid, as large as the panel allows; the puzzle's title and its constructor or paper (a link to it on their site), the clock, the clue you are on in a bar of its own, and the Across and Down lists. The title line says which puzzle it is ("Crossword · Today's mini", "Crossword · HaberTürk, today").

• Sources. Crosshare: its daily minis back to 2020 and its newest minis. HaberTürk: one 8 by 8 a day since November 2017. Cumhuriyet: a 17 by 11 with a photo the clues point at (a click shows it large), since February 2026. Sabah: 9 by 9s from an archive that stopped in April 2025. Each is fetched only when played or listed and kept; nothing of theirs ships with pal. The papers' days are Istanbul's.
• Which puzzle. The first open is the puzzle left half-done, else today's of the source setting. Next (⌘N, or Enter on the finish) stays with the source: today's while it is open, then back through its days (for Crosshare, its newest minis too); a puzzle solved or started is skipped, and so are Crosshare's grids bigger than 7 by 7. The next one is fetched while you solve, so it opens at once. Browse (⌘O) has In progress first, every half-done puzzle from any source, the last played on top; then a tab per source: a calendar month by month, each day marked solved, started or new, and Crosshare's newest minis as a list; Enter plays (a half-done one where it was left).
• The keys are the NYT's: a letter fills the square and moves to the next empty one in the word (a full word typed over goes square by square; a finished word jumps to the next clue with a gap); Backspace clears the square, or steps back and clears; an arrow along the word moves (over blocks), across it turns first; Space or a click on the square turns; Tab and Shift-Tab (and Enter) walk the clues, skipping full ones; a click on a square or a clue goes there. ? shows every key.
• Turkish letters. A Turkish puzzle takes i as İ and ı as I, and a letter counts with its diacritics folded (S for Ş, C for Ç), as the papers' own players check: their grids cross Ç with C. A US keyboard solves one with plain letters, each shown as the answer's own once it matches (c typed where Ç goes shows Ç).
• Help. Check (⌘E the word, ⌘⌥E the square, ⌘G the grid, or Enter on "Not quite") slashes wrong letters and turns right ones blue (they lock); reveal (⌘U, ⌘⌥U, ⌘⇧U, the grid asking first) fills in the answer with a corner mark; ⌥⌫ clears the word, ⌘⌥⌫ the grid. autocheck marks a wrong letter as it is typed. A reveal makes the solve "finished with help": it counts, but not for the best time or the streak.
• A wide grid (Cumhuriyet's) puts the clue across the top and the lists beside the grid; in the compact panel the lists give way, and ⌘L lays every clue over the grid.
• The clock runs only while the grid is on screen: it stops when the panel hides, on the other screens and while paused (⌘P, or a click on the clock), which covers the grid. ⌘T (or ⌘K, or clock = false) hides it, pause button and all, for anyone a ticking time rushes; the time still counts for the stats and shows on the finish.
• The finish. A full grid with a mistake says "Not quite" without saying where. Solved, a wave of light runs across the grid, and the time shows with a new best or the streak, the constructor's note if there is one, and Next puzzle.
• Stats (⌘S), per source: solved, best and average time, the streak (the source's daily solved on its own day, on the source's calendar) and the best one, a chart of recent times, the history.
• Every key is saved as you type (progress.json in ~/Library/Application Support/pal/crossword/, ~/.local/share/pal/crossword/ on Linux), so Escape at any point loses nothing. A puzzle once opened plays offline; offline, the page says so and lists them.
• While today's puzzle of the source setting is unsolved, a quiet row in the root's Now section opens it, once you have solved a puzzle before (suggest).

[extensions.crossword]
source = "crosshare"   # what the first open and the Now row offer: haberturk, cumhuriyet, sabah
autocheck = false      # mark a wrong letter as it is typed; also on ⌘K
clock = true           # false hides the running time while you play (times still count); also ⌘T
suggest = true         # today's puzzle in the root's Now section while unsolved

Sudoku (sudoku)

Sudoku made on your machine, never fetched. Enter on the palette's row opens a view level whose body is the extension's own page (a surface): the board on the left, as tall as the panel allows; beside it a slim side: the difficulty and the clock, a line filling as the cells do, a number pad of slim keys (a bar under each digit for how many are down, dimmed with a check once all nine are), and one row of tools: Undo, Erase, Notes, Auto notes, Digit first and Hint. The title line says which puzzle it is ("Sudoku · Hard, today's").

• Which puzzle. A daily for each of Easy, Medium, Hard and Expert, made from the date, so it is the same on every machine that day, and a new puzzle of any difficulty whenever you like. The first open is the game left half-done, else today's daily of the difficulty setting. ⌘N opens a menu of the four: today's puzzle (Play, Carry on or Done) or a new one. Browse (⌘O) has every half-done game (Enter carries on) and a calendar of each difficulty's dailies, month by month, marked solved, started or new.
• The grades come from solving the puzzle the way a person would, the simplest technique first, and taking the hardest one it needed: Easy is singles you can spot without notes, Medium needs a cell with only one digit left, Hard needs locked candidates or a pair or triple, Expert an X-wing, a swordfish or an XY-wing (and a few such steps). Every puzzle has one answer.
• Keys. 1 to 9 place a digit. A different digit typed over one you placed turns the cell into notes holding both, and from then on digits toggle notes there until Backspace clears the cell (changing your mind never loses the first guess; Backspace then the digit replaces it). With check = "mistakes" the answer is no secret, so a wrong digit is simply replaced and a right one stays. Shift or Option with a digit writes a note, and N (or Space) switches digits to notes, where the modifier places. Notes sit in a 3 by 3 inside the cell; a placed digit clears its note from every cell it sees. A fills in every note (notes you wrote are only trimmed, so your own eliminations stay), Shift-A clears them. Backspace or 0 erases, U or ⌘Z undoes, Shift-U or ⌘⇧Z redoes, the arrows or hjkl move, Tab goes to the next empty cell. ? shows every key, and a newcomer (fewer than three solves) gets one line about the second digit until a few digits are down.
• The pad (the mouse): a click places the digit on the cursor's cell (a note in notes mode); a right-click or ⌥-click writes the note instead, and so does each key's small corner, which lights when the cursor's cell has that note.
• Auto notes (C, or auto_notes = true): every empty cell shows the digits that still fit, updated as you play; you only take notes out (Shift with a digit, the corner), and what you take out stays out as the board changes. Backspace on an empty cell brings its notes back, and turning auto notes off brings back your own notes as they were.
• Digit first (D): pick a digit (1 to 9 or the pad) and every cell it can still go in is lit; a click places it (a note in notes mode), a click on it takes it out again, a click on another digit picks that one. Enter places it on the cursor's cell, Tab goes to the next lit cell, and once all nine are in it moves on to the next digit. D again leaves (Escape stays the panel's: it closes the game).
• Clarity. Clues solid, your digits in the accent colour. The cursor's row, column and box are lit, every copy of its digit is lit and that digit's notes are circled across the board. A digit twice in a row, column or box gets a red line under it, with the clue it runs into ringed; with check = "mistakes" any digit that is not the answer shows in red, and the mistakes are counted.
• Hints (I) come in three presses: where to look ("Look at row 4"), then why, in plain words, with the digit ("Only this cell in the top box can take a 9: every other empty cell sees a 9 already", the 9s circled), then the move (the digit placed, a wrong digit erased, or the marks updated). A wrong digit is always the first hint.
• The clock runs only while the board is on screen: it stops when the panel hides, on the other screens and while paused (P or ⌘P), which covers the board. T (or ⌘K, or clock = false) hides it, pause button and all, for anyone a ticking time rushes; the time still counts for the stats and shows on the finish.
• The finish. A completed row, column or box sweeps with light; a digit's ninth copy makes all nine pulse; the solved board ripples out from the last digit under confetti, with the time, a new best, the streak, Flawless (no hint, no mistake), and today's next daily or a new puzzle on Enter.
• Stats (⌘S), per difficulty: solved, best and average time (solves without a hint), the streak (that difficulty's daily solved on its own day, local time) and the best one, a chart of recent times, the history.
• Every move is saved (progress.json in ~/Library/Application Support/pal/sudoku/, ~/.local/share/pal/sudoku/ on Linux), so Escape at any point loses nothing.

[extensions.sudoku]
difficulty = "medium"   # whose daily the first open shows: easy, medium, hard, expert
check = "conflicts"     # or "mistakes": mark a digit that is not the answer as you place it; also on ⌘K
clock = true            # false hides the running time while you play (times still count); also T
auto_notes = false      # true keeps every empty cell's notes filled in; you only take them out; also C

Slack (slack-unreads, slack-channels, slack-search, slack-status)

One extension, four palettes and a bar item (multi: a second workspace is [instances."slack@work"], its workspace set for that instance, Config), signed in through the Slack desktop app's own session (or a user token).

Signing in. auth = "app" (the default) reads the desktop app's session: the xoxc- token per workspace out of its Local Storage (a LevelDB: the SSTables and the write-ahead log are parsed, both copied first) and the d cookie out of its cookie jar (AES-128-CBC under the "Slack Safe Storage" password from the login keychain, or the Secret Service / "peanuts" on Linux). Read-only, kept in memory, extracted again once when Slack answers invalid_auth. It is the only way to client.counts, the client call that answers every unread at once; the public API has no unread endpoint. auth = "token" sends a user token (xoxp-) as a bearer and falls back to conversations.info per conversation: direct messages and unread channels, no mention counts, no threads. Without either, one hint row per palette; Enter opens the extension's settings.

Unreads. Addressed versus merely unread: direct messages, mentions (@you, @here, @channel) and replies in followed threads are the rows and the count; channels that are only unread are named last, no count, their topic or purpose as the subtitle (else "New messages": no run is fetched for them). Sections Direct messages, Mentions, Threads, Channels, newest first in each. The row: the conversation's name, the sender's avatar, the message (in a channel the one naming you, not the last), a count badge (red; blue for thread replies; 1+ past a page), a presence dot on a direct message (green active, grey away; users.getPresence per person, a minute; the presence setting turns it off), the time. The pane is the unread run, oldest first, up to eight messages. One client.counts per refresh; conversations.history only for an addressed conversation, the newest twelve, once per change of its latest; the inbox is shared with the bar item for 30 s.

Channels. Every channel, private channel, group message and direct message you are in (users.conversations, an hour), channels first then by name, with the topic or purpose, the member count and a tag for private, group, DM. Actions: Open in Slack, Open in browser (⌘⇧O), Copy link (⌘C).

Search Slack. search.messages with the query as typed, Slack's syntax through (from:@name, in:#channel, has:link, before:yesterday), newest first; rows are the message, who said it where, the time. A keystroke waits 300 ms for the next. A hit shows once its names are resolved, in Slack's order: while a sender the directory lacks is asked for, the hits above it are already up. Actions: Open in Slack (at the message), Open in browser (the permalink), Copy text.

Status. What is set now first (the status with its expiry, Do Not Disturb, presence; Enter clears, ends, flips), then the statuses presets (:emoji: text (expiry), common Slack shortcodes drawn as the emoji), Do Not Disturb for 30 minutes, an hour, until tomorrow, and Set away / Set active. users.profile.set, dnd.setSnooze / endSnooze, users.setPresence; every pick keeps the palette open with a toast.

The bar item slack/unreads: the count of what is addressed (DMs + mentions + thread replies) as the badge, hidden at zero, urgent while a direct message waits (its dm rule); every refresh seconds and on show, wake, network. The popover is a view: a section per kind with the newest rows (avatars with a direct message's presence dot, the latest line, a count badge; Enter opens one), the quiet channels as badges, a reply field on r, mark read on m, all read on a, the palette on p. A failed refresh leaves it stale; not signed in hides it.

Popover keys of slack/unreads (rendered every 120 s and on show, wake, network; the arrows move the cursor, a click sets it):

Settings, [extensions.slack]:

unreads item settings, [bar.items."slack/unreads".settings]:

For the tests, PAL_SLACK_API replaces the API host, PAL_SLACK_APP_DIR the app's directory and PAL_SLACK_TOKEN the token setting.

Menu Bar Items (menu-bar)

The menus of the app in front as one list, Raycast's Search Menu Bar Items: every enabled item with the menus above it as the subtitle ("File

Export"), its shortcut as key caps, a check mark when it is on, the app's icon on every row, a section per top menu in menu order. Live, so the menus are read again every time the panel shows (pal's panel never takes the app's place, so the app behind it is the one read) and the rows are root results: export pdf at the root finds Preview's item without opening the palette; the whole path is searched (the segments are keywords, and so is the app's name).

Enter presses the item: pal hides first and waits a few frames for key focus to return to the app, so an item that opens a sheet or a dialog lands there, then presses the very element it listed through Accessibility (AXPress); the HUD names the app and the path ("TextEdit: File > Export as PDF…"), or says why the press failed. A pick more than two seconds after the listing, or of an id it does not have (pal run 'menu-bar/menu-bar/File > New', an item hotkey, the app in front changed since), reads the menus once more first, so the press lands in the app in front now and item_hotkeys on a menu item work as long as its path is stable.

What is left out: separators and disabled items (what the app would not let you click now), the Apple menu (the System palette has what matters there), submenus deeper than four levels (File > Export > As > PDF is the deepest listed) and whatever was not reached within 150 ms of reading. The walk is one round trip to the app's main thread per item (seven attributes in one AXUIElementCopyMultipleAttributeValues) plus one per submenu, so a warm app is fast: Finder 40 items in 18 ms, kitty 54 in 7 ms, TextEdit with a document 144 in 11 ms, Chrome 271 in 81 ms (deep bookmark folders cut). An app answers slowly for a moment right after it comes to the front (TextEdit just activated: 22 items in 188 ms; a second later 144 in 11 ms), so a walk the budget cuts short is answered with the last fuller listing of the same app when there is one, and pressing checks the item is still enabled.

• macOS: needs the Accessibility permission (the menus are read through the app's AXMenuBar); without it the one row says so and Enter on it opens System Settings on the pane. Fn (Globe) shortcuts have no Accessibility bit: a bare letter with the "no command" flag is drawn as fn F, which is what Enter Full Screen carries.
• Linux: not available; no desktop exposes an app's menus to read. The one row says so.

No settings.

Generate (generate)

Identifiers, secrets, random values, hashes, encodings, lorem ipsum, a random colour, a QR code and a JWT taken apart, from generate/. An input palette: the rows come from what is typed, and every value copies on Enter, pastes on ⌘Enter; ⌘R (Refresh) lists again with fresh values, which is how a value is regenerated.

The empty query lists one fresh value of every generator: UUID v4, UUID v7 (time-ordered), ULID, Nano ID, a password (password_length characters from password_charset, the strength as a tag on the right: bits of entropy, weak under 36, fair under 60, good under 80, strong under 128), a passphrase (passphrase_words words from a list of 2551 common five-letter words, about 11 bits each), a random number (1 to 100), 16 random bytes as hex and as base64, a lorem ipsum paragraph, a random colour (the swatch as its icon, ⌘O opens it in the Colour Picker). A mode word narrows and parameterises: password 32 alnum, passphrase 7, number 1-6 (or dice), hex 32, bytes 32, lorem 3 paragraphs, colour (five). Anything else filters the generators by name and keyword.

A transform mode works on the text after it, or on the newest clipboard text when nothing follows (the subtitle says which): sha256, md5, sha1, sha512, hash (all four, ⌘⇧C copies them as lines), base64, b64url, url, hex (each decoding first when the text is already that), encode (every form), decode (whatever the text turns out to be: base64, URL escapes, hex, a JWT). qr <text> is one row wearing the code as its icon, drawn large in the detail pane; Enter shows it full width, ⌘C copies the SVG. The encoder is the extension's own (qr.ts, byte mode, versions 1 to 40, after Nayuki's qrcodegen). jwt <token> is the header, the payload with its expiry as a tag, a row per time claim (exp, iat, nbf) as a date with the relative time, and a reminder row: the signature is never verified.

Settings, [extensions.generate]:

Shortcuts (shortcuts)

Every shortcut from the Shortcuts app, from shortcuts/, over the shortcuts command line tool (macOS 12 and later): indexed and primary, so a shortcut's name at the root finds it; the folder is the section inside the palette and a keyword. Enter runs the shortcut and the panel hides; when the run ends, however long it took, the HUD shows <name>: Done, the first line of what the shortcut output, or the tool's message when it failed. ⌘Enter runs it with the newest clipboard text as its input (a temporary file handed to shortcuts run -i), ⌘T asks for the input in a form, ⌘O opens the shortcut in the Shortcuts app, ⌘C copies its name. The listing is kept five minutes (ttl); ⌘R lists again now.

A global hotkey per shortcut is [palettes.shortcuts.item_hotkeys] with the shortcut's name as the key ("Lights On" = "ctrl+alt+l"); a second shortcut of the same name has <name> (<identifier>) as its id. The Shortcuts database is behind macOS's privacy guard and the tool does not expose a shortcut's icon or colour, so every row wears the palette's mark. On Linux, or a Mac without the tool, the palette is one row saying so.

Script Commands (scripts-commands)

Part of the scripts extension: every executable file in the commands folder (~/.config/pal/commands by default, watched) whose header has a # @pal.title line is one row. The header says the mode (hud, the default: the HUD shows the first output line; silent; show: the whole output as a level; list: the output's JSON lines as rows, a row with url opening, one with copy copying, any other running the script again with PAL_PICK; inline: the first output line as the row's subtitle, refreshed every @pal.refresh), the arguments (@pal.args, a form on Enter), @pal.confirm, @pal.keyword, @pal.section, @pal.cwd and @pal.icon (an emoji, a glyph, a hex, a brand colour, an image next to the script, a url). Raycast's @raycast.* headers are read as aliases, so a Raycast script command drops in unchanged. The row's id is the file name, the key for [palettes.scripts-commands.item_hotkeys]. The whole format is in Scripts and data files; two examples are under examples/commands/.

tela (tela-search, tela-research, tela-pages, tela-spaces, tela-new-page, tela-decks, tela-sheets, tela-comments, tela-backlinks)

One extension, nine palettes and a bar item over a tela instance, signed in with a personal access token. Everything goes to the instance's own API: the REST routes for lists, pages, search and writes, and /api/mcp (what tela's tela-mcp package proxies to) for research.

Signing in. base_url is the instance, token a personal access token from Settings, API Keys on tela (tela_pat_..., kept in the keychain). A read token lists, searches and researches; a page, a comment and marking read need write scope. Without either setting every palette is one hint row naming which; a 401 is one naming the renewal, Enter on tela's API Keys page.

Search tela. Ranked full-text over titles and bodies (a phrase in quotes, -word excluded), 250 ms after the last keystroke; rows by space with the breadcrumb and the matching passage, a public-only hit tagged; the pane is the page. Ask tela. tela's research: a numbered grounding, the cited sources, disagreements, a low-confidence flag. Enter on the question opens the answer as a view: the flags on top, the sources as numbered rows, the selected one's excerpt rendered under its row. ↓/j, ↑/k, a digit select; Enter opens the source, ⌘Enter reads it in pal, ⌘C its link, ⌘⇧C the grounding, ⌘⇧O the question on tela's Ask page, + twice the sources when truncated, n a new question in the search row. Twelve questions are remembered; ⌘⇧D forgets one.

Pages. At the root four commands (New tela page, Search tela, Ask tela, Quick Notes), favourites, then the pages that changed lately by space with who changed them; from Spaces, one space's tree by top-level page. On every page row: Open (Enter), Read in pal (⌘Enter, the markdown drawn as a view: headings, lists, callouts as tinted cards, code and quotes on sunken wells, tables as aligned columns, links under their paragraph; bold and code inside a paragraph are flattened, the view's text is one run), Copy link (⌘C), Outline (⌘⇧O), Backlinks (⌘B), Comment (⌘⇧M, anchored on a run of the page's text). Spaces: every space with its page count, tags for public, personal and the default; ⌘Enter opens it, ⌘N starts a page in it. New Page: a form whose body starts as the front app's selection, else the clipboard's text. Decks and Sheets: the flagged pages across every space, newest first; a deck's pane leads with its first slide. Comments: mentions and replies to your comments, unread first; Enter marks read and opens, ⌘⇧R marks read, ⌘⇧A marks all. Backlinks: what links to the page opened last, or to the row ⌘B came from.

The bar item tela/inbox: unread mentions and replies as the badge, hidden at zero; every 300 s and on show, wake, network. The popover: every one as a row (it scrolls), Open in pal, Mark all read.

Not there: a daily page (tela has none; Quick Notes stands in), an append or any edit of a page's body (that is tela's MCP, not a launcher's job), a space filter on Search (the REST search takes none), an LLM answer (that is tela's Ask page, ⌘⇧O).

Settings, [extensions.tela]:

For the tests, PAL_TELA_URL and PAL_TELA_TOKEN replace the two settings.

Apple TV (appletv-remote, appletv-now, appletv-play, appletv-apps, appletv-commands, appletv-users, appletv-setup, appletv/playing)

An Apple TV on the same network, spoken to directly over the two protocols the iPhone's remote uses: Companion for the buttons, swipes, apps, users, sleep and wake, the volume and the text field, and MRP over AirPlay for what plays. No hub, no Home Assistant. One connection to the current Apple TV (the device setting) is opened on first use; everything the TV tells (a new item, a pause, sleep, a keyboard on screen) pushes into the open remote and the bar item, so nothing polls. The extension's README (appletv/README.md) has the protocols, the pairing and every key.

Set Up Apple TV (appletv-setup, a view) walks Find, Remote, Now playing and Ready: the Apple TVs on the network with their model and tvOS version (a digit pairs one, i takes an address, r looks again), then the four-digit code the TV shows, typed in the search row's field (a wrong one brings a new code), then a second code for what plays (s skips it), then a check of what works read from the TV itself. Until one is paired the other palettes are a single "Set Up Apple TV" row, the remote is a welcome and the bar item is hidden.

Apple TV Remote (appletv-remote, a view): the clickpad on the arrows (each part lights when its key is pressed, and clicks), Enter selects (shift+enter holds), Backspace goes back, h home, tab the app switcher, c Control Center, space play or pause, , and . skip by skip seconds, cmd+left/cmd+right previous and next, - and = the volume, shift and an arrow swipes, p sleep or wake, s the screen saver, u users, d the next paired Apple TV. The card shows what plays with its cover and a seek bar a click moves; the dock (favorites, else the apps opened most) puts apps on the digits; the volume is a slider when the TV set reports it over HDMI-CEC. When the TV shows a keyboard a banner says what for, and t types into it from the search row.

Now Playing on Apple TV (appletv-now, a view; n on the remote) sits what plays on its cover's colour: the cover, the title, the show with its season and episode (or the artist and album), the facts and a line of the synopsis, a position bar split at the chapters, the transport as large buttons with speed, subtitles, audio and like beside them. Left and right scrub (each press moves the target further, faster while held; one seek when the keys rest), Tab cycles a panel: Up Next with pictures, Chapters, Audio, Subtitles, Lyrics, Info.

Play on Apple TV (appletv-play, input, inline at the root on a playable url) sends a link to the TV: a YouTube video at its start time, a Netflix title or an Apple TV+ page. It lists the link just copied, the browser tab in front, the clipboard history's links and what was played before. The tab in front says whether it is playing or paused there, and a YouTube video it is partway through starts on the TV where the tab is (the DevTools probe's position; cmd+enter from the start), leading the list so the same video copied does not start over. Whatever starts on the TV, from any of these, pauses a browser tab playing the same video. A newly copied link is offered by the bar item (90 s), the remote's banner (l) and the empty root's Now section (10 min).

Apple TV Apps (appletv-apps) lists every app with its App Store icon (Apple's own drawn from their marks); Enter opens it on the TV, cmd+enter opens it and shows the remote, cmd+d adds it to the dock or takes it out. Apple TV (appletv-commands, primary) has play or pause, wake, sleep, home, Control Center, the screen saver, skip, next, previous, the volume, Type on Apple TV (Tab, then the text), switch user, switch Apple TV and set up at the root; the empty root's Now section has what plays. Apple TV Users (appletv-users) switches the signed-in user.

The bar item (appletv/playing): the app's icon and what plays, muted while paused, hidden while nothing plays or the TV sleeps (the when setting keeps it while the TV is awake); the popover is the remote. It publishes appletv/power, appletv/playing, appletv/app and appletv/title.

Hue (hue-rooms, hue-lights, hue-scenes, hue-light, hue-setup, hue-sensors, hue-automations, hue-entertainment, hue/home)

Philips Hue over the bridge's CLIP v2 API on the LAN (https, the hue-application-key header), nothing through the Hue cloud beyond one discovery lookup during setup. One GET /clip/v2/resource per bridge reads the home whole; the bridge's event stream (/eventstream/clip/v2) patches it from then on, so every palette below is drawn from memory and follows a change made in the Hue app, on a switch or by an automation without a request. A change from pal is one PUT, applied to the model at once and confirmed by the stream; per resource the newest state goes out no more often than Hue asks (10 a second to a light, 1 a second to a group), so a held arrow key is one command. Several bridges make one home. The extension's README (hue/README.md) has the pairing story, the TLS pinning (Signify's root-bridge CA plus the certificate pinned at pairing; insecure skips it) and every key.

Set up Hue (hue-setup, a view) finds the bridges (the cloud endpoint and mDNS; r scans again, i takes an address typed), asks each its name and id with no key, and 1..9 (or Enter) starts press-link: "Press the round button on the bridge" with a thirty-second countdown while a background task asks the bridge every second; x stops a pairing (or forgets a bridge), b goes back to the bridges, Escape leaves and the panel comes back on its own once the key is in. The key lands in the keychain and the address in the config file through settings.set (Settings › Extensions › Hue shows both); c copies the key once paired. Until a bridge is paired every other palette is one "Set up Hue" row and the bar item is hidden.

Hue Rooms (hue-rooms, live, primary) lists rooms then zones with a tile of the lit lights' colours as stripes (faded by the brightness, an outline when off), the count on and the grouped brightness; Enter toggles the grouped light, ⌘Enter opens the room under the keys, ⌘S its scenes, ⌘L its lights, ⌘⇧C copies the id. Hue Lights (hue-lights, live) is every light under its room's section with its colour as a swatch, the archetype, the kelvin, unreachable, the effect and the brightness; Enter toggles, ⌘Enter opens, ⌘B blinks, ⌘C copies the hex. Hue Scenes (hue-scenes, live, primary) is every scene by room as a five-swatch strip of its palette, tagged active, playing, dynamic or smart; Enter recalls it with the transition, ⌘Enter plays the palette dynamically, ⌘O opens the room. Rooms and scenes are primary at the root: living room and Enter toggles the room, relax and Enter plays the scene.

Hue Light (hue-light, a view, opened from a row) puts a light or a room under the keys: the tile in its colour with the brightness, the brightness bar, the temperature on a warm-to-cool strip with a marker across the light's mirek range, the hue/saturation plane with a marker (the same gradient node as the colour picker), then the presets (Relax, Read, Concentrate, Energize, Bright, Dimmed, Nightlight), the room's scenes as strips, the effects the light supports and the options. ←/→ brightness (5 %, ⇧ 20 %), ↑/↓ cooler/warmer (20 mirek, ⇧ 80), 1..9 and 0, t/space toggle, ⇥ (⇧⇥ back) walks light, colour (the arrows become hue and saturation, clamped into the gamut), presets, scenes, effects (←/→ choose, Enter applies), a this light or the whole room, d the transition (instant, 400 ms, 1 s, 4 s), s scenes, o the room, i blink, c copy, r re-read. The view follows the bridge: a change from a switch or the Hue app reaches it through the event stream while it is open (the tree pushed, view.update), no key needed.

Hue Sensors (hue-sensors, live): motion, temperature, light level (lux), buttons and dials with their last event, contact sensors, by device with the battery on the device's first row (red when low) and when the reading changed; Enter copies the reading, ⌘E enables or disables. Hue Automations (hue-automations, live): the behaviour instances with their script and status; Enter enables or disables. Hue Entertainment (hue-entertainment, live): the areas; Enter starts streaming, ⌘Enter stops.

The bar item (hue/home): the main room's colour as a dot (a PNG; the item's main_room setting, else the room with most lights on) and N on; the popover toggles every room, plays the scenes (the item's scenes, else the main room's), opens pal, turns everything off. Rendered every 60 s and on show, wake and network, pushed on every stream event (at most every 300 ms).

Popover keys of hue/home (rendered every 60 s and on show, wake, network; the arrows move the cursor, a click sets it):

Links: pal://hue/toggle?room=living-room (on=1 sets), pal://hue/scene?name=relax&room=living-room (dynamic=1), pal://hue/off. Ids are slugs (room:living-room, scene:living-room/relax, light:sofa-lamp), so [palettes.hue-rooms.item_hotkeys] with "room:living-room" = "ctrl+alt+l" toggles the room without showing pal.

Settings, [extensions.hue]: