Bar Integrations

--bar-json is a shared status-bar contract rather than a single command. Tools emit one-line output with text, tooltip, and class fields. Git commands also include safe repository or notification rows for the native shell panel; generic status bars can ignore those extra fields and continue polling through their short-lived caches.

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 setup uses one timmo.git Quickshell service to poll repository and notification output directly, plus one timmo.home-assistant service for Home Assistant rows. The commands themselves do not depend on either plugin. See Shell (Quickshell) for the bar configuration.

dot commands with bar output

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

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. Numeric readings keep the state text supplied by Home Assistant without display-side rounding. 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.

Numeric shell items omit units to keep the bar compact. Their tooltips retain the unit of measurement.

Mode	Behaviour
temperature	Show a signed numeric temperature reading with its Celsius unit. Add --show-above <number> to hide it unless the reading is strictly above that threshold. A matching --gate-entity with --gate-state or --gate-below also shows it. Use --icon-only to keep the reading in the tooltip.
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. The unified Home Assistant shell service owns those pollers alongside continuous ha-watch-singleton status streams. doorbell is the exception: it keeps a singleton stream alive for the shell 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 temperature --entity sensor.outdoor_temperature --show-above 25
ha-module-bar temperature --entity sensor.outdoor_temperature --show-above 25 --gate-entity input_boolean.air_conditioner --gate-state on
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 the streaming Home Assistant shell service. 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 and GitHub notification API access.