LiquidBar

한국어

An open-source Liquid Glass taskbar and Cmd-Tab window switcher for macOS.

LiquidBar gives Mac power users the window control they keep missing: a real taskbar, large window thumbnails, Windows Alt-Tab style switching, system indicators, and deep configuration without taking over macOS.

Open By Design

Many macOS taskbar utilities are closed source while asking for Accessibility, Screen Recording, or Input Monitoring permissions. LiquidBar takes the opposite approach: the code is inspectable, the release path is documented, and the permission-sensitive pieces are kept small enough to review, build, and disable.

LiquidBar is for users who want:

• a real taskbar on macOS, including hidden and minimized windows
• a Windows Alt-Tab style switcher with macOS Cmd-Tab muscle memory
• large window thumbnails and click-to-select switching
• a bar that visually belongs on modern macOS instead of fighting it
• configuration that can be edited, tested, and extended
• an open foundation for future plugins such as media controls

Highlights

Cmd-Tab, But Window-First

LiquidBar turns Cmd-Tab into a window switcher: large thumbnails, MRU back-and-forth behavior, Cmd-Shift-Tab reverse traversal, click-to-select, and aspect-aware cards for wide, square, and portrait windows.

A Taskbar That Belongs On macOS

LiquidBar supports labeled windows, icon-only mode, app grouping, pinned apps, custom items, launcher/search entries, and per-display panels. The v1 default is an icon-first 32 px bottom bar with Liquid Glass styling.

Right-Click Controls

Right-click a window to rename it, apply a color, close it, pin it, hide it from the bar, reload config, or open preferences. Window actions stay at the top; app controls stay at the bottom.

System Indicators

CPU, GPU, memory, thermal, Codex, and Claude Code indicators can live inside the bar. Codex and Claude are independent, reorderable app-icon tiles that show the remaining percentage at a glance, reveal quota windows and reset times on hover, and open their app when clicked. Claude connects from Preferences without discarding an existing Claude Code status line. See AI Usage Indicators.

Preferences

Most v1 behavior can be tuned without editing JSON by hand: bar size, icon size, glass style, hover intensity, visual depth, animations, indicators, multi-monitor behavior, language, previews, permissions, diagnostics, and plugins.

Features

• Native taskbar: bottom, top, left, and right AppKit panels with retained Core Animation rendering rather than a permanent full-surface render loop.
• Window control: focus, hide, minimize, close, cycle, group, and show hidden/minimized windows from the bar.
• Context menus: right-click taskbar items for focused window actions, pinning, hiding, config reload, preferences, and quit.
• Keyboard switcher: Cmd-Tab by default, Cmd-Shift-Tab for reverse traversal, click-to-select thumbnails, all-display scope, and MRU-style back-and-forth switching.
• Large thumbnails: static ScreenCaptureKit thumbnails optimized for quick switcher open time without continuous background capture.
• Liquid Glass appearance: native vibrancy/material backdrops, glass tile treatments, hover states, and focus indicators tuned for modern macOS.
• System indicators: CPU, GPU, RAM, optional temperature, and independent Codex and Claude Code usage-left tiles with compact presentation modes.
• Multi-monitor support: choose all displays, main display only, or per-display window behavior.
• Custom items: pinned apps, files, folders, URLs, spacers, launcher items, and user-defined tab groups.
• Stable pinned apps: global pinned apps are the v1 default. Per-Space pinned apps remain experimental because macOS does not expose a public, fully reliable Spaces API for this use case.
• Plugin groundwork: experimental provider/plugin runtime for future extensibility, including media-control style tiles.

Default Hotkeys And Controls

Action	Default
Open switcher / next window	Cmd-Tab
Previous window in switcher	Cmd-Shift-Tab
Select hovered/clicked switcher item	Mouse click
Cycle windows from taskbar	Scroll wheel over the bar
Close a taskbar window	Middle-click its taskbar item
Open preferences	Menu bar icon or taskbar context menu

The switcher hotkey is configurable. If you do not want LiquidBar to intercept Cmd-Tab, change switcher_hotkey or disable switcher_enabled in config.

Permissions And Trust

LiquidBar can run with different feature sets, but the full taskbar/switcher experience uses macOS privacy permissions:

