Skip to content
blublu

Install

Requirements

Section titled “Requirements”
  • macOS 27 on Apple Silicon.
  • Xcode 27, to build the app from source.
  • An OpenAI API key — the command parser and the voice (GPT-Live) use it.
  • For real work: Claude Code and/or Codex with their ACP adapters (Node.js and npm).

Without an agent installed you can still try everything with the built-in test agent.

Build the app

Section titled “Build the app”
Terminal window
git clone https://github.com/artipop/blu.git && cd blu
open blu.xcodeproj    # first time: ⌘B, then "Trust & Enable" for the package macros
scripts/install.sh    # builds the Release app into /Applications

scripts/install.sh puts blu into /Applications. The Debug build from Xcode is a separate app, blu dev, with its own data — handy for trying things out without touching your everyday projects.

Add the OpenAI key

Section titled “Add the OpenAI key”
  1. Open the settings: ⌘, → Voice.
  2. Paste the key. It is stored in the macOS Keychain, never in a file or in iCloud.

The same key serves the voice and the command parser. Without a key or network, commands don’t run and blu tells you why.

Install the agents

Section titled “Install the agents”
Terminal window
npm i -g @agentclientprotocol/claude-agent-acp @agentclientprotocol/codex-acp

You also need the CLIs themselves, claude and/or codex. blu looks for them in the PATH of your interactive login shell, so nvm and Homebrew installs are found.

Sign in once in Terminal:

Terminal window
claude      # then /login
codex login

The project editor shows whether each adapter was found and has a Sign in in Terminal button. blu never reads your tokens: the agents keep them.

Next: first steps.