Getting started with Orbtile

Download

Download the disk image Orbtile-0.2.0.dmg and drag Orbtile to your Applications folder.

First open steps

Orbtile is currently distributed outside the Mac App Store without Apple notarization, so macOS Gatekeeper blocks opening on first launch.

Open Orbtile using any of these three methods:

• Finder: Control-click (or right-click) Orbtile in Applications, choose Open, and click Open in the confirmation dialog.
• System Settings: Go to System Settings > Privacy & Security, scroll down to the Security section, click Open Anyway, and enter your Mac password or Touch ID.
• Terminal: Run xattr -dr com.apple.quarantine /Applications/Orbtile.app in Terminal to clear the quarantine flag.

macOS version

Orbtile requires macOS 14.0 Sonoma or later running on Apple silicon (M1 or later).

The keypad

Connect your Logitech MX Creative Keypad to your Mac using its USB-C cable.

Orbtile uses the nine LCD keys and two page buttons of the keypad over USB HID.

Logi Options+ coexistence

Logi Options+ stays installed on your Mac.

While Orbtile is in control, your Options+ profile for the keypad pauses.

Options+ gets the keypad back immediately whenever you quit Orbtile, switch to Options+ in the menu bar, press the shortcut Control-Option-Command-K, or hold both keypad page buttons for 1.5 seconds.

Claude Code

Install the Orbtile plugin from the app in Settings > Agents > Claude Code or during onboarding.

The plugin registers 18 hooks that stream session events and live typewriter text over a private local Unix domain socket on your Mac.

If you have Claude Code sessions running before installing or updating the plugin, restart them once in Claude Code so they load the plugin.

Codex

Install the Codex hooks from Settings > Agents > Codex to configure 12 hook events in your Codex hooks file.

Codex requires you to trust new hooks manually in Codex Settings > Hooks before it runs them.

Open Codex > Settings > Hooks, review the 12 Orbtile hooks, and click trust; once trusted, the adapter shows Live.

Without hooks installed, Orbtile falls back to reading Codex thread files directly, showing session state without permission prompts.

ZCode

ZCode needs nothing installed and no setup.

Orbtile reads task state directly from ZCode database files on your Mac, so starting a task in ZCode automatically assigns it a key.

Other agents: Adapter API

Orbtile 0.2 has an open, local Adapter API (version 1). Any agent or script can show its sessions on the keypad through it. It talks to Orbtile over a Unix socket on this Mac. There is no network port.

The API is off by default. Turn on the "Adapter API" switch in Settings > Agents.

A newly registered agent stays hidden (off the keypad and out of the menu) until you allow it in Settings > Agents. See the Adapter API reference.

States in words

Each session key features a glowing frosted orb beneath three lines of status text and live typewriter output.

• Idle: A calm pilot light breathing gently every 6 seconds.
• Starting: An expanding ring and ignition flare displaying the model name.
• Thinking: A 3.2-second pulse with two orbiting thought lobes showing the active turn.
• Tool: A sweeping spotlight across the keycap displaying the tool name and command.
• Streaming: Rising ripples with typewriter text streaming at 18 characters per second and a blinking caret.
• Permission: An urgent 1.6-second breath with outward shockwave rings displaying the requested tool and command.
• Question: A double heartbeat pulse every 2 seconds with rings displaying the question prompt.
• Done: A warm still glow with a soft chime pulse every 8 seconds displaying the final message line.
• Error: A red floor wash with a flickering flame displaying the error category and reason.
• Compacting: A concentric ring draining inward every 2.4 seconds as context compacts.
• Offline: A hollow dim ring with an extinguished center showing the session ended.
• Empty: A single dim dot marking an unassigned key slot.

The hub key

Key 9 in the bottom right corner is the hub key summarizing all sessions.

The top shows the count of sessions waiting for approval, errors, or active turns with a summary label.

The bottom shows a row of eight miniature pips representing keys 1 through 8 in their respective states and adapter colours.

An underglow beneath the pips reflects the most urgent state across all keys.

