📊 OMP Bar Bible

OMP Bar v9 is OMP’s configurable telemetry HUD: one compact view of the active model, work, context, quota, agents, repository, tools, and speed. This page is the single source of truth for its interface, behavior, configuration, and operating boundaries.

Representative Unicode bar
 
◕model☮  ☑☑▣ ☐☐ ⁵  ✎¹◎²◆³  ∞⁶  ▤       ▰▰▰▰▱▱▱▱  ⁵↓↑²⁹  ●●●●●●○○  ⑂main↑²↓¹  ⌘³  ⧖⁸⁴
└──────────── identity + work ───────────┘       └──────── capacity + system state ────────────────┘

Need	Fastest path	Result
See and edit everything	`/bar`	Opens the visual editor
Inspect the active shape	`/bar config`	Prints visibility and survival order
Make a common change	`/bar make context longer`	Compiles locally into validated operations
Make a precise batch change	`bar_configure`	Inspects, previews, or atomically applies operations

The 15-second mental model

A segment must be enabled and have runtime data to render. side chooses its split group. order chooses its position and narrow-screen survival priority. Segment settings choose what that item says and how it looks.

Install

Load the OMP Bar extension directory through OMP’s extensions setting, then reload plugins and open the editor:

{
  "extensions": ["/absolute/path/to/omp-bar"]
}

/reload-plugins
/bar

Host-specific home-directory paths are intentionally omitted from this published reference.

Visual editor

/bar opens a path-preserving editor. The root owns visibility, side, and order. Config owns global presentation. Entering a segment exposes only settings that affect that segment.

Bar                                              representative editor replica
 
    On   Item             Preview
  ▶ ●    ⚙ Config          widget · above · unicode
    ●←   ◕ Model           ◕model☮
    ●←   ☑ Todos           ☑☑▣ ☐☐ ⁵
    ●←   ◎ Agents          ✎¹◎²◆³
    ●·   ▰ Context         ▰▰▰▱▱▱
    ●→   ⇅ Tokens          ⁵↓↑²⁹
    ●→   ⑂ Git             ⑂main↑²↓¹
 
  Space/x show · S side · ← → or [ ] order · Enter edit · Esc/q save

Key	Root	Child layer
`↑` / `↓`	Move selection	Move selection
`Space` or `x`	Show or hide segment	Toggle or cycle selected value
`S`	Cycle `left → center → right` in split mode	—
`←` / `→` or `[` / `]`	Reorder	—
`Enter`	Open `Config` or segment settings	Edit, select, or apply
`Esc` or `q`	Save and close	Return to root
`Ctrl+C`	Cancel without saving	Cancel without saving

Short terminals scroll the editor. Configured items remain available even when they are outside the visible viewport.

How layout works

flowchart TD
  A[Runtime events] --> B[Runtime snapshot]
  C[Enabled segments] --> D[Build segment views]
  B --> D
  D --> E[Use compact form when needed]
  E --> F[Keep earlier priority]
  F --> G[Group by left · center · right]
  G --> H[Render widget or status surface]

The five controls

Control	Question it answers	Example
Enabled	May this segment render?	Show `git`, hide `clock`
Runtime data	Is there anything meaningful to show now?	No quota data means no quota view
Side	Which split group owns it?	Put `context` in the center
Order	Where does it sit, and how long does it survive?	Keep `model` before `activity`
Presentation	What value, width, glyphs, and detail should it use?	Context breakdown, 12 cells

Earlier order means higher priority: the renderer first asks a segment for its compact representation, then removes lower-priority tail items until the line fits.

Alignment and surfaces

Setting	Values	Behavior
Alignment	`left`, `center`, `right`, `split`	Positions one stream or three side groups
Side	`left`, `center`, `right`	Used by split alignment
Surface	`widget`, `status`	Widget uses the terminal’s measured width; status uses a 120-cell plain-text budget
Placement	`aboveEditor`, `belowEditor`	Applies to the widget surface
Spacing	`0`–`3`	Cells between rendered segments

The status surface is always left-aligned. Placement and split alignment affect the widget surface.

Unicode and ASCII

Unicode: ◕model☮  ☑☑▣ ☐☐ ⁵  ▰▰▰▱▱▱  ⁵↓↑²⁹  ⑂main↑²↓¹
ASCII:   3model free  [x][x][>] [ ][ ] 5  ###---  5v^29  br:main^2v1

