Vibe Island — App Decomposition & Mac Build Spec

Overview

What Vibe Island does and why it matters.

6

AI Agents

13+

Terminals

50MB

RAM Usage

$19.99

Price

The Problem

When running AI coding agents (Claude Code, Codex CLI, Gemini CLI), developers constantly context-switch to the terminal to check status, approve permissions, and review output. Vibe Island surfaces everything in the notch.

🤖 Supported AI Agents

Claude Code (Anthropic)
Codex CLI (OpenAI)
Gemini CLI (Google)
Cursor Agent
OpenCode
Factory Droid

💻 Supported Terminals

iTerm2 (incl. tmux -CC)
Ghostty 1.3+
Terminal.app
Warp, Alacritty, Kitty
VS Code, Cursor, Windsurf
+ 4 more via VSIX extension

🔒 Privacy Model

100% local — Unix socket IPC only
No data sent to any server
No account required
No cloud dependency

Feature Decomposition

Every feature, organized by category.

Core Agent Monitoring & Control

Multi-agent monitoring — Unified notch panel for all 6 agents simultaneously

GUI permission approval — Allow/Deny buttons in notch for tool execution requests

Interactive Q&A — One-click responses to AskUserQuestion prompts from the notch

Plan review — Markdown rendering of agent plans with feedback capability

Terminal jumping — Navigate to correct terminal window/tab/pane across 13+ apps

Split pane + tmux — Jumps to correct pane within splits and tmux sessions

UI/UX Window & Display

Non-activating overlay — NSPanel that never steals focus from your editor

Notch-native placement — Sits in the MacBook notch on supported hardware

Floating bar fallback — Compact bar for external monitors and non-notch Macs

Contextual expansion — Panel expands to show details, collapses when idle

Multi-session display — All active agent sessions visible in one panel

Audio Sound Alerts

8-bit synthesized sounds — Retro chiptune-style notifications for agent events

Custom sound packs — Configurable alert sounds per event type

Setup Configuration

Zero-config auto-setup — Auto-writes hook entries into each tool's config on first launch

Bundled VSIX extension — For IDE terminal integration (VS Code, Cursor, Windsurf)

Per-agent configuration — Individual hook setup per tool

Technical Architecture

What's under the hood — 100% native Swift, zero cloud.

Event Flow

      AI Agent → Hook Script → Unix Socket → Bridge Binary → Event Parser → State Machine → UI Update
    

🔨 Language & Framework

Swift — 100% native (not Electron/Tauri)
AppKit — NSPanel subclass for overlay
SwiftUI — Views hosted via NSHostingView
Apple Silicon optimized
macOS 14+ (Sonoma) target
~50MB RAM, near-zero CPU idle

🔌 Communication

Unix domain socket — Primary IPC channel
Bridge binary — Lightweight CLI for hook-to-app comms
JSON payloads — Typed event messages
Shell hooks — Installed into each tool's config dir

🎨 Window System

NSPanel + .nonactivatingPanel style
Floating window level — Stays above other windows
Notch geometry detection — CGDisplayBounds API
Core Animation — Expand/collapse transitions

💻 Terminal Navigation

AppleScript/JXA — iTerm2, Terminal.app
Accessibility API — For supported apps
VSIX extension — VS Code, Cursor, Windsurf
App-specific IPC — Ghostty, Kitty, Warp

🔊 Audio Engine

AVAudioEngine or AudioToolbox
8-bit synthesized chiptune sounds
Low-latency runtime generation

💲 Business Stack

Lemon Squeezy — Payment/licensing
PostHog — Analytics (website only)
Local license key storage
No user accounts needed

Hook Config Locations

Agent	Config File	Hook Format
Claude Code	`~/.claude/settings.json`	hooks config
Codex CLI	`config.toml` + `hooks.json`	TOML + JSON
Gemini CLI	`settings.json`	JSON hooks
Cursor	`hooks.json`	JSON hooks

Mac Build Specification

What you need to build this from scratch.

Why Native Swift?

Every app in this space uses native Swift. NSPanel's .nonactivatingPanel is essential, notch detection needs native APIs, Accessibility API requires entitlements, and 50MB RAM rules out Electron (200MB+). Cross-platform frameworks cannot do this.

Components to Build

Component	Technology	Complexity
Notch overlay window	NSPanel + SwiftUI via NSHostingView	Medium
Unix socket server	Foundation CFSocket or Swift NIO	Medium
Bridge binary	Small Swift CLI for hook IPC	Low-Med
Hook installer	FS writes to tool config dirs	Low
Event parser	JSON Codable decoding	Low
State machine	Per-session state tracking	Medium
Permission UI	SwiftUI Allow/Deny + expandable panel	Medium
Markdown renderer	swift-markdown or AttributedString	Medium
Terminal jumper	AppleScript + Accessibility API + VSIX	High
Audio synthesizer	AVAudioEngine for 8-bit sounds	Medium
Notch geometry	CGDisplayBounds + notch detection	Low-Med
License validation	Lemon Squeezy API or similar	Low
Multi-session mgmt	Session registry + lifecycle	Medium

