claude-mode/docs/bar-widget.md

# The Omarchy bar widget

An icon in the Omarchy top bar showing which provider the next `claude` launch
will use, and a panel that switches it — and edits presets — without a terminal.

```bash
bash omarchy/install.sh
omarchy restart shell
```

The installer copies the plugin to `~/.config/omarchy/plugins/smoido.claude-mode/`
and adds its id to the bar layout in `~/.config/omarchy/shell.json` (backed up
first). Placement is `right`, before `omarchy.agents`; `CM_BAR_SECTION` and
`CM_BAR_BEFORE` override that at install, and `omarchy bar move
smoido.claude-mode --section <section>` moves it later.

**Restart the shell after installing or upgrading.** The shell does reload a
plugin whose files change, but it clears Qt's component cache while the old
widget is still alive, so the old compiled panel survives the reload —
`omarchy-shell shell rescanPlugins` does not shift it either.

## The icon

The icon is the mode, drawn as the provider's own mark: the Claude burst, the
OpenRouter arrow, the Z.AI Z, the LM Studio mark, the Ollama llama, and `< >` for
a custom endpoint. Anything other than Anthropic takes the theme accent, so the
bar stays quiet exactly when nothing unusual is configured. A dot on it means a
session needs repair ([live sessions](live-sessions.md#the-bar-notices-for-you));
it is a dot rather than a colour change, because recolouring the mark would
misreport the mode.

### The marks

They are vector paths drawn with `QtQuick.Shapes`, not font glyphs — most have
no Nerd Font pictograph at all, and paths take the bar's foreground colour and
follow the theme. They come from [simple-icons](https://simpleicons.org) (Claude,
OpenRouter, LM Studio, Ollama) and [lobe-icons](https://github.com/lobehub/lobe-icons)
(Z.AI); the `< >` is drawn here. Trademarks belong to their owners.

Each provider's mark and its `logoScale` live in `providers.json`, which reaches
the widget through `health.json`; `Modes.js` keeps only Anthropic's and a
fallback for an older `health.json`. The scale corrects apparent size, because
equal nominal size is not equal apparent size: LM Studio's filled container
covers 69% of its box against ~38% for most others, and Z.AI and OpenRouter are
wide-but-short marks whose ink spans only ~84% of the box height. A scale starts
from the geometric mean of the two corrections and is then settled by eye; the
Ollama and custom marks were also held to 1.0 or less of their box, since both
already fill its height.

Three details keep them from looking ragged in a 13px slot, which is what every
stock glyph in this bar measures:

- **No layer.** A layer rasterises the Shape at its own size and then scales the
  *texture*. Without one, the scale is a transform on the geometry and
  rasterisation happens once, at final resolution.
- **`Shape.CurveRenderer`** (Qt 6.6+) rasterises curves analytically instead of
  tessellating them into antialiased triangles.
- **An odd `iconSize`.** The marks are radially symmetric, so their arms sit on the
  centre line — a pixel *centre* at an odd size, the seam between two pixels at an
  even one, where each arm greys out. Even values are rounded up.

## The panel

**Click** the icon: current mode, every mode with the active one ticked, and the
model map behind a gateway. Picking a gateway unfolds its presets rather than
switching blind; picking a preset starts the switch. Each provider's list ends in
**New … preset…**.

Choosing a target does not switch immediately. It runs the same two checks the
CLI does, and both can stop it:

1. **Preflight.** If the mode has not been set up, has no key, has no models, has
   no address, or its server is not answering, the panel says which and offers the
   fix: *Set up …* opens a terminal and runs the first-run flow there (a bar popup
   can host neither a hidden key prompt nor a filter-select list), *Store the
   key…* opens a terminal for just the prompt, *Edit preset…* opens the editor,
   *Server settings…* opens the server form, and *Check again* re-runs the
   preflight.
2. **Running sessions.** If any are running, the panel lists them by terminal and
   directory, marks any that are mid-request, and asks: *Switch and restart*,
   *Switch and close*, *Switch only*, or *Cancel*. The session action runs
   strictly **after** the write — restarting first would bring them back up on
   the provider being left.

**The gear** on a preset row opens the preset editor: its four tiers, each with
the model it maps to. Clicking a tier opens one field that filters the provider's
models as you type (every word must match; ↓/↑ and Enter work), listed with
context length and price. The list is the [model cache](providers.md#the-model-cache),
so the panel never touches the network on its own; *Fetch models* / *Refresh
list* runs `models --refresh`. Any id can also be typed by hand. The editor also
has **Make default** / **Clear default**, **Duplicate…**, **Rename…** and
**Delete…** (greyed out, with the reason, on the preset in use), and — for a
server provider — **Server settings…**: the base URL, *Use local default* where
the provider has one, and whether that server needs an API key.

Editing the preset in use applies it at once; [providers.md](providers.md#editing-the-preset-in-use)
says why that does not ask about running sessions.

- **Esc** closes the panel. While it is open the panel holds the keyboard, as
  every other shell panel does, so its text fields can be typed into.
- **Right-click** switches straight back to Anthropic.
- **Middle-click** re-reads state.
- **Hover** for mode, preset, and the opus/sonnet mapping.

A failed action — a preset whose key was never stored is the common one —
surfaces the CLI's own error in the panel rather than looking like a click that
did nothing.

## Settings

Per instance, in the widget's entry in `~/.config/omarchy/shell.json`:

| key | default | meaning |
|---|---|---|
| `showLabel` | `false` | show the preset name beside the icon |
| `iconSize` | `13` | mark size in px; rounded up to odd |
| `root` | `~/.claude-mode` | where claude-mode is installed |