• Accessibility is used for window actions such as focus, hide, minimize, close, and optional window resizing around the bar.
• Screen Recording is used to capture window thumbnails for previews and the switcher. LiquidBar uses static thumbnails, not a constant recording loop.
• Input Monitoring is used only when a global shortcut needs to intercept keystrokes before macOS handles them, especially Cmd-Tab.
• Automation may appear for optional provider/media-control actions that control another app.

Other system-facing features are narrower in scope: update checks read GitHub release metadata from the canonical gradigit/LiquidBar repository, Launch at Login uses a user-visible LaunchAgent, and Dock auto-hide changes the standard macOS Dock preference only when that setting is enabled.

These permissions are powerful. The advantage here is that LiquidBar is open source: you can inspect the code, build the app yourself, verify the release artifact, and turn off features you do not use. That is a materially better trust model than a closed-source taskbar requesting the same system access.

Requirements

• macOS 26 or newer
• Swift 6.2 or newer for source builds
• Xcode command line tools

Install

Download the latest DMG from GitHub Releases, open it, drag LiquidBar.app to Applications, then launch LiquidBar from Applications.

On first launch, grant only the permissions for the features you use: Accessibility for window control, Screen Recording for thumbnails, and Input Monitoring for the Cmd-Tab switcher. See Permissions And Trust and Release Trust before installing unsigned/ad-hoc builds.

Build And Run

Run from source:

swift build
swift test -c debug
swift run LiquidBar

Build the real release-mode app bundle locally:

LIQUIDBAR_CREATE_DMG=1 LIQUIDBAR_CREATE_ZIP=0 ./scripts/build_release_app.sh
open build/release/LiquidBar.app

The release builder can produce build/release/LiquidBar-1.1.0.dmg. Set LIQUIDBAR_CODESIGN_IDENTITY=- for the unsigned/ad-hoc public artifact, or pass a Developer ID identity when notarized distribution is available. Early GitHub binaries may be published as unsigned/ad-hoc when clearly labeled; macOS Gatekeeper will warn until Developer ID signing and notarization are added. See docs/RELEASE.md.

The developer test bundle still exists for local TCC reset/regrant workflows, but it is not a release artifact:

./scripts/build_test_app.sh
open -a "$HOME/Applications/LiquidBar Test.app"

Configuration

Configuration is stored in:

~/Library/Application Support/LiquidBar/config.json

Useful config commands:

swift run LiquidBar -- --print-config-path
swift run LiquidBar -- --print-default-config
swift run LiquidBar -- --write-default-config

The v1 default config enables the icon-first taskbar, right-aligned system indicators, Cmd-Tab switcher, all-display switcher scope, and Liquid Glass styling. Developer performance logging is disabled by default.

Change the app language in Preferences -> General -> System -> Language. Choose System, English, or Korean.

Set LIQUIDBAR_CONFIG_DIR during development or tests to isolate config and state files:

LIQUIDBAR_CONFIG_DIR="$(mktemp -d)" swift run LiquidBar

Documentation

• CONTRIBUTING.md: contribution workflow
• SECURITY.md: security reporting, permissions, and release trust model
• docs/START_HERE.md: fresh-session onboarding packet
• docs/ARCHITECTURE.md: source map and runtime flow
• docs/DEVELOPMENT.md: local setup and common development commands
• docs/TESTING.md: SwiftPM, UI, visual regression, and release-oriented test flows
• docs/PERFORMANCE.md: local performance capture and A/B comparison workflow
• docs/RELEASE.md: release packaging, signing, notarization, and notes
• docs/MAINTAINER_NOTES.md: repository hygiene and documentation policy

Release Trust

Official update metadata and binary releases must come from:

https://github.com/gradigit/LiquidBar/releases

Do not install release assets from similarly named repositories or package mirrors unless they are explicitly linked from this repository. Official artifacts should be traceable to the documented release process. Prefer signed and notarized assets when available; unsigned/ad-hoc assets must be labeled.

Status

LiquidBar v1 is the first public release line. The current feature release is v1.1.0, adding capacity-aware taskbar overflow, Codex and Claude usage indicators, and a reversible Claude Code status-line bridge alongside broader fullscreen, display-change, and window-identity hardening. Initial binaries may be ad-hoc signed and clearly labeled unsigned/ad-hoc while Developer ID notarization remains pending. Sidebar mode, provider plugins, per-Space pinning, and window layout memory remain experimental.

License

LiquidBar is released under the MIT License. See LICENSE.