---
title: Bar Integrations
description: 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](https://quickshell.outfoxxed.me), [Waybar](https://github.com/Alexays/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)](/omarchy/shell/) for the bar configuration.

## dot commands with bar output

<CardGroup cols={2}>
  <Card title="Diff & Repo Watcher" href="/git/diff/">`dot git-diff --bar-json` flags managed repos that have uncommitted or unpushed changes.</Card>
  <Card title="Notifications" href="/git/notifications/">`dot git-notifications --bar-json` shows the GitHub notification inbox; left click opens the filtered TUI.</Card>
</CardGroup>

The [command reference](/dot/commands/) 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](https://go-automate.timmo.dev) is one example: its [`--bar-json` reference](https://go-automate.timmo.dev/reference/bar-json/) 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:

```bash
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.

```bash
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:

```bash
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](/configuration/private-dashboard/).

### `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](/configuration/private-git/).

## Health checks

`dot doctor` verifies `dot-git.yml` and GitHub notification API access.