Colours per agent

Each agent has a dedicated colour palette so you can identify sessions at a glance.

• Claude Code: Warm amber gold working palette with terracotta waiting and permission states.
• Codex: Cool blue working palette with magenta-violet waiting and permission states.
• ZCode: Teal working palette with cyan waiting states.
• Errors: Universal dark red and bright crimson across all agents.

You can customize the base hue for any agent in Settings > Agents using the hue ring.

Tap a key

A short press under 0.6 seconds on a session key opens that session in its application or terminal window.

You can configure key tap in Settings > Keypad to open the session, mark it as read, or do nothing.

Hold for focus mode

Holding a session key for 0.6 seconds or longer opens Focus mode across all nine keys.

Focus mode displays the session name and model on key 1, fifteen lines of streamed output across keys 2, 5, and 8, status headlines and elapsed timers on key 3, subagent indicators on key 4, and an expanded hero orb across keys 6, 7, and 9.

In Focus mode, a tap on any key returns to the grid, except key 4 (subagents) and, during a permission request with keypad approval on, Deny and Allow.

Approve from the keypad

Orbtile can answer permission requests on the keypad itself. This is opt-in per agent, and only Claude Code and Codex have it. It is off by default. Turn on "Approve from the keypad" in Settings > Agents > Claude Code or Codex > Keypad.

When a session asks for permission, its key glows. Hold that key to open Focus mode. Key 7 in the bottom left shows Deny, and key 9 in the bottom right shows Allow. Press Deny once to deny. Hold Allow for 0.6 seconds while its ring fills to allow. Releasing earlier does nothing.

The prompt on screen still works, and whichever answers first wins. The keypad can answer for about 25 seconds. After that, answer on screen. A timeout never allows anything.

For Codex, turning the setting on or off rewrites the Orbtile hooks, so Codex asks you to trust them again.

Subagents view

In Focus mode, key 4 shows the session's subagent count with activity dots.

Press key 4 to open the subagents view. Keys 1 to 8 show one subagent each: its orb state, its current tool or command, its streamed text, and its elapsed time.

Tap key 9 to go back to Focus mode. Hold key 9 to go back to the grid.

With more than 8 subagents, the page buttons show the previous or next page.

Tapping a subagent that is waiting returns to Focus mode. If it is waiting for a permission and "Approve from the keypad" is on, Deny and Allow appear there. Otherwise the session's window opens.

Page buttons

The two hardware buttons below the keys navigate pages or browse sessions.

In grid mode, pressing the left or right page button flips between pages when more than eight sessions are active.

In Focus mode, pressing a page button steps to the previous or next session in grid order without leaving Focus mode.

Holding both page buttons down together for 1.5 seconds releases the keypad back to Logi Options+.

Key order

Keys 1 through 8 arrange active sessions by latest turn-level activity, placing the newest session on key 1.

When keys reorder, glowing orbs smoothly glide across the keypad to their new positions over 0.8 seconds.

Sessions remain on their keys while working or waiting, or as long as they were active within the recency window (default 120 minutes).

Key reordering freezes for 1.5 seconds after any key press to prevent positions from shifting under your finger.

General

• Launch Orbtile at login: Starts Orbtile automatically when you log into your Mac.
• Take over the keypad when Orbtile starts: Takes control of the keypad at launch instead of starting released.
• Give the keypad back to Options+ when Orbtile quits: Returns keypad control to Logi Options+ whenever Orbtile shuts down.
• Show a dot when a session is waiting for you: Displays an indicator dot on the menu bar icon when any session needs attention.
• Show the waiting count next to the icon: Displays the numeric count of waiting sessions beside the menu bar icon.
• Switch the keypad between Orbtile and Options+: Toggles keypad ownership using the global shortcut Control-Option-Command-K.
• Open the Orbtile menu: Opens the Orbtile menu bar popover using the global shortcut Control-Option-Command-O.

Keypad

