brb

Take a break. Short guided breaks - breathing, neck and shoulder stretches, eye drills - running on localhost, started from your terminal.

brb

Opens a browser tab with the start screen. Everything runs locally - no account, no network, no audio files. Sound is synthesised in the browser, the figures are SVG.

Install

npm install -g @m1well/brb

Windows PowerShell blocks the npm shim brb.ps1 by default ("running scripts is disabled"). Either call brb.cmd, or allow local scripts once: Set-ExecutionPolicy -Scope CurrentUser RemoteSigned.

Commands

brb                    open the start screen
brb stats              this week, all time, longest run, 13 week heatmap
brb stop               shut the background server down

Options for brb:

• -s, --strict - the skip button stays locked for the first minute. Otherwise skip jumps to the next exercise, or to the next block when none is left.
• --no-open - print the url instead of opening a browser tab, e.g. over ssh.
• -h, --help and -v, --version.

The start screen

• Length: 2, 5, 8, 10 or 15 minutes. Arriving is on top, the clock starts once you have.
• Breathing is part of every break: a fifth of it (at least 45 seconds), or all of it when nothing else is ticked.
• Areas besides breathing: neck, shoulders, hands, stand up, eyes. Under 4 minutes one, under 7 two, under 10 three, from 10 four. Neck, shoulders and hands share one seated block, the standing exercises come after it.
• Body scan to finish: one minute including its intro, in three stages ended by a tone, from 5 minutes. The closing takes 20 seconds.
• Every exercise runs at its own fixed length. Blocks are rounded to whole exercises, never stretched - the last one may run over by up to 15 seconds when that lands closer. Whatever is left goes to breathing, so the break ends on time. Under 4 minutes one exercise per area, from 5 minutes the set may run twice.
• Language: EN or DE. ?lang=de in the url forces it for one visit.
• Sound: café (voices you cannot make out, dishes, an espresso machine, distant chords), rain (hiss in waves, drops on leaves, a puddle now and then) or off, plus volume and the cue tones.
• Breathing patterns: seven built in - coherent 6-6, calm 4-6, long exhale 7-11, box 4-4-4-4, triangle 4-4-4, 4-7-8 and a Buteyko style 4-0-7-8. They cannot be changed. "+ New" adds your own, with a name and seconds in (3-7), hold (0-6), out (3-9) and hold empty (0-9), set with plus and minus. Only your own patterns can be edited and deleted. Every pattern runs for the whole breathing part, and the one you pick is the default for next time.

Everything here is saved as you change it. There is no config file to edit - the settings live in ~/.local/share/brb/settings.json, and anything in there that makes no sense is replaced by its default on the next start.

How it runs

brb starts a static server on port 7878 (next free port if that one is taken) and opens a tab. The server stays up for 30 minutes of inactivity so the next break opens instantly, then exits. Your terminal is not blocked.

Sessions are appended to ~/.local/share/brb/sessions.jsonl, one JSON object per line:

{"ts":"2026-09-22T10:14:00.000Z","min":5,"actualSec":300,"program":"custom","breath":"coherent","done":true}

Nothing is uploaded anywhere. Delete the file and the stats are gone.

Development

npm install
npm run build          # astro build into packages/cli/web, then tsc for the cli
npm run dev            # astro dev server, api calls fall back to demo mode (stats in localStorage)
node packages/cli/dist/index.js --dev   # every exercise and eye drill once, to check them

Release: bump version in packages/cli/package.json by hand (npm version reflows its arrays), add a section to CHANGELOG.md, then npm run build - the start screen shows the version and opens the changelog from it.

MIT

Author

@m1well