Islet

A Dynamic-Island-style notch for Windows 10 and 11

Music · Claude Code and Codex · notifications · battery · weather, all in one small black pill at the top of your screen.

Pill

Notification

Album view

Features · Install · Usage · Claude Code & Codex · Settings · How it works · 📘 Full guide (PDF)

Islet sits at the top centre of your screen. Hover to open it, click anywhere else to close it. When nothing is happening it shrinks to a plain black pill with one dot.

The open notch, left to right: agent sessions → music → time and battery → tools.

✨ What's new

• 👋 Version 2.1: a welcome screen that asks before Islet changes anything, an installer with setup screens, authenticated agent hooks, a wave for the player on show and lighter background work.
• 📦 Version 2.0: 14 reliability fixes, a ready-made installer and redrawn player controls.
• 🌌 Black hole charger animation: an Interstellar-style black hole plays when the charger goes in (CHARGING INITIATED) or out (RUNNING ON BATTERY). You can pick Cinematic or Subtle, or turn it off.
• 💬 Full notification text: pop-ups are wider, grow up to about 7 lines and stay on screen longer for long messages.
• 🔒 Lock screen: Windows' own banners come back while the PC is locked, so you still see messages there.
• 🛡️ Sturdier: Alt+F4 no longer kills the notch, and a broken config.json is never overwritten. This round also fixed calendar exceptions, shelf duplicates, banner recovery, UTF-8 output and more.

🚀 Features

📦 Install

You need: Windows 10 1903+ or 11 · Windows PowerShell 5.1 (built into Windows)

Download the installer

Get Islet-Setup-<version>.exe from the latest release and run it. It adds a Start menu entry and installs to %LOCALAPPDATA%\Programs\islet. Islet doesn't update itself, so to update, install the new version.

[!NOTE]
The installer is unsigned. SmartScreen may warn about it, and Smart App Control may block it. If it's blocked, run from source instead.

Run from source

You also need: Node.js 22 or 24 (a supported LTS release) · Git

git clone https://github.com/goprocker/Islet.git
cd Islet
npm install
npm start

Code changes apply on restart. To build your own installer, run npm run dist, then run dist\Islet Setup <version>.exe.

[!TIP]
Run npm run dist from PowerShell. It fails under Git Bash.

Only one copy of Islet runs at a time, so quit the npm start copy before installing.

On first run, a welcome screen asks about Start with Windows, notifications and the agent hooks. Islet changes none of them until you click Continue. Right-click the tray icon for the menu.

🖱️ Usage

🤖 Claude Code and Codex

The welcome screen offers to install the hooks. Tray → Connect to Claude Code and Codex removes or adds them later. Adding saves a backup next to each file, and only Islet's own handlers are ever removed.

[!IMPORTANT]
The hooks run with node, so Node.js must be on your PATH, even with the installed app. They also point at the copy of Islet that installed them. If you move that folder or switch between source and the installed app, untick and tick the option again in the copy you're using.

• Claude Code: hooks go into ~/.claude/settings.json (backup: settings.json.islet-backup). hooks/islet-hook.js POSTs each event to 127.0.0.1:47321/claude.
• Codex: if ~/.codex exists, hooks are also added to ~/.codex/hooks.json (backup: hooks.json.islet-backup). Codex asks you to trust new hooks, so approve Islet's once, through the prompt Codex shows or /hooks.
• A Claude Code permission request is held for permissionWaitSeconds (default 8). If you don't answer in the notch, the terminal asks as usual. Set it to 0 to never hold.
• Codex permission requests show "Needs you", but you answer them in Codex.
• With both agents running, the status line says Claude · or Codex ·, and Codex chips have a blue dot.
• Without hooks, Islet guesses the status from the newest transcript in ~/.claude/projects.

⚙️ Settings

Stored in %APPDATA%\islet\config.json and edited from the settings window. Hand edits are picked up within 2 s. A file that can't be read is left alone, not overwritten.

🧠 How it works

main.js ── window, tray, hotkeys, powerMonitor, config, IPC
 ├─ helpers.ps1           one PowerShell that runs the three watchers below
 ├─ media.ps1             Windows media session → JSON every second; play/seek/next
 ├─ spotify-audio.ps1/.cs process-loopback capture of Spotify → 24 FFT bands, volume
 ├─ system.ps1            mic / camera / screen use, fullscreen detection
 ├─ notifications.js      reads wpndatabase.db (node:sqlite, read-only); toggles banners
 ├─ icons.js              real app logos (Store manifests, shortcuts, exe icons)
 ├─ claude-bridge.js      HTTP server for Claude Code + Codex hooks; installs/removes them
 ├─ calendar.js  weather.js  lyrics.js  downloads.js  shelf-file.js  spotify-web.js
 └─ preload.js ── renderer/  (index.html, notch.css, notch.js, blackhole.js)
                  settings/  (settings window)

• The window is frameless, transparent and always on top. It ignores the mouse except while the pointer is over the notch.
• Notch states are CSS classes on #notch: open, toast, hidden, quiet, idle, charging. With reduced motion on, the animations stay still.
• The black hole is drawn with Canvas 2D (renderer/blackhole.js) and driven by Electron powerMonitor events, with no polling. It only animates while playing.
• C# runs through Add-Type inside PowerShell, so no unsigned exe ships, which keeps it working with Smart App Control on.
• Windows has no notification-listener API for unpackaged apps, so Islet reads the notification database read-only.
• To hide Windows' banners, Islet sets ShowBanner = 0 under HKCU\…\Notifications\Settings\<app id>. The previous values are saved in %APPDATA%\islet\banners.json and put back on quit or at the lock screen.

🛠️ Develop

npm test     # 27 test files, node --test
node_modules\electron\dist\electron.exe . --remote-debugging-port=9333   # then chrome://inspect

Useful page globals: setOpen(true), render().

🔐 Privacy

Everything runs on your PC. Network calls go only to lrclib.net (title and artist, when lyrics are on), Open-Meteo (the city name), your ICS link, and Spotify if you connect it. Clipboard history never touches disk, and the shelf stores file paths only. The hook server listens on 127.0.0.1 only.

🩺 Troubleshooting

🗑️ Uninstall

1. Tray → untick Connect to Claude Code and Codex and Start with Windows.
2. Tray → Quit (puts Windows banners back).
3. Installed app: Settings → Apps → Islet → Uninstall. From source: delete the folder.
4. Delete %APPDATA%\islet.

🤝 Contributing

Issues and pull requests are welcome. See the contributing guide and Code of Conduct. Report security problems through the security policy, not a public issue.