• Show sessions active in the last: Sets the recency window for keeping idle sessions visible on the keypad.
• Reorder keys on: Chooses whether keys reorder only on turn changes or on all activity including streaming text.
• Frame rate: Sets the target display refresh rate between 10 and 30 frames per second.
• Calm down when nothing happens: Dims the keypad and reduces rendering to 10 frames per second after a period of quiet.
• Key actions: Enables or disables hardware button presses on the keypad.
• Press a session key: Selects whether tapping a session key opens its application, marks it as read, or does nothing.
• Hold a session key: Selects whether holding a session key enters full-pad Focus mode or does nothing.
• While the Mac is locked: Chooses whether keys stay live, show orbs only without text, or turn off while your Mac is locked or sleeping.
• Give the keypad back to Options+ while the Mac sleeps: Hands keypad ownership back to Logi Options+ during system sleep.

Appearance

• Keypad theme: Chooses the look of the keys: "Frosted glow" or "Point cloud".
• Orb brightness: Adjusts the software exposure level of the glowing orbs without changing hardware backlight.
• Typewriter speed: Controls how quickly streamed text reveals character by character on the LCD keys.
• Follow Reduce Motion: Stops orb pulsing and movement in the Mac interface when system motion reduction is enabled.
• One alarm colour for all agents: Makes every waiting session glow the same alarm colour, whichever agent runs it.
• Show agent glyph on keys: Shows a small monogram in the key corner that names the agent.

Agents

• Agent enable toggle: Enables or disables tracking for a specific coding agent.
• Hue ring: Adjusts the primary color hue used for an agent's keys and orbs.
• Approve from the keypad: Answers this agent's permission requests on the keypad: hold Allow to allow, press Deny to deny. Off by default, and only for Claude Code and Codex.
• Adapter API: Lets your own scripts and agents on this Mac show sessions on the keypad. Off by default, and each new adapter asks first.
• Show background sessions: Displays headless or scheduled agent sessions that run without an open terminal window.

Remote Hosts

• Add Host: Connects to an SSH host alias to monitor remote Claude Code agent sessions.

License

• License status: Displays your trial countdown, beta status, or registered license details.

Keys show Options+ icons

The keypad displays Logi Options+ icons whenever Orbtile is released or has not taken control over USB.

Click Take Over Keypad in the Orbtile menu bar popover or Settings > Keypad, or press Control-Option-Command-K to regain control.

Live text missing

If session keys light up but live typewriter text does not stream, the session started before the plugin was installed or updated.

Restart the Claude session once in Claude Code after installing or updating the plugin to connect it to the live socket.

Codex shows "Needs review"

Codex displays "Needs review" when Orbtile hooks are installed in configuration but have not been trusted in Codex preferences.

Open Codex > Settings > Hooks, review the 12 Orbtile hooks, and click trust, then send a prompt to verify the adapter switches to Live.

Mac locked

When your Mac is locked or display sleep begins, Orbtile follows your "While the Mac is locked" setting.

In "Orbs only" mode, text clears from the keys for privacy while orb pulses continue.

Fast User Switching suspends keypad rendering because another user owns the Mac console session.

When your Mac enters full system sleep, Orbtile hands the keypad back to Logi Options+ if "Hand over on sleep" is enabled.

The app says Update required

Orbtile checks signed status at orbtile.com/beta/status.json and requires an update when a beta build expires.

While an update is required, the keypad returns to Logi Options+ while the menu bar popover stays operational.

Click Download Update in the Orbtile menu or visit the download page to install the latest build.

Subagent count stays high

After you stop a workflow or an agent, its subagent count can stay high for up to 30 minutes, because a stopped agent sends no "finished" event.

Deny and Allow never appear

Recent Claude Code versions start in auto mode, which approves low-risk actions without asking. The keypad only sees the requests Claude Code still asks about. To answer every request on the keypad, switch the session to manual mode (Shift+Tab cycles the modes), or start it with claude --permission-mode manual.

Orbtile runs completely locally on your Mac, transmits no analytics or telemetry, and never reads your source code, prompts, or conversation transcripts; see our privacy notice for details.