GitHub - VoidChecksum/vibe-island: A Dynamic Island for your AI coding tools — cross-platform: macOS, Windows, Linux (Hyprland, Sway, GNOME, KDE)

What is Vibe Island?

A floating notch panel that sits at the top of your screen and monitors all your AI coding sessions — Claude Code, Codex, Gemini, Cursor, Amp, Kimi, Kiro, and more. See which agents are running, approve permissions without switching windows, and jump to the exact terminal tab with one click.

The Problem

You're running 4 AI agents across different terminals. One needs permission approval. Another finished 10 minutes ago. You're constantly switching windows to check on them.

That's 15 hours a week in context switches.

The Solution

A single floating pill at the top of your screen shows everything at a glance:

🟠 Claude is working on auth-module
🟢 Codex is idle
🟣 Gemini needs permission to run rm -rf /tmp
🔵 Cursor is writing tests

Approve, deny, or jump — without leaving your flow.

Visual Workflow

1. Launch
_{First-run setup installs hooks and shows a DMG-style guided onboarding.}

2. Watch
_{The top notch tracks sessions, subagents, tools, terminal, and elapsed time.}

🔐
3. Decide
_{Approve once, always allow, deny, answer questions, or enable Auto Mode.}

🎯
4. Jump
_{Click a row to focus the exact terminal, tab, tmux pane, IDE, or compositor window.}

Dynamic Island shape · inline permissions · terminal focus · sound alerts · labs controls · usage telemetry UI

Features

👁️ Session Monitoring See all active AI coding sessions in a compact pill. Pixel-art pet shows status. Per-session tool + terminal badges, elapsed time, and live tool activity.	🔐 Permission Approval Approve or deny tool use directly from the panel. Diff rendering for Edit/Write tools. Numbered options for Ask questions. Keyboard shortcuts `⌘Y` / `⌘N`.	🎯 Jump to Terminal Click any session to jump to the exact terminal — iTerm2, Ghostty, Warp, Kitty, Alacritty, GNOME Terminal, Konsole, WezTerm, tmux, VS Code, Cursor, and more.
🔊 Sound Effects Audible notifications when agents need attention. Custom sound packs supported.	⚙️ Smart Behavior Dwell-time auto-collapse, expand on hover, hide when empty, bypass permission pill, click-outside dismiss.	🔧 Zero Config Auto-installs hooks for all supported AI tools on first launch. Protocol `vi-e7c4`, OSC2 title caching, fallback socket path, and first-run onboarding assets from the desktop app.

Supported AI Tools

Tool	Integration	Hook Type	Status
Claude Code	Full (sessions, permissions, questions, OSC2)	Python hook	✅
OpenAI Codex	Full (sessions, permissions, app-server)	Python hook	✅
Google Gemini CLI	Full (sessions, permissions)	Python hook	✅
Cursor	Full (sessions, permissions)	Python hook	✅
OpenCode	Full (sessions, permissions, questions)	JS plugin	✅
Amp	Full (session/agent/tool events)	JS plugin	✅
Kimi Code	Full (sessions, tool events)	TOML inject	✅
Kiro	Full (session/tool events)	JSON agent	✅
Droid	Session monitoring	Config inject	✅
Hermes	Full (session/tool events)	JS plugin	✅
Windsurf	Session monitoring	URI handler	✅
Copilot	Session monitoring	Config inject	✅
CodeBuddy	Session monitoring	Config inject	✅
Qoder	Session monitoring	Config inject	✅
Cline	Session monitoring	Config inject	✅
π CLI	Session monitoring	Config inject	✅

Supported Terminals (Jump-to-Terminal)

Terminal focus uses TTY→PID resolution — works for any terminal without per-app configuration.

Terminal	macOS	Linux X11	Linux Wayland
iTerm2	AppleScript by TTY	—	—
Terminal.app	AppleScript by TTY	—	—
Ghostty	Sentinel file	`xdotool --pid`	`hyprctl` / `swaymsg`
Warp	Bundle ID activate	`xdotool --pid`	`swaymsg`
Kitty	`kitty@` remote	`xdotool --pid`	`swaymsg`
Alacritty	—	`xdotool --pid`	`swaymsg` / `hyprctl`
WezTerm	—	`xdotool --pid`	`swaymsg` / `hyprctl`
GNOME Terminal	—	`xdotool --pid`	XWayland / `swaymsg`
Konsole	—	`xdotool --pid` / `wmctrl`	KDE XWayland
foot	—	—	`swaymsg`
tmux	pane by TTY	pane by TTY	pane by TTY
VS Code / Cursor	URI handler extension	URI handler extension	URI handler extension
Hyper / xterm	—	`xdotool --pid`	XWayland

How Jump Works

Session TTY path
      │
      ▼
