{"slug": "show-hn-brb-a-claude-code-plugin-for-adhdmaxxing", "title": "Show HN: Brb – A Claude Code plugin for adhdmaxxing", "summary": "Developer usebrb released Brb, a macOS-only Claude Code plugin that uses lifecycle hooks to show a break panel after long Claude turns and alert users with sound, banner, and a 'Back to work' dialog when Claude finishes. The plugin installs via 'claude plugin marketplace add usebrb/brb' and 'claude plugin install brb@brb', stores config in ~/.claude/brb/, and supports commands like 'brb park', 'brb windows', 'brb timer', 'brb matrix', and 'brb log'.", "body_md": "When Claude works, brb offers a break. When it finishes, brb calls you back.\n\nIt hangs off Claude Code's own lifecycle hooks. macOS only (it uses `osascript`\n\nfor the UI).\n\nAs a Claude Code plugin — nothing touches your `settings.json`\n\n:\n\n```\nclaude plugin marketplace add usebrb/brb\nclaude plugin install brb@brb\n```\n\nThen `/reload-plugins`\n\n, or start a new session. `/plugin`\n\ntoggles it on and off.\n\nThat is the whole install — the plugin ships the hooks, which is all brb needs.\n\nOptionally, add the `brb`\n\ncommand to your shell for `brb park`\n\n, `brb windows`\n\n,\n`brb timer`\n\n, `brb matrix`\n\nand `brb log`\n\n:\n\n```\ncurl -fsSL https://raw.githubusercontent.com/usebrb/brb/main/install-cli.sh | bash\n```\n\nThat installs a small wrapper which runs whichever plugin version is currently\ninstalled, so the command and the hooks never drift apart. A plugin's `bin/`\n\njoins\nthe Bash tool's PATH rather than your shell's, which is why this step exists.\n\nConfig, item list and logs live in `~/.claude/brb/`\n\nand are shared by both.\n\n## Installing without the plugin manager\n\n`./install.sh`\n\nwrites the hooks straight into `~/.claude/settings.json`\n\n(backing it up\nfirst) and links the CLI. Use this only if you are not using the plugin — running both\nregisters the hooks twice and everything fires twice. `./uninstall.sh`\n\nreverses it.\n\nmacOS only: the panel and alerts are AppleScript. On other platforms the hooks exit immediately and do nothing.\n\nClaude Code shares one configuration across its local surfaces, so a user-scope install covers the CLI, the Desktop app, VS Code and JetBrains at once — there is nothing extra to install per surface.\n\nThe host app is never assumed to be a terminal. brb walks up the process tree to\nwhichever `.app`\n\nowns the session and stores its bundle id, so \"Back to work\" raises\nTerminal from a terminal session, the Claude app from a Desktop session, and VS Code\nfrom an editor session. The CLI still needs a real shell, which on Desktop means the\nintegrated terminal.\n\nTwo independent things.\n\n**The break panel** — a native list you pick from. Fires on one condition: a turn\npassed the break timer (default 10s). It shows whether or not you're at the terminal,\nbecause offering the break is its whole job.\n\n**The alerts** — sound, banner, and a dialog with a *Back to work* button.\n\n| Situation | Panel | Alert |\n|---|---|---|\n| Turn finishes faster than the timer | no | no |\n| Long turn, panel shown, you ignored it | yes | no |\n| Long turn, you clicked a note item | yes | no |\n| Long turn, you clicked a site | yes | done + Back to work |\n| Claude is blocked on you and you're away | — | \"Claude needs you\" |\n| Another Claude session still busy | stays up | your alert still fires |\n\nClicking a site is the whole condition — you're called back whether or not you\nhappen to be looking at the browser when the turn ends. Also requiring you to still\nbe away made it a coin flip: glance at the terminal for two seconds at the wrong\nmoment and the alert was silently dropped. Set `REQUIRE_AWAY=1`\n\nin `config.sh`\n\nfor\nthe stricter behaviour.\n\nThe callback still requires you to have **actually left through the panel**. Seeing the panel\nand dismissing it doesn't count, and neither does a `note:`\n\nitem — those don't take you\nanywhere, so there's nothing to call you back from.\n\nAnything where Claude is *blocked on you* is deliberately exempt from that rule —\na permission prompt, a question, a link it needs opened. Gating those would mean\nstalling in silence. They still stay quiet if you're at the terminal, since you can\nalready see them.\n\n```\nbrb panel              # the real panel, right now\nbrb alert              # the real callback, right now\nbrb attention          # a \"Claude needs you\" ping\nbrb demo 20            # full flow: pick a site, then the callback 20s later\nbrb matrix             # every decision path, printed, NO UI drawn\n```\n\n`brb matrix`\n\nis the fast one — it runs each branch with `BRB_DRY=1`\n\nand prints what\neach would have done, so you can check the logic without a single popup.\n\n```\nbrb status             # config, live sessions, what's armed\nbrb log -f             # follow the decision log\nbrb timer 45s          # or set it from the panel's ⏱ row\nbrb items              # edit the panel list\nbrb off / brb on       # kill switch\nbrb doctor             # check the install\n```\n\nThe terminal that owns a session is found by walking the process tree\n(`hook → claude → shell → Terminal.app`\n\n) and stored as a bundle id. That's a fact about\nwho owns the session, not a guess about what happened to be focused when the hook ran —\nan earlier version used frontmost-app and would mis-record the terminal if you tabbed\naway at the wrong instant.\n\nBundle ids are compared case-insensitively: System Events and LaunchServices disagree on case for the same app.\n\nEdit `~/.claude/brb/items.txt`\n\n, or pick **➕ Add your own…** at the bottom of the\npanel — it opens [CONTRIBUTING.md](/usebrb/brb/blob/main/CONTRIBUTING.md), where the format is documented\nand PRs against the default list are welcome.\n\nItem icons are emoji or unicode glyphs. Color emoji render fine, but you can't supply an image file, so real brand marks aren't available — and Unicode has no X/Twitter glyph at all. A per-item logo would need a different UI surface.\n\n-\n`~/.claude/brb/items.txt`\n\n— your panel list. Created the first time you run`brb items`\n\nor pick**Add your own…** in the panel. Format is`Label|target`\n\n, where target is a URL, an`app://`\n\nscheme, or`note:some text`\n\n.Until you make one, the panel reads the list shipped with the plugin, so you keep getting new default items as they are added. Once your copy exists it takes over and updates leave it alone. Never edit the copy inside the plugin directory — that is replaced wholesale on every update.\n\n-\n`~/.claude/brb/config.sh`\n\n— optional overrides (sounds, titles). -\n`~/.claude/brb/state/`\n\n— runtime state and`brb.log`\n\n.\n\nAppleScript dialogs take no position and default to the **main** display — the one\nwith the menu bar — which is the wrong screen whenever you're working elsewhere.\n`brb`\n\npositions every dialog on the **owning terminal's** window, so the panel, the\ncallback, and the terminal that \"Back to work\" raises all land on one screen.\nAnchoring to the frontmost window instead proved unreliable during screen\nrecordings, where focus jumps between displays.\n\nYour browser is left where it lives. `MOVE_BROWSER=1`\n\nin `config.sh`\n\nwill drag it\nonto the terminal's display when you take a break, but on a single display that\nmeans it lands directly on top of the terminal, so it's off by default.\n\nNotification *banners* can't be positioned at all — macOS always draws them on the\ndisplay holding the menu bar. Move the menu bar in System Settings → Displays if\nthey appear on the wrong screen.\n\nThat reposition needs Accessibility permission. Without it everything still works, the dialogs just land on the main display. Grant it under System Settings → Privacy & Security → Accessibility for your terminal app.\n\nNotification banners need permission for \"Script Editor\" under System Settings → Notifications. A sound plays regardless, so you're never left with no signal.\n\nHooks are registered `async: true`\n\nand never block a turn. Their timeouts are generous\nonly because they cap how long the detached children — the break timer and the callback\ndialog — are allowed to live.", "url": "https://wpnews.pro/news/show-hn-brb-a-claude-code-plugin-for-adhdmaxxing", "canonical_source": "https://github.com/usebrb/brb", "published_at": "2026-09-03 04:59:41+00:00", "updated_at": "2026-09-03 05:22:11.418071+00:00", "lang": "en", "topics": ["developer-tools", "ai-tools", "ai-agents"], "entities": ["usebrb", "Claude Code", "Brb", "AppleScript"], "alternates": {"html": "https://wpnews.pro/news/show-hn-brb-a-claude-code-plugin-for-adhdmaxxing", "markdown": "https://wpnews.pro/news/show-hn-brb-a-claude-code-plugin-for-adhdmaxxing.md", "text": "https://wpnews.pro/news/show-hn-brb-a-claude-code-plugin-for-adhdmaxxing.txt", "jsonld": "https://wpnews.pro/news/show-hn-brb-a-claude-code-plugin-for-adhdmaxxing.jsonld"}}