drip is a command that shows a card at your Mac's notch. Call it from a script, a build or a shell hook to say that something finished, failed or needs an answer.
No Notifications permission: drip draws its own card, not a Notification Center banner. drip returns at once, so it never slows the script that calls it. On a Mac without a notch, the card grows out of the top edge of the screen.
Recipes · Docs · drip.jrnxf.co
- One command, any script.
drip ok "deployed"shows a green card with an icon, a sound and a countdown. - Wraps commands.
drip run make testshows how it went and how long it took, and keeps the exit code. - Questions.
--yes Deploy --no Cancelwaits for a click. It exits 0 for yes, 1 for no and 5 for no answer. - Slow shell commands. A zsh recipe gives a card to any command that runs 10 seconds or more.
- Coding agents. Recipes for Claude Code, Codex and Gemini CLI call
drip hookto show a card when the agent needs you. - Remote machines. A Linux box you reach over ssh can raise its cards on your Mac.
- Cards wait while the screen is locked. They play back when you return.
Requires macOS 13 or newer. Tested on macOS 15 and 26.
brew install jrnxf/tap/drip
drip ok "hello"A green card grows out of the notch. Homebrew installs a prebuilt universal binary for Apple silicon and Intel, with no Xcode needed. To build from source, see docs/install.md.
# A card
drip "build finished"
# A kind and a detail line
drip ok "tests passed" -d "246 passed in 3.2s"
# The first line of stdin is the title, the rest the detail
git log -1 --format='%s%n%an' | drip ok
# Replace a card in place
drip info "deploying" --id deploy
drip ok "deployed" --id deploy
# Ask a question (exit 0 yes, 1 no, 5 no answer)
drip warn "Deploy to prod?" --yes Deploy --no Cancel && ./deploy.shdrip --help lists every option. docs/usage.md is the full reference, and
docs/contract.md lists what scripts can rely on.
Put drip run in front of any command. It shows a green card on exit 0, or a red one with the exit
code, then exits with the command's own status, so scripts and && chains work as before.
drip run make test
drip run --open "$CI_URL" --button "View run" ./deploy.shTo skip typing it, the zsh-slow-commands recipe is a block for
~/.zshrc. It gives a card to any command that runs 10 seconds or more, only when you are not
watching that terminal.
drip hook turns an agent's hook event into a card. drip gives you hooks and recipes, not automatic
integrations. A recipe is a settings snippet that picks the events that show a
card. Copy one into the agent's settings and adapt it.
| Recipe | When it notifies |
|---|---|
| Permission cards (suggested) | When the agent needs you, and nothing else |
| Attention | Also when an error ends a turn |
| Everything | Also a done card for every turn |
| Long turns | As Everything, but no done card for a turn under 30 seconds |
| Approve from card | As Permission cards, with Allow and Deny on the card |
| Orchestrator | Many sessions at once: cards from the one you talk to, not its workers |
Start with Permission cards. It has the hooks for Claude Code, Codex
and Gemini CLI. recipes/ also has click recipes for herdr, WezTerm and Ghostty,
and examples for Aider and opencode. docs/coding-agents.md is the reference
for drip hook, drip watching and DRIP_HOOK.
To show the cards of an agent on a Linux box you reach over ssh, with no drip there, see docs/remote.md.
A click on a card brings its terminal forward. Add --on-click CMD to run a command on a click too.
The click recipes focus a pane in herdr or WezTerm, or a Ghostty window on
another Space.
Cards that come up while the screen is locked wait for the unlock, then the last five play back and the rest sum up as one card. For a meeting or a screen share, hold them yourself:
drip pause 30m # hold every card; drip resume ends it early
drip history --missed # what came up while you were away
drip dismiss # take the cards on screen away, without going to the terminaldrip does not follow Focus, since reading it would take a permission, so drip pause is how you
keep cards out of a screen share.
Every key is optional, in ~/.config/drip/config.toml:
size = "regular" # compact | regular | large
stack = "chain" # chain | push | off: how cards stack
[preset.deploy] # a look of your own: drip deploy "shipped"
icon = "paperplane.fill"
color = "#a78bfa"
sound = "Submarine"docs/config.md lists every key and its DRIP_* environment variable.
| drip | terminal-notifier, osascript, alerter | |
|---|---|---|
| Shows | its own card, from the notch | a Notification Center banner or alert |
| Permission | none for a card | Notifications |
| Focus and Do Not Disturb | shows anyway; drip pause holds cards |
follows Focus |
| Kept afterwards | drip history |
Notification Center's list |
| Wraps a command | drip run: status, exit code and time |
no |
- Install, from source, and uninstall
- Recipes: when agents notify, and clicks for herdr, WezTerm and Ghostty
scripts/tour.sh: a 10-step tour of the cards, run with Next and Stop cards at the notch- Troubleshooting: no card, permissions, privacy and the debug log
- Development: tests, the live agent check, releases and the web page
- drip.jrnxf.co: guides for Claude Code notifications and alerts when a command finishes
drip makes no network connections of its own and collects no analytics. The one connection is the
ssh that drip follow runs. See Privacy.
MIT