Barista

Keep your Mac awake. Keep your menu bar tidy.

Barista keeps your Mac awake from the menu bar, with timed or indefinite sessions. Barista starts in the menu bar with its preferences hidden. Left-click the cup to start or stop; right-click for durations and preferences. A separate compact arrow hides and reveals a group of menu bar icons you choose with native ⌘-drag.

Built with stx and Craft, using the system WebKit view and native macOS power assertions. The packaged app includes its own runtime.

Features

• Keep awake in one click — Prevent idle sleep with preset durations (5m, 15m, 30m, 1h, 2h, 4h, 8h, indefinite). Left-click the cup to brew or stop; the icon fills while your Mac is awake and the remaining time is on hover.
• Right-click for everything else — A native menu with the current status, durations, preferences and updates.
• Awake on startup — Start awake indefinitely by default. The GitHub edition also opens at login by default; the Store edition asks you to enable Open at Login in Preferences.
• Global hotkey — ⌘⇧C toggles keep-awake.
• Native icon grouping — ⌘-drag unwanted icons left of Barista’s arrow, then click it to hide or reveal the group. One compact control, with no pipes or wide spacer. ⌘⇧B toggles the group. Craft restores the bar if macOS also hides an unselected app icon. Identifiable Apple controls, including Wi-Fi and Battery, follow the same boundary.
• Launch at login — Start Barista when you log in.
• Updates for each edition — The GitHub edition checks its releases, verifies SHA-256, Apple notarization and Barista’s signing team, then installs and restarts. The Store edition receives updates through the Mac App Store.
• Native integration — Native status items, menus, keyboard shortcuts and power assertions, with a system WebKit preferences view.
• Preferences in one place — A dark preferences window for durations, startup behavior, grouping and updates.

Get Started

The packaged download requires macOS 15 or newer on Apple Silicon, matching the bundled Craft runtime. Icon hiding requires macOS 27, the direct build and Accessibility access.

Download the DMG from GitHub Releases, open it and drag Barista to Applications. Launch Barista from there. It starts awake indefinitely and opens at login by default. Right-click the cup for Preferences, durations and updates.

Editions

Both editions provide native keep-awake, timers, the ⌘⇧C shortcut and login settings. The GitHub edition includes icon grouping and its verified updater. The sandboxed Mac App Store edition excludes grouping because its native visibility backend requires a private Apple API. It uses Craft’s public-only runtime and native login registration, with Open at Login off until enabled. As of October 25, 2026, Store version 0.0.9 is uploaded and awaiting Apple’s export-compliance approval before App Review submission. Use GitHub Releases for the available download; the automated Store workflow records its current phase in Actions.

Keep-awake controls idle sleep. It does not override manual sleep, lid-close behavior, shutdown or macOS power protections. See the keep-awake guide.

To build from source, install native tools with Pantry and app dependencies with Bun:

pantry install
bun install --frozen-lockfile
pantry run dev

Choose your hidden group

1. Open Preferences and enable Hide a group of menu bar icons.
2. Choose Open System Settings… and enable Barista under Privacy & Security → Device Control and Data Access (the macOS 27 Accessibility permission).
3. Choose Arrange…, then hold ⌘ and drag unwanted icons left of Barista’s arrow.
4. Click the arrow, choose Hide Grouped Icons, or press ⌘⇧B. Click again to reveal.

Keep Barista’s arrow visible while hiding a group. If macOS places the arrow in its overflow, reveal it there first so Craft can read the group boundary.

Barista follows Hidden Bar’s current native visibility approach. Craft reads the arrangement through Accessibility and hides applications through the private macOS MenuBarClientCore API. Apps with several icons hide together; an icon kept on the visible side keeps its app visible. Wi-Fi, Battery and other identifiable Apple controls also follow the arrow’s boundary. The cup can sit on either side of the arrow and always remains visible. Grouping follows the display containing the arrow; native visibility applies to the selected app or Apple control across displays. Craft uses each displayed native slot's position, including when an app reports stale coordinates from another display. It checks that selected apps disappear and visible apps remain after activation. If macOS does not apply that selection, it releases the restriction, restores the bar and reports the failure. An empty group leaves everything revealed. Apps launched while collapsed may remain hidden until you reveal the group.

If verification fails, Barista opens Preferences to explain why it restored the bar.

The private API is not reliable for every arrangement. On macOS 27.0.1 it can suppress Apple modules such as Focus, Now Playing and camera/microphone activity indicators even when system items are allowed. Barista explicitly accepts that behavior, matching Hidden Bar. Reveal the group to restore those modules. Craft still protects unselected app icons and preserves the native signing identities of visible applications and helpers. Apps sharing an identity remain visible together if any of their icons are on the visible side.

The group is revealed on launch. Disabling grouping, quitting, permission loss or an activation error restores icons. Apple can change the private API, so this feature reports unavailable instead of falling back to a wide spacer. It is for direct distribution and cannot be used in App Store submissions.

macOS still owns system overflow when the revealed icons exceed available space, including its presentation over app menus. Barista does not widen a status item or replace that system control. Keep-awake works independently on macOS 15 and newer. Upgrades preserve awake, duration, login and Dock choices while retiring the old separator, always-hidden and auto-collapse settings.

