macOS notch assistant that plugs into your MoltBot (Clawdbot) gateway. Ctrl+Space opens a glass chat popup from the notch - ask questions, attach your screen as context, and pick up the conversation anywhere MoltBot runs.
Runs as a menu bar app (✦ icon). No windows, no dock icon. Just a hotkey away.
brew install xcodegen
git clone https://github.com/moltbot/moltnotch.git
cd moltnotch
xcodegen generate
# Build app + CLI
xcodebuild build -project MoltNotch.xcodeproj -scheme MoltNotch -configuration Release -derivedDataPath build/derived
xcodebuild build -project MoltNotch.xcodeproj -scheme MoltNotchCLI -configuration Release -derivedDataPath build/derived
# Put the CLI on your PATH
cp build/derived/Build/Products/Release/moltnotch /usr/local/bin/Requires Xcode 16+ and a running MoltBot gateway (v0.8+).
# 1. Point MoltNotch at your gateway (asks URL, auth token, SSH tunnel)
moltnotch setup
# 2. Launch the app
open build/derived/Build/Products/Release/MoltNotch.app
# 3. Press Ctrl+Space - that's itYour auth token lives in ~/.moltbot/moltbot.json → gateway.auth.token on the gateway host. The setup wizard will ask for it.
On first launch, macOS will ask for Screen Recording access. Grant it, then relaunch. You'll also want Accessibility for the global hotkey:
| Permission | What it enables | Without it |
|---|---|---|
| Accessibility | Ctrl+Space hotkey | Click the ✦ menu bar icon instead |
| Screen Recording | Screenshot attachments | Screenshot sends fail with an error |
System Settings → Privacy & Security → grant both → relaunch.
| Key | Action |
|---|---|
| Ctrl+Space | Toggle popup |
| Enter | Send message |
| Tab | Toggle screenshot attachment (📷 icon appears) |
| Shift+Enter | Send with screenshot (always) |
| Ctrl × 2 | Clear visible chat (backend session preserved) |
| Escape | Stop stream → clear input → dismiss (cascading) |
~/.moltnotch.toml - created by moltnotch setup, or edit by hand:
[gateway]
url = "ws://127.0.0.1:18789"
token = "your-auth-token"
health-check-interval = 15
reconnect-max-attempts = 10
[hotkey]
key = "space"
modifiers = ["control"]
# Optional - remote gateway behind SSH
[tunnel]
host = "myserver.example.com"
user = "username"
port = 22
remote-port = 18789
local-port = 18789MoltBot always requires auth. The onboarding wizard (moltbot onboard) generates a token by default, even on loopback.
| Auth Mode | Where to find it |
|---|---|
token (default) |
gateway.auth.token in ~/.moltbot/moltbot.json, or CLAWDBOT_GATEWAY_TOKEN env var |
password |
gateway.auth.password in ~/.moltbot/moltbot.json, or CLAWDBOT_GATEWAY_PASSWORD env var |
Generate a fresh token: moltbot doctor --generate-gateway-token
MoltNotch sends the credential as both auth.password and auth.token in the connect handshake, so it works regardless of gateway auth mode.
Tip: "Gateway disconnected" right after connecting? Wrong token. Check
~/.moltbot/moltbot.jsonon the gateway host.
moltnotch doctor # checks config, TCP, WebSocket, SSH| Symptom | Fix |
|---|---|
| "Not connected to gateway" | Start your MoltBot gateway, run moltnotch doctor |
| Connects then disconnects | Wrong auth token - see Finding Your Auth Token |
| Ctrl+Space doesn't work | Grant Accessibility permission, relaunch |
| Screenshot sends fail | Grant Screen Recording permission, relaunch |
| WebSocket fails after TCP passes | Upgrade to MoltBot gateway v0.8+ |
| "Config not found" | Run moltnotch setup |
| Can't find the app | It's a menu bar app - look for ✦ in the top-right |
Want an AI agent (Claude Code, Codex, OpenCode, etc.) to walk you through the entire setup interactively? Point it at the setup prompt:
Use the instructions in SETUP_AGENT_PROMPT.md to help me set up MoltNotch and MoltBot from scratch.
The prompt covers both MoltBot gateway and MoltNotch client setup, with verification at each stage. See SETUP_AGENT_PROMPT.md.
./Scripts/build-release.sh # outputs build/MoltNotch.dmgMIT - Sohail Mohammad