Getting started with Mastlight.

Thank you for trying it. This takes about ten minutes, most of it the download. One step, the first open, is a little unusual, so it gets the most space.

  1. Before you start

    • A Mac with Apple silicon. That is any Mac from late 2020 on (M1 or newer). Apple menu, About This Mac, shows a chip name starting with M.
    • macOS 13 (Ventura) or newer. Mastlight is built on Electron 44, and the app itself declares macOS 13 (Ventura) as its lowest supported system.
    • Claude Code 2.1.85 or newer. In Terminal, claude --version tells you. If you do not have it, the Claude Code docs explain how to install it.
    • A Claude subscription. You sign in with your own. Mastlight never sees your password or token.

  2. Download

    Download Mastlight 1.0.3 for Mac

    Version 1.0.3 · 147.5 MB · Apple silicon · release page

    Want to be sure the file is the one we built? Its SHA-256 is below. This is optional.

    7007b9bfc26429dc23f94ba1057395a632cc8cc237471aa47b371b74a16ca646

    To check it, run this in Terminal and compare the first long string it prints:

    shasum -a 256 ~/Downloads/Mastlight-arm64.dmg

  3. Install

    1. Open Mastlight-arm64.dmg from your Downloads folder. A window appears with the Mastlight icon and an Applications folder.
    2. Drag Mastlight onto Applications.
    3. Eject the disk image (the eject button beside it in Finder’s sidebar) and, if you like, delete the DMG.

  4. First open

    Mastlight is not signed by Apple yet. It is signed only with a local, ad-hoc signature and has not been through Apple’s notarisation, so macOS holds back anything it cannot vouch for the first time. That is Gatekeeper doing its job; it says nothing about what the app does. You only do this once.

    1. Open Mastlight from Applications (or Launchpad). macOS will say it cannot verify the app, with a choice such as Done or Move to Trash. Choose Done. Do not move it to the Trash.
    2. Open System Settings, then Privacy & Security, and scroll down to the Security section.
    3. You will see a line saying Mastlight was blocked, with an Open Anyway button. Click it. If it is missing, try opening Mastlight once more, then look again.
    4. Confirm with your password or Touch ID. macOS asks once more; choose Open Anyway there too.
    “Mastlight” was blocked to protect your MacOpen Anyway
    A sketch of where to look, drawn for this page. Your Mac’s own wording may differ a little.

    On macOS 15 and later, right-clicking the app and choosing Open no longer gets past this. Older advice that says so is out of date. After this first time, Mastlight opens like any other app.

    If you would rather use Terminal

    This does the same job: it removes the quarantine mark macOS put on the download. Run it once, then open Mastlight normally.

    xattr -dr com.apple.quarantine /Applications/Mastlight.app

    It touches only Mastlight. The System Settings route above is the usual one.

  5. Setup

    Four short steps, and every one can be skipped. Settings has Run setup again if you change your mind.

    1. Welcome.
    2. Find Claude Code. Mastlight asks your login shell where claude is, so it finds the same one your Terminal does, and shows the version.
    3. Accounts. It offers the sign-ins already on your Mac, or you add one with Claude’s own /login in a terminal inside the app. Mastlight never sees a credential.
    4. Start your first session.

  6. Your first five minutes

    • ⌘ N starts a session: pick a folder and an account.
    • When a session needs you it moves to the top of the sidebar, and ⌘ J jumps straight to it.
    • ⌘ K opens the command palette: search sessions and run commands.
    • Permissions, plans and questions show up as cards, with the real command or question on them. Answer with a key or a click.
    • A session opens in its Conversation. ⌘ E flips to the Terminal and back.
    • Already have Claude Code running in Terminal, iTerm or tmux? They appear as External. File, Import sessions… moves them in: Claude exits in the old tab and the same conversation resumes in Mastlight.

    That is it. You are set. All quiet until a session needs you.

  7. Updates

    When a newer version exists, Mastlight shows a banner and links to this page. It never downloads or installs anything by itself. To update, download again from step 2, quit Mastlight, and drag the new app onto Applications, replacing the old one. Sessions that are running keep running while you do it.

  8. Uninstall

    In Settings, Uninstall Mastlight… (two confirmations) removes the app’s data, its logs and its background helper, then moves the app to the Trash. It does not touch ~/.claude*, your Claude sign-ins or other apps.

  9. Trouble?

    Mastlight cannot find Claude Code

    Mastlight asks your login shell for claude, the same way a new Terminal window would. If claude --version works in Terminal but not here, the folder that holds claude is probably added to your PATH in a place only Terminal reads. Move that line into your login shell’s startup file (for zsh, ~/.zprofile), open a new Terminal, check again, then restart Mastlight.

    macOS says Mastlight is “damaged”

    It is not; this is the same Gatekeeper hold with a harsher message. Run this once in Terminal, then open Mastlight again:

    xattr -dr com.apple.quarantine /Applications/Mastlight.app
    No cards appear, even when a session is asking

    If your Claude Code is set to bypass permissions, its sessions never ask, so there is nothing to show as a card. In the New session sheet, choose Ask before acting. That starts that one session in the default permission mode. Your own Claude settings are not read or changed.

    Anything else, or something odd: if someone sent you this link, tell them. Otherwise, open an issue on GitHub.

Everything runs on your Mac. No account with us, no telemetry. The one request the app makes by itself is a once-a-day check for a newer version, which you can switch off in Settings.