# Tjuvkik documentation Every page of https://github.com/banjo/tjuvkik/tree/main/docs in one file. Each page starts with its path. --- # Tjuvkik docs Hold fn to glance at your agents, pull requests and anything else you plug in. Let go to close it. Settings… (⌘,) in the menu bar menu changes the trigger, the board and the theme for you. It edits `config.jsonc` in place, keeping your comments. 1. [Install](install.md): build, first start, permissions, the 🌐 key. 2. [Config](config.md): `config.jsonc`, theme, trigger and which panels to show. 3. [Panels](panels.md): `panel.jsonc`, a command that fills a tile. 4. [Script output](script-output.md): the JSON a script panel prints. 5. [Notifications](notifications.md): macOS notifications from panels. 6. [Themes](themes.md): colors, blur and corner radius. 7. [Sync and share](sync.md): dotfiles, export and import. 8. [Command line](cli.md): `tjuvkik validate`, `run`, `preview`, `new` and `schema`. Everything lives in `~/.config/tjuvkik/`: ``` config.jsonc theme, trigger and which panels to show panels//panel.jsonc a panel; its command runs in this folder themes/.jsonc your own themes schemas/ written by Tjuvkik, for editor completion ``` --- # Install ```sh scripts/create-cert.sh # once: a self-signed "Tjuvkik Dev" signing certificate scripts/bundle.sh --open # build, sign, install to ~/Applications and start ``` Needs macOS 15 and the Xcode Command Line Tools. It also links the [command line tool](cli.md) to `~/.local/bin/tjuvkik`. Every build is signed with the same certificate, so macOS keeps the permissions across rebuilds. ## Once 1. **Input Monitoring.** Tjuvkik asks on first start. Turn it on in System Settings β†’ Privacy & Security β†’ Input Monitoring. 2. **The 🌐 key.** In System Settings β†’ Keyboard, set "Press 🌐 key to" to "Do nothing". Otherwise a tap switches input source. With fn, macOS may start dictation on a double tap. Change the dictation shortcut in System Settings β†’ Keyboard β†’ Dictation, or use another key. ## Use Hold fn to glance, let go to close. fn with another key (fn+arrows, fn+F-keys) doesn't open it. The glance opens on the screen of the window you're in. No fn key, or using it for something else? Pick right βŒ₯, right ⌘ or a shortcut like βŒƒβŒ₯Space as the [trigger](config.md#trigger). ## First start On first start Tjuvkik writes a default config to `~/.config/tjuvkik/` and opens a short setup, four steps you can each skip: 1. **Trigger:** the key or shortcut, and hold, toggle or double tap. Try it right there. 2. **Panels:** tick [starter panels](panels.md#starter-panels), with a miniature of your board. 3. **Theme:** pick one from previews of your board. 4. **Done:** launch at login, background runs and notifications. Done opens the glance, pinned, until Esc, the trigger, a click outside or switching app. Each step writes to `config.jsonc` straight away, so quitting halfway leaves a working config. "Set Up…" in the menu opens it again. A config folder that's already there, say from your dotfiles, skips it. Next: [Config](config.md). --- # Config The settings window (Settings…, ⌘,) writes this file for you. It changes only the lines it needs to and keeps your comments, and it removes a setting that's back at its default. Anything it doesn't cover stays in the file as you wrote it. `~/.config/tjuvkik/config.jsonc`, with every setting at its default: ```jsonc { "$schema": "./schemas/config.schema.json", "view": "bento", "layout": "framed", "theme": "dark-glass", "trigger": { "key": "fn", "mode": "hold", "holdMs": 250, "closeOnClickOutside": true }, "launchAtLogin": true, "menuBar": null, "pause": { "whenLocked": true, "onLowPower": true }, "panels": [ { "panel": "disk" }, ], } ``` Saved changes apply within a second. Comments and trailing commas are fine. If a change breaks something, Tjuvkik keeps the last working config and lists the errors in the menu bar menu. ## Settings | Key | Default | | |---|---|---| | `view` | `"bento"` | Only `bento` for now. | | `layout` | `"framed"` | Only `framed` for now. | | `theme` | `"dark-glass"` | `dark-glass`, `light-glass`, `dracula`, or a file in `themes/`. Or `{ "light": …, "dark": … }` to follow the system's appearance. See [Themes](themes.md#light-and-dark). | | `trigger` | `{ "key": "fn" }` | What opens the glance. See [Trigger](#trigger). | | `launchAtLogin` | `true` | Start Tjuvkik when you log in. If macOS asks for approval, the menu links to Login Items. | | `menuBar` | none | Tiles from `panels`, by id, to show in the menu bar: `"agents"` or `["agents", "github"]`. | | `pause` | both `true` | When background runs stop. See [Pause](#pause). | | `notifications` | on | Sound, quiet hours and whether to notify while glancing. See [Notifications](#notifications). | | `panels` | `[]` | Which panels to show, in order. | ## Trigger Hold a modifier key on its own: ```jsonc "trigger": { "key": "fn", "holdMs": 250 } ``` Or press a shortcut: ```jsonc "trigger": { "shortcut": "βŒƒβŒ₯Space" } ``` - `key`: `fn`, `rightOption`, `rightCommand`, `rightControl` or `rightShift`. Pressed with another key or modifier, it doesn't open the glance, so fn+arrows and βŒ₯+letters still work. Needs Input Monitoring. - `shortcut`: `"βŒƒβŒ₯Space"`, `"ctrl+option+space"`, `"cmd+shift+g"`. It needs βŒƒ, βŒ₯ or ⌘, except F1–F20, which work alone. Keys are named by their place on a US keyboard. Tjuvkik takes the shortcut from other apps, and needs no permission for it. If another app already has it, the menu says so. - `mode`: `hold` shows the glance while you hold, `toggle` shows it on a tap or press and hides it on the next one or Esc. A key held longer than 400 ms isn't a tap, so using it as a modifier (fn+volume) doesn't toggle. `doubleTap`: two taps of the key, the second within `doubleTapMs`, show the glance; two more or Esc hide it. A single tap does nothing. Keys only. A key holds by default, a shortcut toggles. - `holdMs`: how long to hold before the glance shows, 50–2000. Default 250. Only with `hold`. - `doubleTapMs`: how soon the second tap must follow the first, 150–600. Default 300. Only with `doubleTap`. - `closeOnClickOutside`: a click outside the open glance, or between its tiles, closes it. Default `true`. Or double-tap a key: ```jsonc "trigger": { "key": "rightCommand", "mode": "doubleTap" } ``` With fn, macOS may start dictation on a double tap. Change the dictation shortcut in System Settings β†’ Keyboard β†’ Dictation, or use another key. Set `key` or `shortcut`, not both. Caps Lock can't be a key, since macOS locks it on press. To use it, map it to F18 (with [hidutil](https://developer.apple.com/library/archive/technotes/tn2450/) or Karabiner-Elements) and set `"shortcut": "F18"`. ### Pinning - In `hold` mode, click the glance or press Space while you hold to keep it open after you let go. - `toggle` and `doubleTap` stay open on their own. - Esc, the trigger again, a click outside (unless `closeOnClickOutside` is `false`), or switching Space or app closes it. - With right ⌘, ⌘Space may belong to Spotlight, so click instead. The glance takes clicks whenever it's open, but never takes keyboard focus from the app in front. ### Keyboard While the glance stays open (toggled, or pinned), a row is outlined, and you can use it without the mouse: | Key | | |---|---| | ← β†’ ↑ ↓ | The nearest row in that direction, across tiles. A tile without clickable rows is picked as a whole. | | Enter or Space | What clicking the row does. | | βŒ₯Enter | Open the row's `url`, when it also has a `command`. | | ⌘K | List everything you can do with the row, including its [actions](script-output.md#row-actions). Arrows and Enter pick; Esc closes the list. | | ⌘ and a key | The row's action with that `key`. | | ⌘C | Copy the row's `url`, or its title. | | ⌘R | Run the row's panel now. The glance stays open, so you see the result. | | ⌘O | Open its `panel.jsonc`. | | 1–9 | The first row of that tile, in `panels` order. | A bar under the board shows the keys for the picked row. When the glance opens, the first row picked is an error row, then a warning row, in a tile with `"focus": true`; then one anywhere; then the first row of a `focus` tile; then the first row. The keys are taken from the app in front only while the glance is open. ## Panels ```jsonc "panels": [ { "panel": "agents", "size": "xl" }, { "panel": "github" }, ] ``` - `panel`: a folder in `panels/`. See [Panels](panels.md). - `id`: the tile's name, for `menuBar` and `tjuvkik run`. Letters, digits, `-` and `_`. Default: `panel`. - `title`: the tile's title; overrides the panel's own. Optional. - `options`: values for the [options](panels.md#options) the panel declares. - `size`: overrides the panel's own size. Optional. - `background`: overrides the panel's own, for when it runs while the glance is closed: `true`, `false` or a duration like `"5m"`. See [Background](panels.md#background). - `show`: `false` runs the panel for the menu bar without giving it a spot on the grid. Optional. - `focus`: `true` picks this tile first when you use the keyboard. See [Keyboard](#keyboard). Optional. - `notify`: overrides the panel's own, key by key: `false`, `true` or an object. See [Notifications](notifications.md#a-panels-notify). The same panel can be on the board more than once; give each an `id`: ```jsonc "panels": [ { "panel": "ci", "id": "ci-app", "title": "CI Β· app", "options": { "repo": "banjo/tjuvkik" } }, { "panel": "ci", "id": "ci-dots", "title": "CI Β· dots", "options": { "repo": "banjo/dotfiles", "limit": 5 } }, ] ``` Panels fill a 4Γ—3 grid in order: | Size | Columns Γ— rows | |---|---| | `s` | 1 Γ— 1 | | `m` | 2 Γ— 1 | | `l` | 2 Γ— 2 | | `xl` | 2 Γ— 3 | Panels that don't fit are left out, and the menu says which. ## Pause ```jsonc "pause": { "whenLocked": true, "onLowPower": true } ``` - `whenLocked`: stop background runs while the screen is locked or the displays sleep. - `onLowPower`: stop them while Low Power Mode is on. The glance always runs panels on their `every`, whatever `pause` says. Coming back from a pause runs whatever is overdue, so the first glance after you unlock is never stale. ## Notifications ```jsonc "notifications": { "enabled": true, "sound": true, "quietHours": "22:00-07:00", "whileOpen": false } ``` - `enabled`: `false` turns off notifications from every panel. - `sound`: play the system's notification sound. - `quietHours`: nothing is delivered between these times, local time, like `"22:00-07:00"`. - `whileOpen`: deliver while the glance is showing. Off by default. See [Notifications](notifications.md) for how panels send them. ## Menu bar ```jsonc "menuBar": ["agents", "github"] ``` `menuBar` lists tile ids: an entry's `id`, or its `panel` when it has none. Each panel decides what it shows, with [`menuBar` in its output](script-output.md#menu-bar): an icon and text in the menu bar, like `❓ 2 πŸ‘€ 3`, and its own rows in the menu. When no panel shows anything, the menu bar shows the grid icon. A broken config shows a warning sign. ## Files - `.jsonc` and `.json` both work. If both exist, `.jsonc` wins. - `$schema` gives completion and checks in editors that read it. Tjuvkik keeps `schemas/` up to date. --- # Panels A panel is a folder in `panels/` with a `panel.jsonc`. Add it to `panels` in [config.jsonc](config.md) to show it. A panel placed on the board is a tile. One panel can be placed many times, each tile with its own `id`, title and [options](#options). Right-click a tile in the glance to run it now, open its `panel.jsonc`, show its folder in Finder, or open Settings. `panels//panel.jsonc`, with every setting: ```jsonc { "$schema": "../../schemas/panel.schema.json", "description": "Pull requests waiting for your review", "author": "banjo", "version": "1.0.0", "requires": ["gh", "jq"], "type": "script", "mode": "interval", "title": "GitHub", "command": "./github.sh", "every": "60s", "timeout": "10s", "background": true, "size": "s", } ``` ## Settings | Key | Default | | |---|---|---| | `type` | required | `cli`, `script`, or a [content type](script-output.md) like `chart` or `table`. | | `command` | required, unless `file` | Runs with `/bin/sh -c` in the panel's folder. | | `mode` | `"interval"` | `interval` or `stream`. | | `title` | folder name | Shown on the tile. | | `every` | `"60s"` | How often an interval panel runs. At least `5s`. | | `timeout` | `"10s"` | How long an interval run may take. | | `size` | `"s"` | `s`, `m`, `l` or `xl`. `config.jsonc` can override it. | | `history` | | For a [chart](types/chart.md) whose script prints only its value: how many values to keep as the series, 2 to 1000. | | `file` | | A [markdown](types/markdown.md) panel only: a file to show instead of a command's output, reloaded when it changes. `~`, absolute, or in the panel's folder. | | `requires` | `[]` | Commands that must be on PATH. If one is missing, the tile says so instead of running. | | `background` | `true` | How often an interval panel runs while the glance is closed: `true`, `false` or a duration like `"5m"`, at least `5s`. See [Background](#background). | | `notify` | `true` | `false`, or when and how the panel notifies. See [Notifications](notifications.md#a-panels-notify). | | `options` | | Settings each tile sets in `config.jsonc`. See [Options](#options). | | `description`, `author`, `version` | | For sharing. Not shown. | Durations take `ms`, `s`, `m` or `h`: `"500ms"`, `"30s"`, `"5m"`, `"1h"`. ## Options A panel can take options, so the same panel works for several repos, clusters or hosts without editing its script. The panel declares them in `options`; each tile sets their values in [config.jsonc](config.md#panels). | Key | | |---|---| | `type` | Required: `string`, `number` or `boolean`. | | `title` | A label for forms. Default: the option's name. | | `description` | What it's for. | | `default` | The value when a tile doesn't set it. | | `required` | `true`: every tile of the panel must set it. | | `enum` | The allowed values of a `string` option. | ```jsonc // panels/ci/panel.jsonc: what the panel takes "options": { "repo": { "type": "string", "title": "Repository", "description": "owner/name", "required": true }, "limit": { "type": "number", "default": 10 }, "branch": { "type": "string", "enum": ["main", "release"], "default": "main" }, "drafts": { "type": "boolean", "default": false } } ``` ```jsonc // config.jsonc: what you set "panels": [ { "panel": "ci", "id": "ci-app", "title": "CI Β· app", "options": { "repo": "banjo/tjuvkik" } }, { "panel": "ci", "id": "ci-dots", "title": "CI Β· dots", "options": { "repo": "banjo/dotfiles", "limit": 5 } }, ] ``` The command reads them from the environment, in two ways: - One variable per option, `TJUVKIK_OPTION_`: the name upper-cased, `-` turned into `_`. Numbers print without `.0` when whole (`10`, `2.5`), booleans as `true` or `false`. - All of them as one JSON object, with sorted keys, in `TJUVKIK_OPTIONS`. ```sh gh run list --repo "$TJUVKIK_OPTION_REPO" --limit "$TJUVKIK_OPTION_LIMIT" repo=$(echo "$TJUVKIK_OPTIONS" | jq -r .repo) ``` An option with no value and no default is left out of both. Options are never put into `command`, since `sh -c` would run them. Option names start with a letter, then use letters, digits, `-` and `_`. A tile that sets an option the panel doesn't declare, or leaves out a required one, is an error. ### Secrets Don't put tokens in options: `config.jsonc` often ends up in a dotfiles repo. Read them in the script instead, with `gh auth token`, `security find-generic-password -s -w`, or an environment variable. See [#23](https://github.com/banjo/tjuvkik/issues/23). ## Types - **`cli`** shows the output as is, colors removed, as many lines as fit. - **`script`** prints JSON that the tile shows as rows, or as the type its top-level key names. See [Script output](script-output.md). - **A content type**, like `stats`, is a script panel whose output is always read as that type. ## Modes - **`interval`** runs the command every `every`. - **`stream`** keeps the command running. A script prints one JSON document per line, each time something changes, and the tile updates at once. A cli panel shows the latest lines, like `tail -f`. `every` and `timeout` don't apply. ## Background While the glance is closed, an interval panel runs on its `background`: - `true`, the default: as often as it does while you glance, every `every`. - `false`: only while you glance. Opening the glance runs it at once if it's older than `every`. - A duration like `"5m"`: that often, at least `5s`. Cheap panels, like agents, can keep their interval. One that calls `gh` or `kubectl` is worth `"5m"`, or `false` if you only care when you look. Background runs pause while the screen is locked or the displays sleep, and while Low Power Mode is on, unless [`pause`](config.md#pause) turns that off. The glance always runs panels on their `every`. Stream panels and markdown panels that read a `file` are unaffected: a stream keeps running, and a file is read when it changes. A panel can also run without a spot on the grid, for the menu bar: see [`show`](config.md#panels). ## When a command fails A run fails if it exits with a non-zero status, times out, or a script prints invalid JSON. The tile keeps what it last showed, marks it stale and shows the last lines of stderr. A stream that exits is restarted after 1 second, then after up to 30 seconds if it keeps exiting. `tjuvkik run ` runs a panel once from a terminal, the same way, and prints the error. See [Command line](cli.md). ## Environment Commands get your login shell's PATH, so tools from Homebrew, mise and the like are found. `TJUVKIK_PANEL` is the panel's folder name, `TJUVKIK_ID` the tile's id, and each [option](#options) is a `TJUVKIK_OPTION_`, all of them as JSON in `TJUVKIK_OPTIONS`. `TJUVKIK_RUN` says what started the run: `glance` or `background` for an interval panel, `stream`, `action` for a row's command, or `cli`. ## Examples A cli panel: ```jsonc { "type": "cli", "title": "Pods", "command": "kubectl get pods", "every": "30s", "size": "m" } ``` A log that updates live: ```jsonc { "type": "cli", "mode": "stream", "title": "Server", "command": "tail -f /tmp/server.log", "size": "l" } ``` More in the [starter panels](#starter-panels). ## Starter panels Tjuvkik ships a few panels to start from, in [starters/panels](../starters/panels). Picking one during setup copies its folder into `panels/`, unless a folder with that name is already there, and adds a tile. It's then yours to change. | Folder | Shows | Needs | |---|---|---| | `disk` | disk use (already in the default config) | nothing | | [`cpu-memory`](../starters/panels/cpu-memory) | CPU, memory and load, as `stats` | nothing | | [`battery`](../starters/panels/battery) | battery charge, as `meters` | a Mac with a battery | | [`github`](../starters/panels/github) | PRs waiting for your review, then yours | `gh`, `jq` | | [`demo-agents`](../starters/panels/demo-agents) | **sample** coding agents, as rows | nothing | | [`demo-slack`](../starters/panels/demo-slack) | **sample** Slack mentions, as a `feed` | nothing | The demos show sample data, to show what a panel can look like. --- # Script output A `script` panel prints JSON to stdout. By default the tile shows it as rows. A top-level key picks another type, drawn its own way at each size: - [`chart`](types/chart.md): one number and where it's heading. - [`meters`](types/meters.md): how full, how far, how close to a limit. - [`grid`](types/grid.md): many things at once, a colored cell each, or a heatmap. - [`timeline`](types/timeline.md): what's now, what's next, and how long until. - [`stats`](types/stats.md): a few numbers, each against its last period. - [`markdown`](types/markdown.md): notes, runbooks and answers in Markdown, or a file the panel reads. - [`keyvalue`](types/keyvalue.md): exact facts, grouped, with values cut in the middle. - [`table`](types/table.md): the same fields for every row, in columns. - [`feed`](types/feed.md): who said what, and when, newest first, with unread marked. - [`checklist`](types/checklist.md): steps, and what's done, next and stuck. `summary`, `menuBar` and [`notify`](notifications.md) work with every type. Setting `"type"` in [panel.jsonc](panels.md#types) to a type's name, like `"stats"`, makes the panel always read its output as that type. ## Rows Every field: ```json { "hero": { "value": "2", "label": "reviews requested", "tone": "warning" }, "summary": [ { "icon": "❓", "value": "2", "label": "waiting", "tone": "warning" } ], "progress": 0.62, "rows": [ { "icon": "πŸ‘€", "title": "Export bookings", "subtitle": "logbook #1284", "trailing": "1h", "tone": "warning", "group": "Reviews", "note": "Waiting for approval", "url": "https://github.com/acme/app/pull/1284" } ], "menuBar": { "icon": "πŸ‘€", "text": "2", "tone": "warning", "menu": [ { "icon": "πŸ‘€", "title": "Export bookings", "subtitle": "logbook #1284", "trailing": "1h", "url": "https://github.com/acme/app/pull/1284" } ] } } ``` The smallest valid output: ```json { "rows": [{ "title": "All good" }] } ``` Only `rows`, each row's `title` and the hero's `value` are required. A `stream` panel prints one such document per line. ## Fields | Field | | |---|---| | `hero` | A big number at the top: `value` (required), `label`, `tone`. | | `summary` | A line of small counts. Each has `icon`, `value`, `label` and `tone`, all optional. | | `progress` | A bar, from 0 to 1. | | `rows` | As many as fit, in order. | | `menuBar` | What the panel shows in the menu bar. See [Menu bar](#menu-bar). | | `notify` | macOS notifications, one per `id`. See [Notifications](notifications.md). | Each row: | Field | | |---|---| | `title` | Required. | | `icon` | An emoji or a short text. | | `subtitle` | A second, fainter line. | | `trailing` | On the right, like a time or count. | | `tone` | Colors the row. | | `group` | A heading over each run of rows with the same group. | | `note` | A line under the row in its tone, for what needs you. | | `url` | Opened when the row is clicked in the glance or picked in the menu. Closes the glance. | | `command` | Run when the row is clicked in the glance or picked in the menu, in the panel's folder. Wins over `url`. Closes the glance and runs the panel again, so the tile shows the result next time. | | `actionTitle` | What the glance's hint bar calls a click, like `"Jump to session"`. Default: Run or Open. | | `actions` | More things to do with the row from the keyboard. See [Row actions](#row-actions). | ## Menu bar Shown when the panel is in `menuBar` in [config.jsonc](config.md#menu-bar). | Field | | |---|---| | `icon`, `text` | Shown in the menu bar: `πŸ‘€ 2`. | | `tone` | Colors it. | | `menu` | Rows in the menu, under the panel's title. Same fields as `rows`; `subtitle` and `note` go on a second line. | - Leave `menuBar` out to show the first `summary` chip, with the whole summary in the menu. - Set `"menuBar": null` to show nothing, like when nothing needs you. ## Row actions Rows in rows, table, timeline and feed panels can offer more than a click. With the row picked in the glance, ⌘K lists them, and ⌘ and an action's `key` runs it directly. The hint bar under the board shows the keyed ones. ```json { "title": "feat: export filters", "url": "https://github.com/…/1284", "actionTitle": "Open PR", "actions": [ { "title": "Approve", "command": "gh pr review 1284 --approve", "key": "a" }, { "title": "Check Out", "command": "gh pr checkout 1284" }, { "title": "Copy Branch", "copy": "feat/export-filters" } ] } ``` | Field | | |---|---| | `title` | Required. | | `command` | Run in the panel's folder, like a row's. Wins over `url` and `copy`. | | `url` | Opened. Wins over `copy`. | | `copy` | Put on the clipboard. | | `key` | A letter or digit, used with ⌘. Not `c`, `k`, `o` or `r`, which the glance uses. | Running an action closes the glance. A row's `command` runs like the panel's, with your login shell's PATH. What it starts in the background keeps running, so it can open apps or focus windows. If it fails, the error shows on the tile. ## Tones `normal`, `muted`, `warning`, `error`, `success`, `info` and `accent`. The theme decides the colors. ## Example A script that lists files in Downloads: ```sh #!/bin/sh ls -t ~/Downloads | head -20 | jq -R '{ title: . }' | jq -s '{ rows: . }' ``` --- # Notifications A panel can send a macOS notification when something changes, so you don't have to glance to know. Panels only run while the glance is closed if they run in the [background](panels.md#background), so a panel that notifies needs background runs on. ## From a script A script prints `notify` next to its content, with any [content type](script-output.md): ```json { "rows": [{ "title": "Fix login bug", "tone": "warning" }], "notify": [ { "id": "ses_abc-blocked", "title": "Agent waiting", "body": "Bash: rm -rf node_modules", "command": "agent-watcher focus ses_abc" } ] } ``` | Field | | |---|---| | `id` | Required. Names the notification: one is sent per `id`. | | `title` | Required. | | `subtitle` | A line under the title. | | `body` | The text. | | `url` | Opened when the notification is clicked. | | `command` | Run when the notification is clicked, in the panel's folder, like a menu row's. Wins over `url`. | - A notification is sent the first time its `id` shows up in the panel's output, and withdrawn from Notification Center when the `id` is gone. An `id` that stays shows nothing new. - The first output a panel gives after Tjuvkik starts, or after its config changes, sends nothing: what's already there counts as seen. Only what's new after that is sent. - Clicking runs its `command` or opens its `url`. With neither, it opens the glance, pinned. ## A panel's `notify` In [panel.jsonc](panels.md#settings), or in an entry in [config.jsonc's `panels`](config.md#panels), whose keys win: ```jsonc "notify": false // this panel never notifies "notify": { "sound": false, "minInterval": "1m", "on": ["failed", "warning"] } ``` | Key | Default | | |---|---|---| | `sound` | the global `sound` | Play the system's notification sound. | | `minInterval` | none | At most one notification this often, like `"1m"`, at least `1s`. | | `on` | `[]` | Notifications the script doesn't print. See below. | ### `on` So `cli` panels and scripts that don't print `notify` can notify too: - `"failed"`: while the panel shows an error, like a failed run, a stream that exited or a missing tool. The title is ` failed`, the body the error. It's withdrawn when the error clears. - `"warning"` and `"error"`: each row with that tone, in rows output only. The title is the row's title, the subtitle the panel's title, the body the row's `note`, else its `subtitle`. Clicking does what the row's `url` or `command` does. ### `minInterval` What comes in within the interval waits. When it has passed, one waiting notification is sent as is, and several as one: the panel's title, with `3 new: A, B, C`. A waiting one whose `id` disappears is dropped. ## Global settings In [config.jsonc](config.md#notifications): ```jsonc "notifications": { "enabled": true, "sound": true, "quietHours": "22:00-07:00", "whileOpen": false, } ``` | Key | Default | | |---|---|---| | `enabled` | `true` | `false`: no panel notifies. | | `sound` | `true` | The system's default sound. | | `quietHours` | none | Nothing is delivered between these times, local time. It may cross midnight. | | `whileOpen` | `false` | Deliver while the glance is showing. | In quiet hours, or while the glance is open, new notifications are dropped, not delayed: they count as seen and aren't sent later. Focus modes apply as for any app. ## Permission macOS asks the first time Tjuvkik is about to deliver a notification. If you deny it, the menu says "Notifications are off for Tjuvkik" and links to Notification settings. --- # Themes Pick one in `config.jsonc`: ```jsonc "theme": "dark-glass" // or "light-glass", "dracula", or a file in themes/ ``` ## Light and dark To follow the system's appearance, name one theme for light mode and one for dark. Set both: ```jsonc "theme": { "light": "light-glass", "dark": "dracula" } ``` The glance switches while it's open, when you change System Settings β†’ Appearance. ## Your own `themes/.jsonc` starts from another theme and changes what it sets. Every setting, as in `dark-glass`: ```jsonc { "$schema": "../schemas/theme.schema.json", "extends": "dark-glass", "appearance": "dark", "blur": true, "radius": 16, "panel": "#1e1f298c", "well": "#00000047", "text": "#f8f8f2", "secondaryText": "#f8f8f294", "tertiaryText": "#f8f8f25c", "line": "#ffffff14", "warning": "#ffb86c", "error": "#ff6e6e", "success": "#50fa7b", "info": "#8be9fd", "accent": "#bd93f9", "material": "hud", "font": { "scale": 1 }, "board": { "gap": 10, "inset": 10 }, "tile": { "border": 1, "shadow": true, "padding": 12, "header": { "uppercase": false, "kind": true, "interval": true }, }, } ``` Usually a few lines are enough: ```jsonc { "extends": "dracula", "accent": "#ff79c6", "radius": 14 } ``` Or more than colors: ```jsonc // themes/terminal.jsonc { "extends": "dracula", "radius": 4, "blur": true, "material": "popover", "font": { "family": "Inter", "mono": "JetBrains Mono", "scale": 1.1 }, "board": { "gap": 6, "inset": 12 }, "tile": { "border": 0, "shadow": false, "padding": 10, "header": { "uppercase": true, "kind": false, "interval": false }, }, "tones": { "error": { "background": "#ff55551a" } }, } ``` Then set `"theme": ""` in `config.jsonc`. Every setting is optional, and one a theme doesn't set comes from the theme it extends, key by key: a theme that sets `font.scale` keeps the `font.family` it extends. ## Settings | Key | | |---|---| | `extends` | A built-in theme or another file in `themes/`. Default `dark-glass`. | | `appearance` | `dark` or `light`. | | `blur` | Blur what's behind the tiles. Without it, `panel` is drawn solid. | | `radius` | Tile corner radius, 0–40. | | `material` | The glass behind the tiles, while `blur` is on: `hud` (default), `popover`, `menu`, `sidebar` or `underWindow`. | | `font.family` | The font for text, as Font Book names it. Default: the system font. | | `font.mono` | The font for monospaced text. Default: the system's monospaced font. | | `font.scale` | Multiplies every text size, 0.85–1.25. Default 1. | | `board.gap` | Space between tiles, 0–24. Default 10. The board keeps its size, so the tiles grow or shrink. | | `board.inset` | Space around the tiles, 0–40. Default 10. | | `tile.border` | Width of the tile's outline, 0–4. Default 1; 0 is none. | | `tile.shadow` | A shadow under each tile. Default `true`. | | `tile.padding` | Space inside a tile, 6–20. Default 12. | | `tile.header.uppercase` | Titles in upper case. Default `false`. | | `tile.header.kind` | The type tag, like `table`. Default `true`. | | `tile.header.interval` | How often it runs, like `every 1m` or `live`. Default `true`. `stale` always shows. | | `tones..background` | What's drawn behind pills, highlighted rows and table rows in that tone: `muted`, `warning`, `error`, `success`, `info` or `accent`. Default: the tone's color, faded. | | `panel` | Tile background. | | `well` | Inset backgrounds. | | `text`, `secondaryText`, `tertiaryText` | Text, from strongest to faintest. | | `line` | Borders and dividers. | | `warning`, `error`, `success`, `info`, `accent` | The [tones](script-output.md#tones). `muted` uses `tertiaryText`, and `normal` keeps the default color. | Colors are `#rgb`, `#rrggbb` or `#rrggbbaa`. A font that isn't installed is a warning in the menu, and that text uses the system font. --- # Sync and share ## Dotfiles Keep `~/.config/tjuvkik/` in your dotfiles and link it, with stow or by hand: ```sh ln -s ~/dotfiles/.config/tjuvkik ~/.config/tjuvkik ``` Tjuvkik follows links and reloads when linked files change. Ignore `schemas/`, which Tjuvkik writes itself: ```gitignore .config/tjuvkik/schemas/ ``` Check the folder before committing, or in CI on a Mac: ```sh tjuvkik validate --config ~/dotfiles/.config/tjuvkik ``` It exits 1 on errors. See [Command line](cli.md). ## Export and import From the menu bar menu: - **Export Config…** saves the folder as a zip. - **Import Config…** checks the zip, backs up your current config to `~/Library/Application Support/Tjuvkik/Backups/`, then replaces it. A linked folder stays linked. ## Share a panel A panel is a folder, so copy it into someone's `panels/` and add it to their `config.jsonc`. Fill in `description`, `author`, `version` and `requires` in `panel.jsonc`, so others know what it does and what it needs. --- # Command line `scripts/bundle.sh` links `tjuvkik` into `~/.local/bin`. It's the app's own binary: with a command it runs the command and exits, without one it starts the app. ```sh tjuvkik new prs --type table # make panels/prs/ from a template tjuvkik run prs # run it once and see what the tile shows tjuvkik preview prs # render the tile to prs-m.png tjuvkik validate # check the whole config folder ``` Every command reads `~/.config/tjuvkik/` (or `$XDG_CONFIG_HOME/tjuvkik/`). `--config ` reads another one. ## validate Checks `config.jsonc`, the themes it uses and every panel in `panels/`, including panels that aren't on the board yet. Prints each error and warning with its file and key, then a summary: ``` error: panels/prs/panel.jsonc: every: must be at least 5s, got "1s" βœ— 1 error in config.jsonc and 4 panels ``` Exits 1 on errors, so it works in CI for a dotfiles repo. Warnings don't fail it. ## run ```sh tjuvkik run [--raw] [--option key=value]... ``` Takes a tile's id from `config.jsonc` or a panel's folder name. A tile on the board runs with its [options](panels.md#options); anything else is a panel with its option defaults. `--option key=value` sets an option and wins over both; repeat it for more. ```sh tjuvkik run ci-app # the tile's options tjuvkik run ci --option repo=banjo/tjuvkik # the folder, with an option ``` Runs the panel as the app does: in its folder, with your login shell's `PATH`, with `TJUVKIK_PANEL`, `TJUVKIK_ID`, the option variables and `TJUVKIK_RUN=cli` set and its `timeout`. Then it says what the tile shows, or why it shows an error: ``` prs: table, ran in 0.84s shows table, 4 columns and 8 rows ``` `--raw` prints the command's output as is. A stream panel keeps running and describes each line until Ctrl-C. Exits 1 when the command fails or its output can't be read. ## preview ```sh tjuvkik preview [--size s|m|l|xl] [--theme ] [-o ] [--scale <1-4>] [--option key=value]... ``` ```sh tjuvkik preview ci-dots --option limit=3 ``` Runs the panel and renders its tile to a PNG, at its size on the largest board, with a transparent background. Like `run`, it takes a tile's id or a panel's name, and `--option`. The size defaults to the one `config.jsonc` gives the tile, else the panel's own; the theme to the one in `config.jsonc`, for the current appearance when it names one for light and one for dark. The file defaults to `-.png` in the current folder. Blur isn't rendered, so the tile's background is drawn solid. A failed run renders the tile with its error, and exits 1. ## new ```sh tjuvkik new [--type | --script | --cli] ``` Makes `panels//` with a `panel.jsonc` and a `.sh` that prints an example of the type. The type is `script` (rows, the default), `cli`, or a [content type](types/) like `stats` or `table`. Add the panel to `config.jsonc`'s `panels` to show it. ## schema ```sh tjuvkik schema # list the schemas and where they are tjuvkik schema panel # print one: config, panel or theme ``` --- # Chart One number and where it's heading. ```json { "chart": { "value": "64", "unit": "%", "label": "CPU, all cores", "delta": { "text": "β–² 22 pts in 10m", "tone": "warning" }, "series": [31, 28, 35, 30, 41, 52, 64], "min": 0, "max": 100, "threshold": 80, "axis": ["βˆ’60m", "βˆ’30m", "now"], "tone": "accent" } } ``` | Size | Shows | |---|---| | `s` | The value and change, a sparkline below them. | | `m` | The value, label and change on the left, the chart on the right. | | `l`, `xl` | The value and change, the label, the chart with a grid and the threshold line, the axis labels, then min, avg and max. | ## Fields | Field | | |---|---| | `value` | The current value, as shown: `64`, `"4:12"`. Text or a number. Without it, the last value in `series`. | | `unit` | Smaller, after the value: `%`, `ms`, `GB`. | | `label` | What the number is, like `CPU, all cores`. Shown at `m` and `l`. | | `delta` | The change: `{ "text": "β–² 22 pts in 10m", "tone": "warning" }`, or just the text. Your script picks the tone, since up isn't always good. | | `series` | Numbers, oldest first. Numbers written as text work; `null` is skipped. | | `min`, `max` | The bottom and top of the scale. Without them, the series' lowest and highest value. | | `threshold` | A dashed line at this value, with its label, at `l`. | | `axis` | Labels under the chart at `l`, spread from left to right: `["βˆ’60m", "βˆ’30m", "now"]`. | | `tone` | The line's color: `accent` (default), `info`, `success`, `warning`, `error`, `muted`. | Either `value` or `series` is required. min, avg and max use the value's decimals and its unit: with `"value": "0.4"` and `"unit": "%"`, an average of 0.125 shows as `0.1%`. `summary` and `menuBar` work as for [rows](../script-output.md#menu-bar): they set what the menu bar shows. ## Let Tjuvkik keep the series A script that prints only the current value can leave the series to Tjuvkik. Set `history` in [panel.jsonc](../panels.md) to how many values to keep, from 2 to 1000: ```jsonc { "type": "chart", "command": "./cpu.sh", "every": "1m", "history": 60 } ``` Each run adds its `value` to the series, and the oldest drops off once there are 60. It only works when `value` is a number and the script prints no `series` of its own. The series starts over when Tjuvkik restarts or the panel's command changes. ## Example CPU use on a Mac, one value a minute, with the last hour kept by `"history": 60`: ```sh #!/bin/sh idle=$(top -l 2 -n 0 -s 1 | awk '/CPU usage/ { idle = $7 } END { sub("%", "", idle); print idle }') used=$(echo "100 - $idle" | bc | cut -d. -f1) tone=accent [ "$used" -ge 80 ] && tone=warning cat < # Checklist Steps, and what's done, next and stuck. The tile is read-only: your script owns the list, whether it comes from todo.txt, Things, Reminders or a GitHub task list. ```json { "items": [ { "section": "Before" }, { "title": "Freeze main", "state": "done" }, { "title": "Smoke test on QA", "state": "doing", "who": "Sara", "note": "export and calendar left" }, { "title": "PO sign-off", "state": "blocked", "note": "Waiting for Kristian" }, { "section": "Release" }, { "title": "Deploy to prod", "who": "Anton" } ], "caption": "steps Β· release Thu 14:00", "foldDone": true } ``` | Size | Shows | |---|---| | `s` | The count, a bar, and the next step: the first one in progress, else the first one to do. | | `m` | The steps, in two columns when one doesn't fit. Sections are left out. | | `l`, `xl` | The count and bar, then sections, steps and notes. With `foldDone`, done steps are hidden behind a `βœ“ 3 done` line. | Steps that don't fit are cut, never scrolled. ## Fields | Field | | |---|---| | `items` | Required. Steps and sections, in order. A single step works without an array. | | `caption` | Next to the count, like `steps Β· release Thu 14:00`. | | `foldDone` | `true` hides done and skipped steps in an `l` tile. Off by default. | Each step: | Field | | |---|---| | `title` | Required. Text or a number. | | `state` | `todo` (the default), `doing`, `done`, `blocked` or `skipped`. `true` and `false` mean done and todo. Unknown states read as `todo`. | | `who` | Who's on it, at the end of the line. | | `note` | A line under the title. Red when the step is blocked. | A section is `{ "section": "Before" }`: a heading over the steps after it. With `foldDone`, a section whose steps are all done is hidden too. The count is done steps out of all steps. Skipped steps count as neither. The bar shows done steps in the success color, then steps in progress in the accent color. `summary` and `menuBar` work as for [rows](../script-output.md#menu-bar): they set what the menu bar shows. ## Example The task list in a GitHub pull request's description, with [gh](https://cli.github.com) and [jq](https://jqlang.org): ```sh #!/bin/sh gh pr view 1284 --repo acme/app --json body --jq .body | jq -R -s '{ items: [gsub("\r"; "") | split("\n")[] | capture("^\\s*[-*] \\[(?[ xX])\\] (?.*)") | { title, state: (if .x == " " then "todo" else "done" end) }], caption: "PR #1284" }' ``` With `"type": "checklist"` in [panel.jsonc](../panels.md), the tile always reads the output as a checklist, and says what's missing when the script prints something else. --- <!-- docs/types/feed.md --> # Feed Who said what, and when: mentions, notifications, commits, posts. ```json { "items": [ { "author": "Sara Lind", "where": "#dsp-spark", "text": "Can you look at the **export PR** before sprint review?", "time": "2026-11-16T13:12:00Z", "unread": true, "url": "slack://channel?team=T1&id=C1" }, { "author": "GitHub", "icon": "πŸ‘€", "where": "logbook #1284", "text": "**Johan Berg** requested your review on **feat: export filters**", "time": "2026-11-16T12:40:00Z", "unread": true }, { "author": "Kristian Ek", "avatar": "https://example.com/kristian.png", "where": "DM", "text": "Nice work on the calendar fix", "time": "2026-11-15T16:05:00Z" } ] } ``` | Size | Shows | |---|---| | `s` | The newest message, large, with who and when under it, and how many more are unread. | | `m` | The latest messages that fit, two lines each. | | `l`, `xl` | The messages that fit, under a heading per day: Today, Yesterday, the weekday, then the date. | ## Fields Each item: | Field | | |---|---| | `text` | Required. The message. `**bold**` is drawn brighter, for names and titles. | | `author` | Who said it. Without `avatar` or `icon`, the tile draws their initials on a color picked from the name, the same every time. | | `avatar` | An image URL, drawn round. The initials show while it loads, and if it can't. | | `icon` | An emoji drawn in a square instead, for bots and services: `πŸ€–`, `❌`. | | `where` | Where it was said, after the author: `#dsp-spark`, `DM`, `logbook #1284`. | | `time` | When it was said. ISO 8601 (`2026-11-16T13:12:00Z`, or `2026-11-16T14:12` in your time zone) or a Unix timestamp. Shown relative: `now`, `5m`, `2h`, `Sun` within the week, `12 Nov`. Anything else is shown as is. | | `unread` | `true` puts a dot before the author. | | `url` | Opened when the item is clicked in the glance. Closes the glance. | When every item has a `time`, the tile shows the newest first; otherwise it keeps your order. Relative times update every minute between runs. `items` can also be a single item instead of an array. Items with `author` or `text` make a feed; items with `title` make a checklist. `summary` and `menuBar` work as for [rows](../script-output.md#menu-bar): they set what the menu bar shows. ## Example Your unread GitHub notifications, with [gh](https://cli.github.com) and [jq](https://jqlang.org): ```sh #!/bin/sh gh api notifications --jq '{ items: [ .[] | { author: .repository.owner.login, where: .repository.name, text: "**\(.subject.type)** \(.subject.title)", time: .updated_at, unread: .unread } ] }' ``` With `"type": "feed"` in [panel.jsonc](../panels.md), the tile always reads the output as a feed, and says what's missing when the script prints something else. --- <!-- docs/types/grid.md --> # Grid Many things at once, a colored cell each: services, CI jobs, pull requests, uptime. ```json { "grid": { "rows": [ { "label": "logbook", "value": "100%", "cells": ["success", "success", "success", "success"] }, { "label": "assets-api", "value": "99.2%", "tone": "warning", "cells": ["success", "warning", "warning", "success"] }, { "label": "workshop-hist", "value": "96.8%", "tone": "error", "cells": ["success", "error", "error", "warning"] } ], "axis": ["24h ago", "12h", "now"], "legend": { "success": "up", "warning": "degraded", "error": "down" }, "footer": "checked every 5m" } } ``` | Size | Shows | |---|---| | `s` | The worst count, like `1 down`, the rest below it (`1 degraded, 10 up`), then a dot per row. | | `m` | A chip per row, three to a line: dot, label, value. | | `l`, `xl` | A row per item, its cells as history, the value on the right. The axis, legend and footer below. | Rows that don't fit are left out. ## Fields `grid`: | Field | | |---|---| | `rows` | Required, unless you give `levels`. | | `axis` | Labels under the cells at l, spread out evenly: `["24h ago", "12h", "now"]`. | | `legend` | What each tone means, as an object from tone to text: `{ "error": "down" }`. Shown at l, mildest first, and used for the words at s. | | `footer` | A line at the bottom at l, and under a heatmap at m: `checked every 5m`. | | `value`, `label` | Replace the computed text at s, like `All live` and `dev, qa, prod in sync`. | | `tone` | The color of `value` at s, and of the heatmap (accent by default). | | `levels` | A heatmap instead of rows. See [Heatmap](#heatmap). | | `height` | Cells per heatmap column for a flat `levels` list. Default `7`. | Each row: | Field | | |---|---| | `label` | Required. Text or a number. | | `value` | Right of the cells at l, in the chip at m: `99.2%`, `failed`, `2:48`. | | `tone` | The row's state: its dot at s and m, and its value's color. Without one, the last tone in `cells`. | | `cells` | The row's history, oldest first, shown at l. Each cell is a tone, or a level from 0 to 4. `null` is an empty cell. | `rows` can also be a single row instead of an array. ### Worst first A row's state is its `tone`, else its last tone cell. At s, the worst state counts first, in this order: `error`, `warning`, `info` and `accent`, `success`, then `muted` and `normal`. When every row is `success`, it reads `All up`, with `up` from the legend. Without a legend, tones read as plain words: `error`, `warning`, `ok`. ### Heatmap Give `levels` instead of `rows` for a heatmap, like GitHub contributions. Each level is 0 to 4; numbers outside are clamped, and fractions rounded. Either a flat list, oldest first, filled into columns of `height` from the top: ```json { "grid": { "levels": [0, 1, 3, 4, 2, 0, 0, 1, 2], "footer": "214 commits in 20 weeks" } } ``` or a list of columns: ```json { "grid": { "levels": [[0, 1, 3, 4, 2, 0, 0], [1, 2]] } } ``` Every size shows the newest columns that fit; m and l add the footer and a less-to-more key. A row's `cells` can be levels too, for a heatmap per row at l. `summary` and `menuBar` work as for [rows](../script-output.md#menu-bar): they set what the menu bar shows. ## Example The last runs of each workflow in a repository, with [gh](https://cli.github.com) and [jq](https://jqlang.org): ```sh #!/bin/sh gh run list --repo acme/app --limit 100 --json workflowName,conclusion,status | jq ' def tone: if .status != "completed" then "accent" elif .conclusion == "success" then "success" elif .conclusion == "failure" then "error" else "warning" end; { grid: { rows: (group_by(.workflowName) | map({ label: .[0].workflowName, tone: (.[0] | tone), value: (.[0].conclusion // .[0].status), cells: (.[:12] | reverse | map(tone)) })), axis: ["older", "latest"], legend: { success: "passing", warning: "cancelled", error: "failing", accent: "running" } } }' ``` `gh run list` prints the newest run first, so each row's first run is its state, and `reverse` puts the cells oldest first. With `"type": "grid"` in [panel.jsonc](../panels.md), the tile always reads the output as a grid, and says what's missing when the script prints something else. --- <!-- docs/types/keyvalue.md --> # Key-value Exact facts, grouped: a label on the left, its value on the right. ```json { "pairs": [ { "section": "Kubernetes" }, { "key": "Context", "value": "aks-prod-weu", "tone": "error", "pill": true }, { "key": "Namespace", "value": "logbook" }, { "section": "Repo" }, { "key": "Branch", "value": "feat/export-filters" }, { "key": "Uncommitted", "value": "3 files", "tone": "warning" } ] } ``` | Size | Shows | |---|---| | `s` | Label above value, for the first pairs that fit. No headings. | | `m` | Two columns of pairs, the left one filled first. | | `l`, `xl` | One list, with section headings. | Values are monospaced and cut in the middle when they don't fit, so the ends of IDs and paths stay visible. Pairs that don't fit are left out, never shown half. ## Fields Each item in `pairs` is a heading or a pair. A heading: | Field | | |---|---| | `section` | Required. Shown above the pairs after it, until the next heading. | A pair: | Field | | |---|---| | `key` | Required. The label. | | `value` | Required. Text, a number or `true`/`false`. | | `tone` | The value's color. | | `pill` | `true` draws the value on a capsule tinted in its tone. Needs a `tone`. | `pairs` can also be a single pair instead of an array. A heading with no pairs after it isn't shown. In `m`, a section split between the columns goes on in the right one without its heading again. `summary` and `menuBar` work as for [rows](../script-output.md#menu-bar): they set what the menu bar shows. ## Example Where your shell points, with [kubectl](https://kubernetes.io/docs/reference/kubectl/), [jq](https://jqlang.github.io/jq/) and git: ```sh #!/bin/sh context=$(kubectl config current-context) namespace=$(kubectl config view --minify --output 'jsonpath={..namespace}') cd ~/code/logbook || exit 1 branch=$(git branch --show-current) changed=$(git status --porcelain | wc -l | tr -d ' ') tone=normal; [ "$changed" -gt 0 ] && tone=warning prod=normal; case $context in *prod*) prod=error ;; esac jq -n --arg context "$context" --arg namespace "${namespace:-default}" --arg branch "$branch" \ --argjson changed "$changed" --arg tone "$tone" --arg prod "$prod" '{ pairs: [ { section: "Kubernetes" }, { key: "Context", value: $context, tone: $prod, pill: true }, { key: "Namespace", value: $namespace }, { section: "Repo" }, { key: "Branch", value: $branch }, { key: "Uncommitted", value: "\($changed) files", tone: $tone } ] }' ``` With `"type": "keyvalue"` in [panel.jsonc](../panels.md), the tile always reads the output as key-value, and says what's missing when the script prints something else. --- <!-- docs/types/markdown.md --> # Markdown Notes, runbooks and answers, written in Markdown. ```json { "markdown": "### On call this week\n**Anton** until Fri 17:00, then **Sara**.\n\n> workshop-hist is degraded since 11:20.\n\n#### Restart a stuck export\n1. Find the job: `kubectl get jobs -n logbook`\n2. Delete it; the cron job starts a new one" } ``` | Size | Shows | |---|---| | `s` | The heading and the first lines. Paragraphs stop after four lines. | | `m` | The document in two columns. | | `l`, `xl` | The whole document, cut where the tile ends. | Only whole blocks are shown: a paragraph, list item or code block that doesn't fit is left out, with everything after it. ## Fields | Field | | |---|---| | `markdown` | Required. The text, or an array of lines. | `summary` and `menuBar` work as for [rows](../script-output.md#menu-bar): they set what the menu bar shows. ## What's supported A subset of [CommonMark](https://commonmark.org): | Markdown | Drawn as | |---|---| | `#`, `##`, `###` | A title. The highest of these in the document is the title; deeper ones are section labels. | | `####` to `######` | A small, uppercase section label. | | `**bold**`, `*italic*`, `~~strike~~` | As written. | | `` `code` `` | Monospaced, on a darker background. | | `[text](https://…)` | A link, in the info color. | | `-`, `*`, `+`, `1.` | Lists. Indent by two spaces or more to nest them, up to four levels. | | `- [ ]`, `- [x]` | A task, open or done. | | ```` ``` ```` or `~~~` | A code block, one line per line, cut at the tile's edge. | | `> ` | A note in the warning tone. | | `---`, `***`, `___` | A line across. | Not supported, so shown as text: headings underlined with `===` or `---`, code indented by four spaces, HTML, tables and images. ## A file instead of a script A markdown panel can read a file instead of running a command. The tile reloads when the file changes: ```jsonc { "type": "markdown", "title": "Today", "file": "~/notes/today.md", "size": "l" } ``` `file` takes `~`, an absolute path, or a path in the panel's folder. Use either `file` or `command`, not both. See [panels](../panels.md). ## Example Today's section of a daily note, as written in Obsidian: ```sh #!/bin/sh note="$HOME/notes/daily/$(date +%F).md" [ -f "$note" ] || { echo '{ "markdown": "_No note yet._" }'; exit 0; } jq -Rs '{ markdown: . }' "$note" ``` With `"type": "markdown"` in [panel.jsonc](../panels.md), the tile always reads the output as markdown, and says what's missing when the script prints something else. --- <!-- docs/types/meters.md --> # Meters How full, how far, how close to a limit. ```json { "meters": [ { "label": "Macintosh HD", "value": 412, "max": 494, "text": "412 GB", "of": "494 GB", "mark": 450, "tone": "warning" }, { "label": "Docker.raw", "value": 58, "max": 96, "text": "58 GB", "of": "96 GB" }, { "label": "CPU requests", "value": 71, "mark": 85 } ], "footer": "82 GB free Β· Time Machine 2h ago" } ``` | Size | Shows | |---|---| | `s` | The first meter as a ring, with its value and label inside. | | `m` | The first three, each a big value over a bar. | | `l`, `xl` | A bar per meter, with limit marks, and the footer. Meters that don't fit are cut. | ## Fields Each meter: | Field | | |---|---| | `value` | Required. How far the bar fills, against `max`. A number, or text like `"4,212"` or `"83%"`. | | `max` | What a full bar is. Defaults to 100, so without it `value` is a percentage. | | `label` | The meter's name. At size `s`, the line under the value. | | `text` | What the value says, like `412 GB`. Defaults to the number, with a `%` when there's no `max`. | | `of` | What it's out of, shown after the value: `412 GB / 494 GB`. Defaults to `max` when you set one. | | `mark` | A limit tick on the bar, on the same scale as `value`. | | `tone` | The bar's color. Defaults to the accent color. | Values below 0 show an empty bar and values above `max` a full one. At the top level: | Field | | |---|---| | `footer` | A line under the bars at size `l`. | `meters` can also be a single meter instead of an array. `summary` and `menuBar` work as for [rows](../script-output.md#menu-bar): they set what the menu bar shows. ## Example Disk use on macOS, with a limit mark at 90%: ```sh #!/bin/sh disk() { df -k "$2" | awk -v label="$1" 'NR == 2 { used = $3 / 1048576; size = ($3 + $4) / 1048576 tone = used / size > 0.9 ? "error" : "accent" printf "{ \"label\": \"%s\", \"value\": %.0f, \"max\": %.0f, \"text\": \"%.0f GB\", \"of\": \"%.0f GB\", \"mark\": %.0f, \"tone\": \"%s\" }", label, used, size, used, size, size * 0.9, tone }' } free=$(df -h / | awk 'NR == 2 { print $4 }') cat <<EOF { "meters": [ $(disk "Macintosh HD" /), $(disk "Data" /System/Volumes/Data) ], "footer": "$free free" } EOF ``` With `"type": "meters"` in [panel.jsonc](../panels.md), the tile always reads the output as meters, and says what's missing when the script prints something else. --- <!-- docs/types/stats.md --> # Stats A few numbers, each against its last period. ```json { "stats": [ { "label": "Crash-free sessions", "value": "99.71", "unit": "%", "delta": "β–Ό 0.12", "tone": "error", "vs": "vs last week" }, { "label": "New issues", "value": 14, "delta": "β–² 5", "tone": "warning", "vs": "vs last week" }, { "label": "Releases", "value": "4", "delta": "5.2.1", "tone": "info", "vs": "latest, 2h ago" } ] } ``` | Size | Shows | |---|---| | `s` | The first stat, big: label, value, change. | | `m` | The first three, in a row. | | `l`, `xl` | The first six, in a 2Γ—3 grid. | ## Fields Each stat: | Field | | |---|---| | `value` | Required. Text or a number. | | `label` | Above the value. | | `unit` | Smaller, after the value: `%`, `ms`, `pts`. | | `delta` | The change, like `β–² 4` or `62%`. | | `tone` | The delta's color. Your script decides, since up isn't always good. | | `vs` | What the delta is against, like `vs last week`. | `stats` can also be a single stat instead of an array. `summary` and `menuBar` work as for [rows](../script-output.md#menu-bar): they set what the menu bar shows. ## Example Open pull requests and reviews this week, with [gh](https://cli.github.com): ```sh #!/bin/sh open=$(gh search prs --author @me --state open --json number --jq length) reviews=$(gh search prs --reviewed-by @me --updated ">=$(date -v-7d +%F)" --json number --jq length) cat <<EOF { "stats": [ { "label": "Open", "value": $open, "vs": "yours" }, { "label": "Reviewed", "value": $reviews, "vs": "this week" } ] } EOF ``` With `"type": "stats"` in [panel.jsonc](../panels.md), the tile always reads the output as stats, and says what's missing when the script prints something else. --- <!-- docs/types/table.md --> # Table The same fields for every row, in columns. ```json { "columns": [ { "title": "Pod", "mono": true, "width": "38%" }, { "title": "Status", "priority": 1 }, { "title": "Restarts", "align": "right" }, { "title": "Age", "align": "right" } ], "rows": [ { "cells": ["api-7d9f4-x2kq", { "text": "Running", "tone": "success", "dot": true }, 0, { "text": "2d", "dim": true }] }, { "cells": ["export-1794-lq", { "text": "CrashLoop", "tone": "error", "dot": true }, { "text": "12", "tone": "error" }, { "text": "41m", "dim": true }], "highlight": true } ] } ``` | Size | Shows | |---|---| | `s` | Up to two columns. | | `m` | Up to four columns. | | `l`, `xl` | Every column that fits. | Columns that don't fit the tile's width are dropped from the right. A column with a higher `priority` stays longer: with room for two of the four columns above, you see Pod and Status; give Age `"priority": 2` and you see Status and Age. Rows that don't fit are cut from the bottom. ## Fields `columns` is required; `rows` can be empty. Each column: | Field | | |---|---| | `title` | The header. A column can also be just its title: `"columns": ["Port", "Process"]`. | | `mono` | `true` for a monospaced column: IDs, versions, ports. | | `align` | `left` (default), `right` or `center`. Right-align numbers. | | `priority` | A number. Higher keeps the column longer when the tile is narrow. Defaults to 0. | | `width` | The column's share of the table's width, like `"38%"`. Columns without one share what's left. | Each row: | Field | | |---|---| | `cells` | Required. One per column, in column order. A row can also be just its cells: `["5173", "vite"]`. | | `highlight` | `true` tints the row in the error tone, or give a tone: `"warning"`. | | `url` | Opened when the row is clicked in the glance. Closes the glance. | | `command` | Run when the row is clicked in the glance, in the panel's folder. Wins over `url`. Keeps the glance open and runs the panel again, so the tile shows the result. | Each cell is text, a number, or an object: | Field | | |---|---| | `text` | What the cell shows. | | `tone` | The text's color: `success`, `warning`, `error`, `info`, `accent` or `muted`. | | `dot` | `true` puts a dot in the tone before the text, for a status. | | `dim` | `true` shows the text in the secondary color, for what matters less. | Missing cells show empty; extra cells are ignored. `summary` and `menuBar` work as for [rows](../script-output.md#menu-bar): they set what the menu bar shows. ## Example Pods in a namespace, with [kubectl](https://kubernetes.io/docs/reference/kubectl/) and [jq](https://jqlang.org). Pods that aren't running are highlighted. ```sh #!/bin/sh kubectl get pods -n logbook -o json | jq '{ columns: [ { title: "Pod", mono: true, width: "45%" }, { title: "Status", priority: 1 }, { title: "Restarts", align: "right" } ], rows: [.items[] | ((.status.containerStatuses[0].state // {}) | keys[0]) as $state | { cells: [ .metadata.name, { text: (.status.containerStatuses[0].state.waiting.reason // .status.phase), tone: (if $state == "running" then "success" elif $state == "waiting" then "error" else "muted" end), dot: true }, (.status.containerStatuses[0].restartCount // 0) ], highlight: ($state == "waiting"), command: "kubectl logs -n logbook \(.metadata.name) | open -f" }] }' ``` With `"type": "table"` in [panel.jsonc](../panels.md), the tile always reads the output as a table, and says what's missing when the script prints something else. --- <!-- docs/types/timeline.md --> # Timeline What's now, what's next, and how long until. ```json { "timeline": { "from": "09:00", "to": "17:00", "events": [ { "title": "Standup", "start": "2026-11-16T09:15", "end": "2026-11-16T09:30", "tone": "info" }, { "title": "Logbook export review", "start": "2026-11-16T10:00", "end": "2026-11-16T11:00", "subtitle": "Room Kajen" }, { "title": "Lunch", "start": "2026-11-16T11:30", "end": "2026-11-16T12:30", "tone": "muted" }, { "title": "Focus time", "start": "2026-11-16T13:00", "end": "2026-11-16T14:30", "subtitle": "no meetings", "tone": "success" }, { "title": "Sprint review", "start": "2026-11-16T15:00", "end": "2026-11-16T16:00", "subtitle": "Teams" } ] } } ``` Tjuvkik draws now and counts down itself, every 30 seconds, so the tile stays right between runs. Your script only has to run when the events change. | Size | Shows | |---|---| | `s` | A countdown: how long the current event has left, with a progress bar, or how long until the next one. | | `m` | The window as a strip with a now line, then what's on now, what's next, and how much is left. | | `l`, `xl` | An agenda: hour lines down the left, the events placed by time, and a now line. Events that overlap sit side by side. | ## Fields | Field | | |---|---| | `events` | Required. The events, in any order. | | `from` | Where the window starts, like `09:00`. | | `to` | Where the window ends, like `17:00`. A `to` before `from` ends the next day. | Without `from` and `to`, the window runs from the first event's hour to the last event's. `timeline` can also be just the array of events. Each event: | Field | | |---|---| | `title` | Required. | | `start` | Required. A time, see below. | | `end` | A time. Without one, the event is a moment. | | `subtitle` | After the time, like a room or `Teams`. | | `tone` | The event's color. `accent` when not set. | | `url` | Opened when the event is clicked in the glance. Closes the glance. | | `command` | Run when the event is clicked in the glance, in the panel's folder. Wins over `url`. Keeps the glance open and runs the panel again, so the tile shows the result. | ## Times | Written as | Means | |---|---| | `2026-11-16T15:00` | 15:00 on that day, in your Mac's time zone. Seconds are optional, and a space works instead of `T`. | | `2026-11-16T14:00Z`, `2026-11-16T15:00+01:00` | That exact time, in any zone. | | `2026-11-16` | Midnight at the start of that day. | | `15:00` | 15:00 today. `24:00` is the end of today. | | `9`, `17.5` | A number up to 24 is hours today: 09:00, 17:30. | | `1794841200` | A larger number is Unix seconds, or milliseconds. | Write times without a zone when they're local, like most calendars print them. Tjuvkik places them in the time zone your Mac is in when it draws them. `summary` and `menuBar` work as for [rows](../script-output.md#menu-bar): they set what the menu bar shows. ## Example Your day from a plain file next to the script, one event per line: start, end, title, separated by tabs. ``` 09:15 09:30 Standup 13:00 14:30 Focus time 15:00 16:00 Sprint review ``` ```sh #!/bin/sh awk -F '\t' ' BEGIN { printf "{ \"timeline\": { \"from\": \"08:00\", \"to\": \"18:00\", \"events\": [" } NF >= 3 { gsub(/"/, "\\\"", $3) printf "%s{ \"title\": \"%s\", \"start\": \"%s\", \"end\": \"%s\" }", sep, $3, $1, $2 sep = ", " } END { print "] } }" }' today.tsv ``` Times without a date are today's, so the same file works every day. With `"type": "timeline"` in [panel.jsonc](../panels.md), the tile always reads the output as a timeline, and says what's missing when the script prints something else.