Key Technical Challenges

⚠ Terminal Jumping (Hardest)

13+ terminal apps, each with different automation APIs. iTerm2 has great AppleScript; Ghostty uses its own IPC; Kitty has kitten @; Warp has limited automation. Split pane + tmux detection adds massive complexity. Estimated 2-3 weeks alone.

⚠ Non-Activating Overlay

NSPanel with .nonactivatingPanel sounds simple but handling click-through, proper z-ordering, and focus behavior across spaces/desktops requires careful tuning. Two-way interaction without focus steal is the core UX challenge.

⚠ Hook Compatibility

6 AI tools, each with different config formats (JSON, TOML). Maintaining compatibility as tools update their APIs is ongoing work. Auto-installer must handle edge cases (missing dirs, conflicting configs).

⚠ Notch Positioning

Detecting notch area, handling multiple displays (some with notch, some without), external monitor fallback, and display configuration changes requires display monitoring.

Required Assets

Asset	Description	Source
Sound effects	8-bit chiptune alerts (or runtime synthesis)	Create or license
App icon	macOS icon (1024x1024 + sizes)	Design
Fonts	JetBrains Mono, system monospace	Free / bundled
VSIX extension	VS Code extension for IDE terminal integration	Build (TypeScript)

Development Environment

🛠 Required Tools

Xcode 15+ — Swift compiler, Interface Builder
macOS 14+ SDK — Sonoma APIs
Apple Developer account — For signing & notarization
Swift Package Manager — Dependency management

📦 Key Dependencies

Swift NIO — Unix socket server
swift-markdown — Plan rendering
DynamicNotchKit — Notch UI helper (open source)
AudioToolbox — Sound synthesis (system framework)

Effort Estimate

Solo developer, full-time. Three phases from MVP to full feature parity.

Phase 1 — MVP 2-3 weeks

Scope: Single agent (Claude Code) monitoring + notch overlay

Unix socket server
Hook installer for Claude Code only
Basic notch panel with status display
Permission approval (Allow/Deny)

Effort25%

Phase 2 — V1 4-6 weeks

Scope: 3 agents + permission UI + terminal jump for 3 terminals

Add Codex CLI + Gemini CLI support
Interactive Q&A from notch
Markdown plan review
AppleScript terminal jumping (iTerm2, Terminal.app, Ghostty)
Floating bar fallback for non-notch displays

Effort55%

Phase 3 — Full Parity 8-12 weeks

Scope: Full feature parity with Vibe Island

All 6 agents
13+ terminal app support (incl. tmux, split panes)
VSIX extension for IDE terminals
8-bit audio synthesizer + custom sound packs
License validation (Lemon Squeezy)
Polish, edge cases, multi-display handling

Effort100%

Biggest Time Sink

The terminal jumping system alone (13+ apps, each with different automation APIs, plus tmux and split pane detection) accounts for ~30% of the total effort. Consider shipping with 3-4 terminal support initially.

Competitors & Alternatives

The landscape of AI agent notch apps and related tools.

Direct Competitors (AI Agent Notch Apps)

App	Price	Agents	Open Source	Key Differentiator
Vibe Island	$19.99	6	No	Two-way interaction, 13+ terminals, audio
Claude Island	Free	1	MIT	Auto-setup, chat history, markdown
Notchi	Free	1	MIT	Animated sprites, sentiment analysis
AgentNotch	Free	2	MIT	OpenTelemetry-based, token/cost tracking
Notchy	Free	1	Yes	Embedded terminal in notch
ClaudeBar	Free	3	Yes	Usage quota monitoring (menu bar)

General Mac Notch/Dynamic Island Apps

App	What It Does	Open Source
NotchNook	General Dynamic Island — media, calendar, widgets	No
TheBoringNotch	Music controls + visualizer in notch	Yes
DynamicLake	Dynamic Island notifications for Mac	No
Alcove	Media, calendar, files in the notch	No
NotchDrop	File drop zone in the notch	Yes

Open Source Starting Points

Build Faster — Fork These

Claude Island (MIT) — Best starting point for the core notch UI + hook system. Already has NSPanel, Unix socket, and Claude Code hooks.
AgentNotch (MIT) — Has multi-agent support (Claude + Codex) and token tracking.
DynamicNotchKit (MIT) — Reusable SwiftUI library for notch-area UI components.
Notchi (MIT) — Has animated sprites and personality features if you want visual flair.

Architectural Pattern (All Apps Share This)

      Language: 100% Swift

      IPC: Unix domain socket (JSON payloads)

      Hooks: Shell scripts in tool config dirs

      Window: NSPanel + .nonactivatingPanel

      Privacy: All local, no cloud

      The paid app (Vibe Island) differentiates on breadth: 6 agents vs 1-2, 13+ terminals vs 1-3, two-way interaction vs read-only.