Use unicode for density and visual hierarchy. Use ascii for strict 7-bit terminals or as the safest response to glyph-width artifacts.

Segment atlas

A segment can be enabled yet absent when its runtime value is empty. The samples below are editor previews, not promises that every item renders in every session.

Segment	Sample	What it answers	Controls
`model`	`◕model☮`	Which model, thinking level, and free-route marker?	Alias, max width, thinking marker, free marker
`todos`	`☑☑▣ ☐☐ ⁵`	What is done, active, and remaining?	Phases/ratio, divider, glyph cap, total
`context`	`▰▰▰▱▱▱`	How much context is used or free?	Style, width, aggregate/breakdown, used/free, percent
`tokens`	`⁵↓↑²⁹`	How many input and output tokens?	Arrows/exchange separator, optional `k` marker
`agents`	`✎¹◎²◆³`	Which subagent roles are active and how many?	Always show count
`loop`	`∞⁶`	What loop state or remaining iteration count?	Visibility and placement
`modes`	`▤`	Which OMP modes are active?	Visibility and placement
`quota`	`●●●○○`	Which provider window is limiting capacity?	Data, window, style, width, percent, reset, TTL
`git`	`⑂main↑²↓¹`	Which branch, sync state, and worktree state?	Branch, ahead/behind, working tree, width, refresh
`tools`	`⌘³`	How many tool calls are active?	Visibility and placement
`tps`	`⧖⁸⁴`	What token-generation speed is observed?	Live, last, or off
`activity`	`✓`	What recent activity state is visible?	Visibility and placement
`clock`	`14:05`	What is the local time?	Visibility and placement
`brand`	`π`	Should the OMP identity mark render?	Visibility and placement

Context, quota, and bar styles

Context and quota own independent width and style settings.

sparks     ✦✦✦✧✧     diamonds   ◆◆◆◇◇     dots       ●●●○○
stars      ★★★☆☆     blocks     ▰▰▰▱▱     squares    ■■■□□
line       ━━━┄┄     arrow      ━━━┈┈     ascii      ###--

Setting	Context	Quota
Width	`2`–`32`	`2`–`32`
Value/window	`used` or `free`	`tightest`, `shortest`, or `longest`
Detail	`aggregate` or `breakdown`	Optional percent and reset time
Data policy	Current context snapshot	Quota data on/off, cache TTL `1`–`120` minutes

Token display

Tokens (k) off   ¹²↓↑⁶⁷⁸⁹
Tokens (k) on    ¹²ᵏ↓↑⁶⁷⁸⁹

The optional superscript k is a compact unit marker. It does not rescale the numeric runs.

Default configuration

Area	v9 default
Bar	enabled; `widget`; `aboveEditor`; Unicode; redraw throttle `100 ms`
Layout	`split`; spacing `1`
Left	`model`, `todos`, `agents`, `loop`, `modes`
Right	`context`, `tokens`, `quota`, `git`, `tools`, `tps`, `activity`, `clock`, `brand`
Visible	`model`, `agents`, `loop`, `modes`, `context`, `quota`, `todos`, `tokens`, `tps`, `git`, `tools`
Hidden	`brand`, `activity`, `clock`
Priority	`model → todos → context → tokens → agents → loop → modes → quota → git → tools → tps → activity → clock → brand`
Context	blocks, width `8`, used, breakdown, percent off
Quota	dots, width `8`, tightest, percent/reset off, TTL `5 min`
Todos	phases, compact divider, max `18` glyphs, total on
Tokens	arrows, `k` marker off
TPS	last observed
Git	branch, ahead/behind, and working tree on; width `14`; refresh `1500 ms`

Looks

Looks are named snapshots of visual and segment configuration. Applying a preset preserves an unmatched custom configuration as the recovery look user before replacing it.

Look	Visible focus	Distinctive settings
`minimal`	Model, todos, context, tokens	Context width `6`; TPS off
`balanced`	Ten core operational segments	Default priority; context `8`; quota `6`; last TPS
`full`	All fourteen segments	Context `10`; quota `8`
`usage`	Model, context, quota, tokens, TPS, clock	Split capacity view; context `16`; quota `8`; percent and reset on
`user`	Last unmatched custom view	Automatic recovery snapshot
Saved look	User-selected snapshot	Lowercase kebab-case name; up to `12` manual looks

/bar look usage
/bar look next
/bar look previous
/bar look save focused-work
/bar look delete focused-work

Commands