Development

# Run the app in development mode
pantry run dev

# Lint
bun run lint
bun run lint:fix

# Build a distributable .app + .dmg
pantry run build

Set APPLE_SIGNING_IDENTITY for a signed direct build. Direct builds use barista.direct.entitlements for the Bun host. pantry run build:app-store packages the separate sandboxed edition with Craft as the native app host and an inherited Bun backend. It requires Store signing identities and a matching provisioning profile. See Releasing.

Releases

Release credentials live locally in .env. Prepare .env.production from the local signing and notarization values, then encrypt it with Buddy Env before staging it:

bunx --bun @stacksjs/buddy@0.75.299 env:encrypt --file .env.production --file-keys .env.keys

Commit only the encrypted .env.production. Keep .env, .env.keys, .p8 and .p12 files private. GitHub stores DOTENV_PRIVATE_KEY_PRODUCTION as a repository secret. Release CI decrypts credentials into temporary runner files, imports the Developer ID identity with Pantry, notarizes and staples the app and DMG, then removes the plaintext files.

When refreshing a credential, start from the existing encrypted file so Buddy can retain its encryption key. If you create a new key, update the matching GitHub repository secret from .env.keys before releasing.

After verification, bun run release:patch creates and pushes the next version tag. That tag starts both edition workflows. The direct release stages the DMG and update.json as a prerelease after packaged-app checks, then tests a real previous-to-new updater replacement and native restart before promoting it to latest. The Store flow verifies its sandboxed package, generates current screenshots through stx, uploads to Apple and submits for review once compliance is approved. A resume workflow checks Apple every six hours and reports the precise waiting or release phase. See Releasing. Installed copies download the direct update in the background; Install and restart becomes available after the download verifies.

The README animation uses captures of the installed app’s actual stx interface at its native panel size; its native window is verified separately. After refreshing .github/art/demo/ and recording the current version, regenerate it with bun scripts/generate-demo.ts (requires FFmpeg through Pantry).

Verification

bun run check
pantry run build
bun run test:native

The native E2E suite clones and signs the packaged .app with unique app and runtime identities, an isolated preference profile and an empty working directory. It uses only system tools on PATH, waits for its real WebKit view to initialize the tray and shortcuts, checks macOS power assertions, switches timed/indefinite sessions, validates rejected inputs, verifies the selected native backend and compact control, and checks shutdown and Start Awake after relaunch. CI verifies an ad hoc signed bundle and runs it against both the packaged app and its read-only DMG before release publishing. Timed expiry is covered in stx's native power tests. Craft also tests cancelled and late activations, errors, permission revocation and cleanup. Physical ⌘-drag placement still requires a macOS desktop check.

Architecture

The app source is TypeScript and .stx; Swift and Kotlin belong outside this app. Native implementation stays in stx/Craft, exposed through their public APIs.

Barista is a stx menu bar app. @stacksjs/stx is the only dependency — it wraps Craft, the Zig-powered native webview, and the desktop APIs (power management, preferences, system tray) behind one package.

createMenuBarApp from @stacksjs/stx/menubar owns the local server, the preference store and the login item, so the app is a declaration rather than a runtime:

app.ts                 createMenuBarApp: context, routes, tray menu
build.ts               Compile + package the direct DMG or sandboxed Store PKG
src/barista.stx        Preferences, with stx signals and native composables
src/caffeinate.ts      Named wrapper over the desktop power API
src/tray.ts            The menu bar item: its cup icon and its menu
src/durations.ts       The durations the popup and tray both offer
src/preferences.ts     Preference shape and defaults
src/updates.ts         Self-update from GitHub releases

See the stx guide, Menu Bar Apps, for the pattern.

Website and documentation

The marketing page is built with the Stacks frontend: stx layouts, partials and components, signals, native form bindings, and ts-css. The guide uses BunPress. Sources live in resources/ and docs/.

bun run build:site
bun run preview:site

The combined static site is written to storage/site/, with the guide at /docs/. Preview it at local preview. Native app builds continue to use dist/. Set SITE_URL to the real production origin when building for a host; these build and preview commands do not publish. CI builds the site, checks its links and assets, and uploads the output as an artifact.

See Website development for the design, asset sources and hosting requirements, Configuration for grouping limitations, and Releasing for the encrypted CI credential flow.

The live site is barista.stacksjs.com, with the guide at /docs/. bun run deploy:site:plan previews the Stacks attachment; bun run deploy:site publishes the static site and guide to that shared server. Pushes to main automatically deploy through Stacks after CI passes, then verify the live build. See Website deployment for credentials, release boundaries and live verification. bun run verify:site compares the deployed pages and assets with the exact deployed build and checks HTTPS and missing URLs. CI retains that production artifact for repeatable verification.

Contributing

We welcome contributions! Please feel free to submit a Pull Request.

Credits

• Hidden Bar for the grouping interaction and native visibility API research
• Bartender
• Chris Breuer
• All Contributors

Sponsors

Support Barista and the Stacks ecosystem through GitHub Sponsors.

License

The MIT License (MIT). Please see LICENSE for more information.

Made with 💙