/proc/*/fd/0 readlink  ──► terminal emulator PID
      │
      ▼
Compositor dispatch:
  Hyprland  → hyprctl dispatch focuswindow pid:<pid>
  Sway      → swaymsg '[pid=<pid>] focus'
  KDE       → wmctrl -ip <pid>
  X11       → xdotool search --pid <pid> windowactivate
  tmux      → tmux select-pane -t <pane>
  macOS     → AppleScript / bundle-id activate

Platform Support

macOS

Native notch-aware positioning. Floats above all windows. .dmg installer. iTerm2, Ghostty, Warp, Terminal.app, Kitty support.

Windows

Always-on-top floating panel. Named pipe IPC. System tray. .msi / .exe installers.

Linux X11

xdotool --pid for universal terminal focus. AppIndicator tray. .deb, .rpm, .AppImage.

Linux Wayland

Hyprland (hyprctl), Sway (swaymsg), KDE (wmctrl), GNOME (XWayland). Auto-detected at runtime.

Hyprland Setup

Vibe Island auto-applies window rules on startup. To make them permanent:

# ~/.config/hypr/hyprland.conf
windowrulev2 = float, class:^(vibe-island)$
windowrulev2 = pin, class:^(vibe-island)$
windowrulev2 = noborder, class:^(vibe-island)$
windowrulev2 = noshadow, class:^(vibe-island)$
windowrulev2 = noanim, class:^(vibe-island)$
windowrulev2 = move 33% 0, class:^(vibe-island)$

Quick Start

Option 1 — npx (hooks only, no build required)

Install hooks for all your AI tools in one command:

npx @voidchecksum/vibe-island install

Then download the app for your platform.

Option 2 — Download

Platform	Link
macOS (universal)	Vibe Island.dmg
Windows	Vibe Island Setup.exe
Linux (AppImage)	vibe-island.AppImage
Linux (.deb)	vibe-island.deb

Option 3 — Build from source

Requires Node.js 20+ and Rust 1.88+ (see src-tauri/rust-toolchain.toml).

git clone https://github.com/VoidChecksum/vibe-island.git
cd vibe-island
npm install
npx tauri build

Platform Dependencies

Linux (Debian/Ubuntu)

sudo apt install libwebkit2gtk-4.1-dev build-essential curl wget file \
  libxdo-dev libssl-dev libayatana-appindicator3-dev librsvg2-dev libasound2-dev \
  wmctrl xdotool

Linux (Arch)

sudo pacman -S webkit2gtk-4.1 base-devel curl wget file libxdotool \
  openssl libayatana-appindicator librsvg alsa-lib wmctrl

macOS

xcode-select --install

Windows

Install Visual Studio Build Tools with "Desktop development with C++" workload. WebView2 is included in Windows 10/11.

Development

npx tauri dev
# Hook scripts auto-install on first launch
# Socket: ~/.vibe-island/run/vibe-island.sock

Build Output

Platform	Output
macOS	`src-tauri/target/release/bundle/dmg/Vibe Island.dmg`
Windows	`src-tauri/target/release/bundle/msi/Vibe Island.msi`
Linux	`src-tauri/target/release/bundle/deb/vibe-island.deb`
Linux	`src-tauri/target/release/bundle/appimage/vibe-island.AppImage`

UI Anatomy

┌──────────────────────────────────────┐
│  ▣ Vibe Island        ● 1 waiting    │  compact pill
├──────────────────────────────────────┤
│  🟠 auth-module   Claude  iTerm  12m │
│     You: refactor login flow          │
│     Edit(src/auth/session.ts)         │
│                                      │
│  ⚠ Permission Request                 │
│    Bash npm run test                  │
│    [Deny ⌘N]     [Allow ⌘Y]          │
│           Always Allow                │
└──────────────────────────────────────┘

Compact notch when idle.
Expands on hover or when a tool asks.
Parent sessions and subagents group together.
Inline approval cards render command details and file diffs.
Settings expose Behaviour, Display, Usage, Sound, CLI Hooks, Terminal, Labs, Community, Advanced.

Architecture

Data Flow

AI Tool ── hook.py/js ── ~/.vibe-island/run/vibe-island.sock ── SessionStore ── React UI
            (proto vi-e7c4)    (fallback /tmp/vibe-island.sock)       │
                                                                       ▼
                                                              Tauri emit("session-update")
                                                                       │
                                                              OSC2 cache → jump_to_terminal()

Event Types

Event	Direction	Description
`SessionStart`	Hook → App	New AI session started
`SessionEnd`	Hook → App	Session terminated
`UserPromptSubmit`	Hook → App	User sent a prompt
`PreToolUse`	Hook → App	Tool about to execute
`PostToolUse`	Hook → App	Tool completed
`PermissionRequest`	Hook ↔ App	Tool needs approval (held connection)
`Stop`	Hook → App	Session went idle

Project Structure

vibe-island/
├── src-tauri/
│   ├── src/
│   │   ├── lib.rs              App entry, Tauri commands
│   │   ├── sessions/mod.rs     Session state machine + models
│   │   ├── socket/mod.rs       Unix socket server
│   │   ├── hooks/mod.rs        Hook installer (14 tools, proto vi-e7c4)
│   │   ├── config/mod.rs       Persistent config: display, labs, usage, terminal, sound
│   │   ├── sound/mod.rs        Audio (rodio) + bundled ceremony sound
│   │   └── platform/mod.rs     jump_to_terminal(), 13+ terminals
│   ├── resources/
│   │   ├── Sounds/             Built-in notification sounds
│   │   └── terminal-focus/     VS Code extension (URI handler)
│   └── Cargo.toml
├── src/
│   ├── assets/brand/           Wallpaper, QR, icon, Departure Mono font
│   ├── components/
│   │   ├── notch/
│   │   │   ├── NotchPanel.tsx      Dynamic Island, dwell-time collapse
│   │   │   ├── SessionRow.tsx      Session row, terminal badge, bypass pill
│   │   │   └── PixelPet.tsx        Pixel-art status character
│   │   ├── approval/
│   │   │   └── ApprovalCard.tsx    Diff view, inline Q&A, ⌘Y/⌘N
│   │   ├── onboarding/
│   │   │   └── OnboardingScreen.tsx DMG-style first-run setup
│   │   └── settings/
│   │       └── SettingsPanel.tsx   Sidebar settings: usage, labs, sound, terminal, hooks
│   ├── store/useStore.ts
│   ├── types/index.ts          16 tools, all config types
│   └── styles/index.css
└── package.json

Configuration

~/.config/vibe-island/config.json:

{
  "display": { "monitor": "primary", "position": "top-center", "opacity": 0.95 },
  "layout": {
    "style": "clean",
    "show_tool_names": true,
    "dwell_time_secs": 4.0,
    "expand_on_hover": true,
    "hide_when_empty": false,
    "expand_on_subagent_done": false,
    "click_outside_dismisses": false,
    "notch_follows_active_window": false,
    "auto_configure_terminal_titles": false
  },
  "sound": {
    "enabled": true,
    "volume": 0.5,
    "pack": "builtin-8bit",
    "events": { "permission_request": true, "input_required": true }
  },
  "usage": { "show_usage_limits": true, "provider": "auto", "value_mode": "remaining" },
  "labs": { "auto_mode": false, "cursor_approval": true, "codex_desktop_alerts": true },
  "terminal": { "warp_tab_jump": true, "disable_click_to_jump": false }
}

Tech Stack

Layer	Technology	Why
Backend	Rust + Tauri v2	~5MB binary, native performance, cross-platform
Frontend	React 19 + TypeScript	Component model, strict types
Styling	Tailwind CSS + Framer Motion	Utility-first, spring animations
State	Zustand	Lightweight, no boilerplate
Audio	rodio (Rust) + bundled WAV	Cross-platform, built-in notification pack
IPC	Unix socket / Named pipe	Protocol `vi-e7c4`, `0x3A7F` compat
Terminal Focus	TTY→PID→compositor	Universal — works for all 13+ terminals
Build	Vite + Cargo	Fast HMR, incremental Rust builds

Contributing

git clone https://github.com/YOUR_USERNAME/vibe-island.git
cd vibe-island
npm install
cargo check --manifest-path src-tauri/Cargo.toml
npx tauri dev

# Type checks
npx tsc --noEmit

Footer

_{Made with ☕ by VoidChecksum · Report Bug · Request Feature}

Name		Name	Last commit message	Last commit date
Latest commit History 46 Commits
.github		.github
assets		assets
bin		bin
dist		dist
scripts		scripts
src-tauri		src-tauri
src		src
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json
postcss.config.js		postcss.config.js
tailwind.config.js		tailwind.config.js
tsconfig.json		tsconfig.json
vite.config.ts		vite.config.ts

Folders and files

Latest commit

History

Repository files navigation

What is Vibe Island?

The Problem

The Solution

Visual Workflow

Features

👁️ Session Monitoring

🔐 Permission Approval

🎯 Jump to Terminal

🔊 Sound Effects

⚙️ Smart Behavior

🔧 Zero Config

Supported AI Tools

Supported Terminals (Jump-to-Terminal)

How Jump Works

Platform Support

macOS

Windows

Linux X11

Linux Wayland

Hyprland Setup

Quick Start

Option 1 — npx (hooks only, no build required)

Option 2 — Download

Option 3 — Build from source

Platform Dependencies

Development

Build Output

UI Anatomy

Architecture

Data Flow

Event Types

Project Structure

Configuration

Tech Stack

Contributing

About

Resources

License

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages