Configuring Omarchy Bar Position and Transparency: A Complete Guide

Omarchy bar position and transparency are controlled through the bar object in ~/.config/omarchy/shell.json, configurable via CLI commands (omarchy bar position <edge> and omarchy bar transparent <bool>), interactive gestures, or the Style menu, with all methods updating the same canonical configuration and applying changes instantly via IPC.

Configuring Omarchy bar position and transparency personalizes your Quickshell-based desktop environment by anchoring the status bar to any screen edge and controlling background opacity. The bar implementation (omarchy.bar plugin) reads its settings from a JSON subtree in the user's shell configuration, supporting programmatic updates through the omarchy-bar CLI tool and immediate visual feedback through IPC notifications. Whether you prefer terminal commands, direct file edits, UI gestures, or menu selections, all configuration methods converge on the same ~/.config/omarchy/shell.json file, ensuring consistent state across sessions.

Understanding the Bar Configuration Architecture

The Omarchy bar is implemented as a Quickshell plugin declared in manifest.json with id: omarchy.bar and kind: bar, instantiated from Bar.qml and hosted within the main shell. According to the Omarchy source code, the host shell (shell/shell.qml) loads the configuration from ~/.config/omarchy/shell.json (falling back to config/omarchy/shell.json) and injects the barConfig property into the plugin instance.

The configuration schema defines two primary settings:

• bar.position – Accepts string values "top", "bottom", "left", or "right" to control screen anchoring
• bar.transparent – Boolean true or false that determines whether the background is fully opaque or reveals the desktop wallpaper

When modifications occur, the bar reacts to IPC updates immediately without requiring a restart, as the running instance watches the configuration file and internal IPC channels for changes.

Changing Bar Position via CLI

The omarchy-bar script provides direct manipulation of the bar's screen position through the omarchy bar position command. This CLI tool updates the user's shell.json and notifies the running bar via the internal IPC channel.

Move the bar to the bottom edge:

omarchy bar position bottom

Anchor the bar to the left side:

omarchy bar position left

Valid position arguments include top, bottom, left, and right. The change takes effect immediately, repositioning the Quickshell bar to the specified screen edge.

Toggling Bar Transparency via CLI

Control background opacity using the omarchy bar transparent command, which accepts boolean values or a toggle switch:

Toggle between opaque and transparent modes:

omarchy bar transparent toggle

Explicitly enable or disable transparency:

# Enable transparency (wallpaper visible through bar)

omarchy bar transparent true

# Disable transparency (solid background)

omarchy bar transparent false

As implemented in bin/omarchy-bar, these commands modify the bar.transparent value in the JSON configuration and trigger an IPC update to the running bar instance.

Direct Configuration File Editing

For manual configuration, edit the bar object in ~/.config/omarchy/shell.json. The user configuration file becomes the canonical source after the first modification, superseding any default values shipped with the distribution.

Example configuration placing the bar on the right with transparency enabled:

{
  "bar": {
    "position": "right",
    "transparent": true,
    "layout": {}
  }
}

After saving changes to ~/.config/omarchy/shell.json, the bar detects the file modification and reloads automatically. Alternatively, execute omarchy reload to force an immediate refresh.

Interactive Configuration Methods

Beyond CLI and file editing, Omarchy supports intuitive gesture-based configuration defined in the bar plugin's QML implementation.

Repositioning via drag: Drag an empty section of the bar (click-and-hold on neutral space) to move it to a different screen edge. The gesture updates bar.position in shell.json through the same IPC mechanism as the CLI commands.

Toggling transparency via double-click: Double-left-click the empty center area of the bar to toggle the bar.transparent boolean value instantly.

Menu-Driven Configuration

The Omarchy menu provides graphical access to bar settings through entries defined in default/omarchy/omarchy-menu.jsonc. Navigate to Style → Menu Bar to access:

• Position – Select from Top, Bottom, Left, or Right
• Transparency – Toggle between Opaque and Transparent modes

These menu entries invoke the same omarchy-bar CLI commands internally, ensuring consistency with terminal-based configuration. The menu mappings reference "style.bar.position" and "style.bar.transparency" keys that correlate to the CLI functionality.

Key Source Files and References

Understanding the following source files helps troubleshoot configuration issues and customize advanced behavior:

File	Purpose
shell/plugins/bar/README.md	Documents the bar plugin architecture, configuration schema, and user-facing commands
bin/omarchy-bar	Implements the omarchy bar CLI commands that modify shell.json and trigger IPC updates
shell/shell.qml	Host shell script that loads shell.json and provides the barConfig property to the bar plugin
config/omarchy/shell.json	Default configuration file shipped with the distribution
default/omarchy/omarchy-menu.jsonc	Menu definitions mapping UI selections to bar configuration commands
~/.config/omarchy/shell.json	User-specific configuration file that becomes the canonical source after first modification

The bar plugin exposes properties such as bar.position and bar.vertical to widgets, allowing custom components to adapt their layout based on the current bar orientation and transparency state.

Summary

• Omarchy bar position and transparency are stored in the bar object within ~/.config/omarchy/shell.json, supporting values "top", "bottom", "left", "right" for position and boolean values for transparency.
• Three configuration methods exist: CLI commands (omarchy bar position|transparent), direct JSON file editing, and interactive gestures (drag-to-move, double-click-to-toggle).
• Immediate application occurs via IPC updates to the running Quickshell bar instance without requiring session restarts.
• Menu integration at Style → Menu Bar provides graphical access to the same CLI functionality.
• Source authority transitions from default config/omarchy/shell.json to user-specific ~/.config/omarchy/shell.json after initial modification.

Frequently Asked Questions

How do I move the Omarchy bar to a different screen edge?

Use the command omarchy bar position <edge> where <edge> is top, bottom, left, or right. For example, omarchy bar position bottom anchors the bar to the bottom of the screen. You can also drag an empty area of the bar to reposition it interactively, or use the Style → Menu Bar → Position menu.

What happens to my bar configuration when I edit shell.json manually?

When you save changes to ~/.config/omarchy/shell.json, the running bar detects the file modification through its file watcher and applies updates immediately via IPC. If the bar does not update automatically within a few seconds, run omarchy reload to force a configuration refresh.

Can I make the Omarchy bar semi-transparent instead of fully transparent or opaque?

The current implementation in bin/omarchy-bar and the bar plugin's QML configuration treats transparency as a boolean value (true or false) rather than an opacity percentage. The bar.transparent setting switches between fully opaque and fully transparent backgrounds that reveal the desktop wallpaper. For partial transparency, you would need to modify the Bar.qml source or create a custom theme override.

Where does Omarchy store the default bar configuration before I make changes?

Default settings are defined in config/omarchy/shell.json within the Omarchy installation directory. Once you modify the bar position or transparency using any method (CLI, gestures, or menu), the system creates or updates ~/.config/omarchy/shell.json, which then becomes the canonical source that overrides all defaults for subsequent sessions.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}