github.com/NetVar1337/vibe-island @v1.0.0

---

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.**

---

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.

---

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	✅

---

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

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

---

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 (14 fields)
│   │   ├── sound/mod.rs        Audio (rodio)
│   │   └── platform/mod.rs     jump_to_terminal(), 13+ terminals
│   ├── resources/
│   │   └── terminal-focus/     VS Code extension (URI handler)
│   └── Cargo.toml
├── src/
│   ├── 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
│   │   └── settings/
│   │       └── SettingsPanel.tsx   All toggles + uninstall
│   ├── store/useStore.ts
│   ├── types/index.ts          14 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 }
}

---

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)	Cross-platform, pure Rust
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

---

<img alt="Footer" src="https://github.com/NetVar1337/vibe-island/raw/v1.0.0/assets/footer.svg" width="900" />

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