macOS notifications for Claude Code in VS Code. Know which session is done, needs your permission or has a plan ready, even while you are in another app, and jump straight to its exact VS Code terminal tab with one click.
curl -fsSL https://raw.githubusercontent.com/LucaL1fe/claude-code-alerts/main/install.sh | bashOne command installs the menu bar app, the Claude Code hooks and skill, and the VS Code extension. Free and open source (MIT). macOS 14+.
Running four Claude Code sessions in parallel is great until you lose track of them. Claude Code's own notifications don't reach the VS Code terminal, Focus mode swallows banners, and every tab looks the same. You end up clicking through tabs to find the one that has been waiting for you for ten minutes.
Claude Code Alerts fixes exactly that:
- You notice it. A pill under the notch and a sound, drawn on top of every app and every desktop. It still shows when Focus / Do Not Disturb is on.
- You know who. The pill says which session and what happened:
checkout-refactor · Validation added, all 3 tests pass. - You land in the right place. Click the pill and VS Code comes to the front, on the right desktop, with that exact terminal tab focused.
Click the menu bar icon: every alert, most urgent first (orange needs you, purple plan ready, green done). The icon takes the color of the most urgent item and shows how many are waiting. Open a row to see more, act on it, or go straight to its terminal tab. Below the alerts, every session sits in the same folders as in VS Code's Claude Sessions view (click a folder to open or close it; it is colored when something inside waits), with the same right-click menu: New Session, New Folder, Go to Session, Set State, Move to Folder, Rename, Close Session; folders also have Move Up / Move Down and Delete. Close Session (also the trash on a session row in VS Code) closes its terminal tab, which ends Claude; while Claude is still working it asks first.
Each session's terminal tab gets a colored dot: 🟢 done, 🟠 needs you, 🟣 plan ready, 🔴 error. Once you have looked at it, it goes back to Claude's own title.
The Claude Sessions view in VS Code's Explorer lists every running Claude session with its live state and what it is doing. Click one and you are in its terminal. The status bar shows how many are waiting.
Start a new session with + in the view's title bar, or right-click a folder or session for New Session and New Folder:
it opens a terminal tab that runs claude and lands in that folder. Sort sessions into your own folders, like files in
the Explorer: drag sessions and folders onto a folder, or right-click → Move to Folder… / Move to Top Level. Hover a
folder for New Session, Rename and Delete (what was inside moves up a level); hover a session for Rename and Remove
from List (it keeps running and comes back as soon as you write to it or it needs you). Right-click a session →
Set State ▸ Needs You / Plan Ready / Done / Idle marks it yourself, as a reminder for later (no pill, no sound): Needs You
and Plan Ready stay until you write to it, Done goes when you open it (like an unread mail), Idle clears it. Sessions are listed most urgent first, then
the one you wrote to last; your folders sit below them (setting claudeCodeAlerts.foldersPosition puts them on top), in
your order: right-click → Move Up / Move Down, or Alt+↑ / Alt+↓. Each folder shows how many sessions it holds. A session that needs you colors its name and every folder
above it, so a collapsed folder still shows that something inside waits. A resumed session (or one started again after
/clear in the same tab) comes back to its folder.
Restart without losing your sessions. When VS Code updates or your Mac restarts, VS Code reopens your terminal tabs
but Claude is no longer running in them. The extension remembers which tab ran which session and resumes each one in its
old tab (claude --resume <id>, in the same folder), with its name and its folder in the view. Sessions you ended
yourself stay ended. Turn it off with claudeCodeAlerts.restoreSessions; what it did is in the Output panel under
"Claude Code Alerts".
When a session stops at your 5-hour or weekly usage limit, it waits with a ring dot and the time it goes on
(Usage limit · continues at 04:02). A moment after the limit resets, Claude Code Alerts types a short continue message
into its VS Code terminal tab, so a long job keeps running overnight instead of waiting for you until morning.
- It does nothing if the session already went on: Claude Code continued by itself, or you wrote to it.
- Claude Code has its own automatic continue, but it doesn't start while Remote Control is on. This one works either way.
- The reset time comes from fields Claude Code writes for itself (its status line input and the transcript, including those of background agents), never from message text, so it works in any language and any time format.
- A session that runs outside a VS Code terminal tab, or whose reset time isn't known, gets an alert instead: when it stops, and again when the limit resets.
- Switch it off in Settings, or right-click a waiting session in the menu bar list › Don't Continue by Itself.
The clock button brings an alert back in 5 minutes (change it in Settings). While you are away (screen locked, display asleep or idle) alerts wait quietly; when you are back you get one "While you were away" summary with a single sound.
When a session drives your Mac (computer use), a thin red ring stays around the screen so you keep your hands off, and a short green glow tells you when you can type again. The ring lets every click through. (This is the only glow: other alerts are just the pill and a sound.)
The skill teaches Claude the cca command: "rename this tab to release-checklist", "if you need my password, notify
me". Claude does it, and the pill shows Claude's own words.
| Pill on every app, every desktop, full screen apps, Focus on | Menu bar icon colored by the most urgent waiting item, with a count |
| Exact VS Code terminal tab, on the right desktop, in one click | Colored dot in each terminal tab title: 🟢 🟠 🟣 🔴 |
| Claude Sessions view and status bar item inside VS Code | Works with several VS Code windows and desktops |
| States: working, needs you, plan ready, done, error, using your Mac | Per pill: quiet ✕, later 🕒, done ✓, go to → |
| No alert when you are already looking at that tab | Snooze time, sound, voice and the Mac ring are separate switches |
| Away detection with one summary when you are back | Rename sessions right in the pill (✎) or by asking Claude |
Claude can ping you itself: cca notify --needs-you "…" |
Works with the Claude Code CLI in any terminal; best in VS Code |
| Sessions continue by themselves after a usage limit resets | Your usage limits in Claude Code's status line |
curl -fsSL https://raw.githubusercontent.com/LucaL1fe/claude-code-alerts/main/install.sh | bashThe installer:
- builds the menu bar app from source (about a minute, needs the Xcode command line tools) or downloads the latest
release, and puts it in
/Applications; - links the
ccacommand to~/.claude-code-alerts/bin/cca; - adds the hooks and a status line to
~/.claude/settings.json(a backup is saved next to it, your other settings stay untouched; a status line you already have keeps showing exactly as before) and the skill to~/.claude/skills/claude-code-alerts; - installs the VS Code extension and starts the app.
Then reload your open VS Code windows once:
Cmd+Shift+P› Developer: Reload Window. VS Code only loads a newly installed extension after a reload. Your terminals and Claude sessions keep running.
Running sessions pick up the hooks by themselves. Run the same command again to update.
Uninstall: ~/.claude-code-alerts/uninstall.sh removes the app, hooks, skill and extension and keeps the rest of
your settings exactly as they were.
As a Claude Code plugin: the hooks and the skill are also available as a plugin
(/plugin marketplace add LucaL1fe/claude-code-alerts), but you still need the app from the installer.
Claude Code session ──hooks──▶ cca ──socket──▶ Claude Code Alerts.app ──▶ glow, pill, menu bar, sound
│
└──socket──▶ VS Code extension ──▶ focuses the terminal tab
- Hooks (
Stop,StopFailure,Notification,PermissionRequest,PreToolUsefor plans, questions and computer use,UserPromptSubmit,SessionStart,SessionEnd) callcca hook. They run asynchronously and never slow Claude down. - The status line (
cca statusline): Claude Code hands its status line your usage limits with their exact reset times.ccapasses them to the app, then prints your own status line if you had one, else a short5h 53% · resets 12:50 · week 30%. ccafinds the session's terminal by walking up the process tree (hook → claude → the terminal's shell) and reads the session name from the transcript.- The app (Swift, AppKit + SwiftUI) keeps the state, applies the rules (urgency, smart suppress, away, snooze) and draws the overlays as non-activating panels on every Space.
- The VS Code extension reports which terminals each window has (by shell PID) and focuses one when the app asks. Clicking a pill first brings that window forward, so macOS switches to its desktop.
- Tab dots are a terminal title (OSC 2) the app writes to the session's terminal; Claude replaces it with its own spinner as soon as it works again.
Everything stays on your Mac. No network, no analytics.
The installed skill lets Claude use these itself; you can run them too:
cca notify --needs-you "Enter your Mac password in the keychain prompt"
cca notify --done "Build finished" # also --plan, --error
cca rename "checkout-fix" # pill, list and VS Code tab
cca mac start "Typing a reply in Mail" # red ring; computer use turns it on automatically
cca mac end # green "Mac is free"
cca status # all sessions and connected VS Code windowsClick the menu bar icon › Settings: Later button (1 min to 1 h, default 5 min) · fold pills away after a while (default never) · colored dots in tab titles · continue by itself after a usage limit resets · usage limits in the status line · sound · voice (says who and what happened, off by default) · red ring when Claude uses your Mac · when you count as away · open at login.
Where does "go to" take me? Always to where the session already runs, never somewhere new:
| Session runs in | Go to |
|---|---|
| a VS Code terminal | the exact terminal tab, in the right window, on the right desktop |
| the Claude Code panel (VS Code extension) | that panel tab (VS Code asks once to allow the link) |
| the Claude desktop app | brings the Claude app forward |
| iTerm, Ghostty, Terminal, … | brings that app forward |
the background (claude -p, scheduled tasks, scripts) |
nothing to jump to: listed quietly, a pill only on errors |
Why no pill from the Claude app? With the Claude app in front, the session you last wrote to there finishing gets no pill: you are looking at it (like the VS Code tab in front). A scheduled task of the Claude app finishing a run gets none either; a question or an error from it still does, and once you write in that session it alerts like any other.
Why does it set my status line? Claude Code gives the exact reset times of your usage limits only to the status line, and the app needs them to continue a session when the limit resets. If you had a status line, ours runs it and prints its output unchanged; uninstalling puts it back. Without one you get a short usage line (switch it off in Settings: the line stays empty).
Does it work without VS Code? Yes. Alerts, the menu bar and cca work with Claude Code in any terminal. Only the
exact-tab jump and the Claude Sessions view need VS Code.
Where is the icon? Can I move it? It starts next to the system icons on the right. Hold Cmd and drag it anywhere in the menu bar; the position is remembered. If you use a menu bar manager (Ice, Bartender), make sure it is not in the hidden section.
Is this made by Anthropic? No. It is a community project and not affiliated with Anthropic. "Claude" is a trademark of Anthropic.
Contributions are very welcome. The goal is a small, polished ecosystem around running many Claude Code sessions in parallel: better terminal support (iTerm2, Ghostty, Warp), approvals from the pill, a phone push when you are away, themes. See CONTRIBUTING.md to get started, and open an issue with ideas.
The idea of matching a session's shell PID to a VS Code terminal comes from dimokol/claude-notifications (MIT). Thanks to the notch apps (Vibe Island, CodeIsland, Vibe Notch) and cmux for showing what good agent status UX looks like.
MIT © LucaL1fe and contributors