Command	Effect
`/bar`	Open the visual editor
`/bar config`	Print current configuration, visible order, and survival priority
`/bar reset`	Restore v9 defaults
`/bar help`	Show concise help and examples
`/bar on` / `/bar off`	Enable or disable rendering
`/bar look NAME`	Apply a built-in or saved look
`/bar look next` / `previous`	Cycle looks
`/bar look save NAME`	Save the active visual configuration
`/bar look delete NAME`	Delete a manual look

Natural language

Documented phrases compile locally without a model round trip:

/bar make context longer
/bar context 12 wide
/bar put todos right of model
/bar side context center
/bar hide percentages
/bar show only model todos context tokens
/bar context stars and quota dots
/bar apply the balanced look
/bar spacing 2
/bar colors vivid
/bar hide git, show clock

Intent	Accepted vocabulary
Relative order	`before`, `after`, `left of`, `right of`
Width	`longer`, `wider`, `shorter`, `narrower`, `N wide/chars/cells`
Visibility	`show`, `enable`, `hide`, `disable`, `off`
Side	`side SEGMENT left/center/right`
Colors	`auto`, `quiet`, `vivid`
Spacing	`0`–`3`
Aliases	`ctx`, `limits`, `tasks`, `subagents`, `branch`, `speed`, `time`, and others listed by the segment atlas

An entirely unrecognized request is handed to the current agent, which should inspect and use bar_configure. For must-be-atomic natural-language changes, prefer one fully recognized clause per command or use one explicit tool batch; a mixed request can contain an unrecognized clause that produces no operation.

Agent-safe configuration

bar_configure is the supported machine interface. Never hand-edit the persisted JSON.

flowchart TD
  A[Configuration intent] --> B{Control surface}
  B --> C[Visual editor]
  B --> D[Local natural language]
  B --> E[Agent via bar_configure]
  C --> F[Draft then save]
  D --> G[Compile recognized clauses]
  E --> H[Inspect · dry-run · atomic batch]
  F --> I[Validate and persist]
  G --> I
  H --> I

Safety contract

Omit operations to inspect the active configuration.
Preserve every unspecified setting.
Use the fewest operations that express the request.
Use dryRun: true for consequential or ambiguous batches.
A batch is atomic: any validation error rejects the whole write.
The tool accepts at most 40 operations per call.

Operation vocabulary

Operation	Purpose	Required fields
`segment`	Show or hide	`segment`, `enabled`
`move`	Change priority/order	`segment`, `position`; `anchor` for before/after
`resize`	Resize context or quota	`target`; `width` or `delta`
`style`	Change context/quota bars	`target`, `style`
`side`	Assign split group	`segment`, `side`
`option`	Set a typed configuration option	`option`, `value`
`look`	Apply, save, delete, or cycle	`action`; optional `name` or `direction`

Common payloads

Inspect without writing:

{}

Preview a focused capacity layout:

{
  "dryRun": true,
  "operations": [
    { "op": "look", "action": "apply", "name": "usage" },
    { "op": "resize", "target": "context", "width": 20 }
  ]
}

Apply one atomic layout batch:

{
  "operations": [
    { "op": "segment", "segment": "clock", "enabled": true },
    { "op": "side", "segment": "context", "side": "center" },
    { "op": "move", "segment": "todos", "position": "after", "anchor": "model" },
    { "op": "style", "target": "context", "style": "stars" },
    { "op": "option", "option": "tokens.showK", "value": true }
  ]
}

Option IDs

Group	Option IDs	Values or range
Global	`enabled`; `surface`; `placement`; `glyphs`	Boolean; widget/status; above/below; Unicode/ASCII
Layout	`layout.alignment`; `layout.spacing`; `colors.mode`; `renderThrottleMs`	Four alignments; `0`–`3`; three color modes; `40`–`1000 ms`
Model	`model.maxWidth`; `model.showThinking`; `model.showFreeMarker`; `model.alias`	`3`–`24`; booleans; current-model alias
Agents	`agents.alwaysShowCount`	Boolean
Context	`context.mode`; `context.display`; `context.showPercent`	used/free; aggregate/breakdown; boolean
Quota	`quota.enabled`; `quota.mode`; `quota.showPercent`; `quota.showReset`; `quota.ttlMinutes`	Boolean; three windows; `1`–`120 min`
Todos	`todos.mode`; `todos.divider`; `todos.maxGlyphs`; `todos.showTotal`	phases/ratio; three dividers; `1`–`100`; boolean
Tokens	`tokens.separator`; `tokens.showK`	arrows/exchange; boolean
TPS	`tps.mode`	live/last/off
Git	`git.showBranch`; `git.showAheadBehind`; `git.showWorkingTree`; `git.branchMaxWidth`; `git.refreshMs`	Booleans; `3`–`40`; `250`–`60000 ms`

Additional limits: model aliases are capped at 32; saved look names are lowercase kebab-case up to 32 characters; manual looks are capped at 12.

Runtime and persistence

sequenceDiagram
  participant OMP as OMP events
  participant Bar as OMP Bar runtime
  participant Render as Segment renderer
  participant UI as Widget or status
  participant Store as statusbar.json

  OMP->>Bar: session · tool · todo · agent · loop · mode changes
  Bar->>Render: normalized config + runtime snapshot
  Render->>Render: build · compact · prioritize · split
  Render->>UI: redraw after throttle window
  UI-->>Bar: /bar or bar_configure mutation
  Bar->>Store: validate · serialize · temporary file · rename

Rendering is event-driven and throttled; the default redraw floor is 100 ms.
Git and quota use their own refresh/cache timing.
Configuration is stored as statusbar.json, migrated and normalized on load.
Writes are serialized, written through a private temporary file, and atomically renamed.
If the file exists but is unreadable, OMP Bar runs on defaults and refuses to overwrite it.
No-op changes do not create writes.

Current boundaries

Boundary	Practical response
Enabled segments without runtime data do not render	Treat the editor preview as a vocabulary guide, not a live-state promise
Status surface has a fixed 120-cell, left-aligned budget	Use the widget surface for terminal-width-aware split layouts
The reduced fallback menu exposes global actions, not full per-segment editing	Reopen `/bar` in the full interactive UI or use `bar_configure`
A mixed natural-language request can silently omit an unrecognized clause	Use one recognized clause per command or an explicit atomic tool batch
Split-editor reordering also rewrites global survival priority	Check `/bar config` after complex side/order edits
Extremely narrow colored output can expose clipping artifacts	Reduce segments or spacing; switch to ASCII when needed

Troubleshooting

Symptom	Check	Fix
Bar is absent	Enabled state, selected surface, extension load	`/bar on`; then `/reload-plugins` if the extension was just added
Segment is absent	Visibility and runtime data	Enable it; then confirm its data source exists
Important item disappears first	Global order	Move it earlier and inspect `/bar config`
Widget is on the wrong edge	Surface and placement	Select widget, then above/below placement
Layout is crowded	Context/quota width, spacing, visible list	Narrow bars, lower spacing, hide low-priority segments, or apply `minimal`
Config will not save	Unreadable persisted JSON or validation failure	Preserve the unreadable file for recovery; repair it outside the running process, then reload
Glyphs look broken	Terminal width/font behavior	Switch glyph mode to ASCII

Source and verification map

Concern	Source of truth	Contract coverage
Host lifecycle, commands, tool	`src/omp-bar.ts`	Integration and host tests
Schema, defaults, normalization	`src/bar-config.ts`	Config and settings-matrix tests
Segment output	`src/bar-segments.ts`	Segment and settings-matrix tests
Layout and width fitting	`src/bar-format.ts`	Format and render-target tests
Editor hierarchy	`src/bar-menu.ts`	Menu contract tests
Natural language	`src/bar-language.ts`	Language parser tests
Operations and validation	`src/bar-operations.ts`	Atomic-operation tests
Looks	`src/bar-looks.ts`	Look and operation tests
Persistence	`src/bar-store.ts`	Store, migration, and concurrency tests

From the OMP Bar source directory, bun run verify runs the complete contract suite. Source and this canonical reference were reconciled on 2026-08-12.

OMP docs: wiki.omp.loca.zone · Upstream runtime: oh-my-pi

description	Canonical visual and operational reference for OMP Bar v9.
tags	omp, telemetry, status-bar
aliases	/telemetry/bar-optimization-cheatsheet

Oh My Pi

Explorer

📊 OMP Bar Bible

Install

Visual editor

How layout works

The five controls

Alignment and surfaces

Unicode and ASCII

Segment atlas

Context, quota, and bar styles

Token display

Default configuration

Looks

Commands

Natural language

Agent-safe configuration

Safety contract

Operation vocabulary

Common payloads

Option IDs

Runtime and persistence

Current boundaries

Troubleshooting

Source and verification map

Graph View

Table of Contents

Backlinks