Bar Integrations

The --bar-json status-bar contract shared by dot commands and external tools.

--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 Watcher

dot git-diff --bar-json flags managed repos that have uncommitted or unpushed changes.

Notifications

dot 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 positive NAS activity while the gate switch is on; hide zero activity and 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. Use `--max-length <characters>` to limit the bar text while preserving the full tooltip.
`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.