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.

Orbtile also reads local Codex thread files for state and live text. Desktop threads and codex exec runs always show as Codex, even when launched from another agent. Approve permission requests in Codex: keypad approval is unavailable, and Codex permission waits are not shown on the keypad.

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 shows its name, state and live text over an animated orb. Settings > Appearance offers Frosted glow, Globules, the dot-based Point cloud theme and Riso, each with v1 and v2.

• 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: Motion follows the tool kind: shell, edit, read, web, delegate, plan, integration or other. The key also shows the tool name and command.
• Streaming: Rising ripples with typewriter text at your selected speed 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 waiting count and leading session, or the working count when nothing is waiting.

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. With Key actions on, tap key 9 on the grid to focus the first waiting session in grid order, including other pages. If none is waiting, the tap does nothing. Hold key 9 for 0.6 seconds to open the Mac overlay; it does not also focus a session.

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: Jade working palette with rose 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

First enable Key actions in Settings > Keypad. It is off by default. The gestures below apply while Orbtile controls the keypad.

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, agents on key 2, and status and timer on key 3. Larger live text reads across keys 4–5–6, then the top two lines of keys 7–8–9. Words stay inside the keys. When streaming ends, the text settles into the middle row and gives the bottom-row orb its space back.

In ordinary Focus mode, a tap returns to the grid, except key 2 (subagents) and, during a Claude Code or ZCode permission request with keypad approval on, Deny and Allow. Questions use the separate option layout below.

Approve from the keypad

Orbtile can answer permission requests on the keypad itself. This is opt-in per agent, for Claude Code and ZCode. It is off by default. Turn on "Approve from the keypad" in Settings > Agents > Claude Code or ZCode > Keypad, and enable Key actions in Settings > 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.

Keypad approval is unavailable for Codex: waiting for the keypad would delay its on-screen approval dialog. Answer permissions in Codex; Orbtile does not show Codex permission waits on the keypad. Third-party adapters do not support keypad approval in 0.2.

For ZCode, turning the setting on adds one hook to ZCode's settings file (~/.zcode/cli/config.json), and turning it off removes it again. It applies to new ZCode conversations in local workspaces on this Mac; conversations that were already open, and remote workspaces, keep using ZCode's own prompt. ZCode shows a "Waiting for Orbtile keypad" line in the chat while the keypad can answer. Questions, plans and workflows are always answered in ZCode.

Answer questions from the keypad

When Claude Code asks you a question with options, the question stays on screen and you can also answer it on the keypad. The same "Approve from the keypad" setting for Claude Code turns this on.

The session's key shows the option numbers, for example "1 2 3 hold". Hold that key to open the question. Keys 1, 2 and 3 show options 1 to 3, and key 7 shows option 4. The question is on keys 4 to 6. Tap an option to pick it. When a question allows more than one answer, each tap turns an option on or off.

When more questions follow, key 9 shows Next: tap it to go to the next question. The page buttons also go to the previous or next question. On the last question key 9 shows Send: hold it for 0.6 seconds while its ring fills. All your answers go to Claude Code together, and nothing is sent before that.

Key 8 brings the session's window to the front, so you can type your own answer on screen. A tap on keys 4 to 6 goes back to the grid, and your picks stay. Send is available only after every question has a pick. An early release sends nothing.

The question on screen always works, and whichever answers first wins. When you answer on screen, the keypad shows "Answered". The keypad can answer for up to 10 minutes. Codex questions show on the keypad read-only: answer them on screen.

Subagents view

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

Press key 2 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 and stop at the first and last 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. Grid, focus, subagent and question navigation stops at the first and last page or session; it never wraps around.

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

Key order

Keys 1 through 8 arrange sessions by state: waiting, working, recent finishes, then idle; offline sessions follow. Finished sessions stay in the recent-finish tier for 15 seconds. Within a tier, sessions keep their order by default.

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

Working and waiting sessions always remain visible. Idle sessions stay for the recency window (default 120 minutes). Keys hold their positions for at least 8 seconds between ordinary moves; a newly waiting session can move ahead sooner, after the input freeze.

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.
• Key order: State tiers keeps sessions in order within waiting, working, recent finishes and idle. Activity leaders also lets a clearly busier working session pass another working session. Both use an 8-second dwell; new waits can move ahead after the 1.5-second press freeze.
• 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 "Frosted glow" (soft hearts), "Globules" (turning spheres of glowing globules), "Point cloud" (a lattice of crisp round dots), or "Riso" (printed ink). Each has v1 and v2 buttons. State words and gestures stay the same.
• Point cloud, rendered by Orbtile:
• 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. For Claude Code it also lets you pick numbered question options, including multiSelect, and hold Send for 0.6 seconds. The on-screen question stays available. Off by default, and only for Claude Code and ZCode; Codex permissions are answered in 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: In 0.2, displays Free beta or Update required. The beta has no licence key or trial countdown; licence entry starts with 1.0.

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

For Claude Code, if session keys light up but live typewriter text does not stream, the session may have 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.

Send feedback

Choose Send Feedback in the Orbtile menu for a bug, idea, complaint or other report. Email and safe diagnostics are optional; review the full submission before sending. We store your kind, message, optional email and optional diagnostics to answer requests and improve Orbtile. Feedback is kept for 365 days and deleted on the next hourly cleanup run. If delivery fails, a local queued draft retries hourly until accepted. You can also use the website feedback form or email [email protected]. Feedback messages contain what you type and are stored as submitted; please leave out secrets, personal information and private task text.

Something looks wrong on a key

Something looks wrong on a key? Choose Save Keypad Snapshot in the Orbtile menu (or run open orbtile://snapshot) and send the folder with your report.

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.

ZCode asks for permission only in a mode that asks before changes, and only conversations started after you turned the setting on use the keypad. Start a new ZCode conversation after turning it on.

Orbtile runs on your Mac. It reads only the end of each Claude Code transcript to show the latest words on the key, and automatic reports never send transcripts, prompts or source code. It also reads local Codex thread state and rollout tails, and ZCode task state. Each day it sends orbtile.com a usage report (and an update when you quit) of counts, minutes and model names under a pseudonymous machine ID; see our privacy notice for the full list.