Luma support

Start here if you need help connecting Luma or finding a setting.

Connect Codex

Install and sign in to Codex Desktop, then start a local task. Keep Codex open while using Luma. When macOS asks for a folder, select the Codex folder containing your sessions and task index. In the picker, press Shift–Command–G and enter ~/.codex. This grants local read access, including Codex configuration.

You can also choose Codex CLI in Settings → Connection, select your installed Codex executable and sign in if asked. Luma runs a local app server and reconnects when you send a message after reopening. Desktop and CLI keep separate task tabs and drafts. Models, limits, tools and available controls depend on your Codex version, configuration and account. Computer use is available only when the chosen connection provides a compatible integration. Luma does not include Codex access. Cloud-only tasks without local activity cannot be followed.

Chats and replies

Open Chats to choose a task. You can rename chats, add an emoji and drag tabs to change their order. Multiple image previews share a grid when there is enough space. Return sends a reply; Shift–Return inserts a new line. Drop an image into the reply field to attach it. The brain button opens reasoning controls and model selection. Fast is available only when the selected model supports it. Sending or granting an approval is always an explicit action.

Desktop pet and compact view

The pet opens separately from the main window. Drag it to move it; its position is remembered. The X on its bubble hides the conversation, and a new update opens it again. Brief and Full change how much chat is shown. Use the reply button in the bubble to write a response. Compact view keeps the conversation in a smaller floating window.

Big Screen

Use Big Screen in the top bar to enter macOS full screen. It always uses a dark background, even when the main app uses a light theme. Text size controls the conversation scale. Press Escape to leave.

Connect Philips Hue

Keep the Mac and Hue Bridge on the same local network.
Choose Connect Bridge and press the physical button on the Bridge when asked.
Select your lights. Color effects need color-capable lamps.
Open Light effects to set colors, blink speed and completion alerts.

Hue is optional. Bluetooth-only lights are not supported. Luma remembers a paired Bridge and reconnects. If discovery fails, check macOS Local Network permission and try the Bridge’s local IP address.

Sounds, music and voice

Sound effects and background music have independent selections and volume controls. Voice is optional. Local voice requires a one-time model download and then speaks on your Mac. OpenAI voice needs your own API key and has separate API charges. Read my replies uses a separate voice for your new messages. Never send an API key to support.

Missing updates or controls

Check that you selected the right connection and task. Keep Codex Desktop open in desktop mode; in CLI mode, check the connection status in Settings. Reconnect the Codex folder if it moved. Changes to Codex can require a Luma update. If a request is unavailable in Luma, open the task in Codex to complete it. A model’s limits and speed options come from Codex; Luma does not estimate missing quota values.

Contact Acacia Boat

Join the Acacia Boat Discord for Luma support. Include your macOS version, Luma version and a short description of what happened. Do not share passwords, API keys, Bridge credentials or private conversation files.