claude must work in your terminalbrew install ffmpeg whisper-cpp plus a Whisper model. The setup wizard can install all of this for you with one button.Open the DMG and drag Merlin to Applications. First launch asks for your license key (it is in your purchase email from Lemon Squeezy), then opens a short setup wizard: it checks your machine, sets up workspaces, the talk keys, the task board folder, and optional memory. The wizard is skippable, re-runnable from settings any time.
A workspace is a project: a tab, a folder, a colour. Up to 8, switched with ⌘1-8. ⌘D opens a terminal pane in the current workspace, up to 8 panes in a grid. ⌘↵ zooms a pane full size, ⌘F searches its output, ⌘O shows every pane from every workspace at once.
Two agents share the cockpit: one for engineering, one for planning (Charlie and Alex by default). Hold the talk key and speak, or type in the panel. Start a sentence with the other agent's name to switch. They remember your recent conversation across restarts and updates.
Agents can see the pane you have focused and can drive the app: open panes, show URLs in the built-in browser (⌘B), and run full worker sessions. ⌘L opens past days' transcripts.
What they can do on your Mac. Your agents run commands and edit files on your behalf without asking first. That is what makes them useful. It also means they act on what they read: a web page, a file, or a task card can influence what an agent does next, so point them at code and content you trust, and treat anything irreversible (deletes, deploys, pushes) as yours to confirm out loud.
Two layers, two places:
~/.merlin/agents/charlie.md and alex.md. Open them in any editor, write how you want each agent to think and speak, save. Changes take effect the next time that agent starts or rolls; restart Merlin to apply them immediately.Workers have their own file. Dispatched worker sessions read an operating covenant at ~/.merlin/agents/worker.md before touching a task: stay on the brief, work on a branch, verify before claiming, write the result back to the card, stop cleanly when blocked. Edit it the same way to tune how every future worker behaves. It applies from the next dispatch, no restart needed.
Your license key arrives by email at purchase and unlocks Merlin on up to 3 Macs. Moving machines or reinstalling? Settings → About → Deactivate this Mac frees that seat first. If the license server is unreachable on first launch, Merlin can unlock for 72 hours and verify your key automatically once you are back online.
Updates arrive through the app: a gold chip appears in the status bar when a new version exists (or Merlin menu → Check for Updates), one click downloads it, restart to finish. A what's-new card shows the changes after the update.
⌘K opens the board. Every card is a markdown file in a folder you choose. Point it at a folder inside your notes vault and cards show up there too; if the folder is in a git repo, every edit auto-commits.
⌘, opens settings, organised into panes: Workspaces (projects, folders, colours), Agents (names, models, voices), Billing & keys (API keys, stored in your macOS Keychain), General (UI scale, talk key, transcript retention and Clear history), and About (version, updates, license, Deactivate this Mac, Replay tour, Run setup again). Everything saves as you change it.
Everything lives in ~/.merlin/: config, agent identities, dispatch cards, and transcripts. API keys you add are kept in the macOS Keychain, not in files. Transcripts stay on this Mac, readable by your account alone; Settings → General sets how long they are kept and can clear them all. Merlin has no accounts and sends no telemetry.
Removing Merlin completely. First free this Mac's license seat: Settings → About → Deactivate this Mac. Then delete Merlin.app from Applications and the ~/.merlin folder, and remove the "Merlin" items from Keychain Access if you added API keys. Nothing else is left behind.
Run claude once in a terminal to confirm it works, then press Recheck in the wizard. Merlin looks in your shell PATH and all common install locations (npm, Homebrew, nvm, volta, pnpm, bun, asdf).
Another app may hold that key. Pick a different global key in settings; the in-app key always works when Merlin is focused.
Voice input needs the ffmpeg and whisper tools from the wizard's first step, and macOS microphone permission for Merlin (System Settings → Privacy & Security → Microphone). Typing always works.
Panes that were mid-session resume their own conversation automatically, so the picker means that pane had nothing to pin down: a fresh pane, a session that was deleted, or Claude last started before this version of Merlin. Pick a session to continue, or press Esc for a fresh one. Session tracking works in zsh (the macOS default) and bash; in other shells, like fish, the picker is what you will see.
On a Mac you no longer use, open Merlin → Settings → About → Deactivate this Mac to free the seat, then activate on the new machine. Locked out of the old Mac entirely? Email support with your order number.
Email paul@evans-studio.co.uk. Include your macOS version and what you expected to happen.