Something off?
Let’s fix it.

System requirements

• macOS 26.0 or later
• Apple Silicon (a Mac with an M-series chip)
• Apple Intelligence is optional: with it, notes and the status line get fresh wording; without it, Zerre uses its own written lines

Install

Three ways, all the same signed and notarized app. Each one also gives you the zerrectl command for your terminal.

Download

Get the DMG from the releases page, open it, and drag Zerre to Applications.

Homebrew

brew install --cask darkbringer1/tap/zerre

One line in Terminal

curl -fsSL https://zerre.dogukaan.dev/install.sh | sh

The script downloads the latest release, checks its checksum, Developer ID signature and notarization, installs Zerre to Applications and opens it. It never asks for your password. It links zerrectl into ~/.local/bin and tells you if that folder isn't on your PATH yet.

Getting started

Click Zerre’s menu bar icon to open its state card. Open Settings… there to choose its home, connect your tools and adjust focus sessions.

Choose its home

Open Settings → Zerre → Lives in and choose Desktop, Notch or Dock. On the desktop, Home by the notch controls whether Zerre also has a room at the top of the screen. Turn it off to keep notes on a small board beside the creature.

In Dock mode, Zerre becomes the app’s Dock icon. Click it to read its signs; right-click for focus and notes. It hides when the Dock hides.

Connect your tools

Open Settings → Connections → Hooks to connect Claude Code, Codex, Gemini CLI, OpenCode, git or zsh. Connect Calendar on the state card lets Zerre stay quiet during meetings. Settings → General → Open at login starts it when you sign in to your Mac.

Start a focus session

Use the focus button on the state card to start your configured session, or choose Just 5 min for a short block. You can also right-click the desktop creature and choose Start focus session.

In Settings → Focus, set block lengths, breaks and the number of blocks in a session. Under Calm the rest, choose Off, Behind the front window or All but apps I let in. The last option blocks clicks in other apps; drag Zerre onto a window to let that app in. Blur and Darken adjust the effect while it is enabled.

Use Stop session on the state card to end a session. During a break, the card offers a button to start the next block and End session to finish.

Right-click the desktop creature for notes, or triple-click it to write one.

Common issues

"Zerre can't be opened because it is from an unidentified developer"

Gatekeeper didn't see the notarization ticket. The download is notarized and stapled; if this still appears, re-download it from the releases page (the DMG may have been cut short), or run xcrun stapler validate Zerre.app.

My agent finished but Zerre didn't notice

Check Settings → Connections → Hooks: the agent should show Remove (installed). Agents only pick up new hooks in new sessions, so restart the agent after installing. OpenCode needs a restart to load its plugin.

Clicking a note doesn't bring my terminal forward

For Terminal and iTerm, allow Zerre under System Settings → Privacy & Security → Automation. Other terminals (Warp, Ghostty, VS Code) come forward as an app; they don't let other apps pick a specific tab.

It's hiding at the edge of the screen

It hides during meetings. If the meeting ended early, click it and choose Meeting's over.

Report a bug

Open a GitHub issue with your Zerre version, macOS version and Mac model, and the steps to reproduce. If you'd rather write privately, email [email protected]. Please don't send your event log or notes: they're not needed, and we don't want them.

Updates

Zerre checks for updates automatically through Sparkle, and you can check on demand from the menu bar card. That covers Homebrew installs too: brew upgrade leaves Zerre alone unless you add --greedy. Running the install script again also updates it.

Your data

Everything Zerre notices stays on your Mac. Settings → Your data can export it all as JSON, or erase it so Zerre starts over as a tiny sprout (your hooks and settings stay).

Uninstall

Open Settings → Your data → Remove Zerre from this Mac. It removes its hooks from your coding agents, git and zsh (your own hooks stay exactly as they were), turns off Open at login, deletes its data and settings, and quits. Then drag Zerre from Applications to the Trash, or if you installed it with Homebrew, run brew uninstall --cask zerre. The install script's ~/.local/bin/zerrectl link goes away with Remove Zerre.

If you've already deleted the app: remove its hooks by hand (entries mentioning Zerre/bin/zerrectl, and the # zerre-hook block in ~/.zshrc), run git config --global --unset core.hooksPath if it points into Zerre's folder, then delete ~/Library/Application Support/Zerre and ~/Library/Preferences/com.dogukaan.zerre.plist.