Bar Integrations

--bar-json is a shared status-bar contract rather than a single command. Tools emit one-line --bar-json output (with text, tooltip, and class fields) meant to be polled by a status bar module through its own short-lived cache. Left click opens the relevant TUI; right click refreshes the cache.

dot git-diff status scans disable Git’s optional index locks. Background bar and TUI polling can read working-tree state during a rebase, merge, or another index-writing operation without refreshing the index or competing for .git/index.lock.

The JSON format is bar-agnostic: it works with Quickshell, Waybar, or any bar that can run a command and parse JSON. My own setup uses the Omarchy 4 Quickshell bar, which runs these commands through timmo.command widgets, but the commands themselves do not depend on any particular bar. See Shell (Quickshell) for how that bar is configured.

dot commands with bar output

Diff & Repo Watcherdot git-diff --bar-json flags managed repos that have uncommitted or unpushed changes.

Workflow Runsdot git-workflows --bar-json --since surfaces recent GitHub Actions activity for each repo's checked-out commit.

Notificationsdot git-notifications --bar-json shows the GitHub notification inbox; left click opens the filtered TUI.

The command reference lists the full --bar-json flag set on each command.

External applications

--bar-json is not limited to dot. Other tools in this setup emit the same bar-friendly JSON, so one bar can poll them the same way. go-automate is one example: its --bar-json reference documents the Home Assistant watcher output it exposes to a status bar.

go-automate’s entity watcher is a long-running stream, but a polled bar module or a dashboard source card wants one line per refresh. The bundled ha-entity-bar-json-once script bridges the two: it runs go-automate ha bridge watch entity --bar-json, reads the first line, stops the watcher, and prints that single line (or a hidden placeholder if nothing arrives). It takes the same flags as the watcher, for example:

ha-entity-bar-json-once --icon '' input_text.current_next_event_in_an_hour

ha-module-bar

ha-module-bar wraps go-automate with opinionated status-bar modules for common Home Assistant entities. Each mode ships default entity IDs and display rules; override them with --entity, --name, --icon, and mode-specific flags when your setup differs. Run ha-module-bar --help for the full flag list.

Mode	Behaviour
temperature	Show a numeric temperature reading when the entity state is numeric.
co2-alert	Show a warning or critical CO₂ reading above 1400 ppm and 2000 ppm respectively; hide otherwise.
voc-alert	Show a warning or critical VOC reading when the quality entity is very abnormal or extremely abnormal. Uses --quality-entity and --value-entity.
nas-activity	Show NAS activity while the gate switch is on; highlight when the inactivity script is armed. Uses --switch-entity and --inactive-script-entity.
dining-temperature	Show dining-room temperature only while the air-conditioner target is below --gate-below (default 25). Uses --gate-entity for the AC target.
current-next-event	Pass through the entity’s bar JSON when the text is non-empty.
doorbell	Stream doorbell state through singleton-stream so the bar can keep one long-lived watcher per module instance.

Most modes poll once per refresh. doorbell is the exception: it keeps a singleton stream alive for the bar ancestor process and emits JSON only when the output changes. Override the stream identity with --stream-key when multiple doorbell modules share an entity.

ha-module-bar temperature
ha-module-bar co2-alert --entity sensor.office_co2
ha-module-bar dining-temperature --gate-below 24
ha-module-bar doorbell --entity input_boolean.doorbell

CO₂ and VOC modes accept --fake-state warning or --fake-state critical for layout testing (WAYBAR_FAKE_CO2_ALERT and WAYBAR_FAKE_VOC_ALERT set the same values per mode). doorbell accepts --simulate on|off or --force-true for the same purpose.

All modes except doorbell support optional trigger hooks that run a shell command when entity state changes:

ha-module-bar co2-alert \
  --trigger-state critical \
  --trigger-command 'notify-send "CO2 critical"' \
  --trigger-on transition \
  --trigger-cooldown 300

--trigger-on accepts transition (default; fire when state enters --trigger-state) or match (fire while state equals --trigger-state). --trigger-initial true allows the first observed state to fire; the default skips the initial read so restarts do not replay alerts. --trigger-cooldown enforces a minimum interval between fires. Trigger state persists under $XDG_RUNTIME_DIR (override the key with --trigger-key when multiple modules share a mode).

dot dashboard rejects commands that embed singleton-stream or doorbell, so use ha-entity-bar-json-once for dashboard cards and reserve ha-module-bar doorbell for a streaming bar widget. See Private Dashboard Config.

package-updates-bar

package-updates-bar reports updates for packages listed in .dot-public-packages. It caches status-bar JSON under $XDG_CACHE_HOME/status-bar, refreshes stale data in the background, and keeps the previous AUR backoff behaviour. Run package-updates-bar refresh for an immediate retry.

Configuration

Which repos and which activity reach the bar is controlled by the private dot-git.yml config; the notifications.bar.ignore_bot_activity key tames bot noise. See Private Git Config.

Health checks

dot doctor verifies dot-git.yml, GitHub notification API access, and the absence of legacy git-workflow-watch leftovers.