Perch — Build Specification

Overview

What Perch is, who it's for, and why you'd build it.

What Perch Does

Perch sits in your MacBook's notch (or floats on non-notch displays) and monitors all your Claude Code sessions. When Claude needs permission to run a tool, asks a question, or presents a plan — you handle it from the notch without switching apps. Click any session to jump straight to its terminal.

4

Terminal Apps

2-way

Communication

∞

Concurrent Sessions

3-5w

Build Estimate

🐦 Why "Perch"?

It perches in the notch, watching over your coding sessions like a bird on a wire. Short, memorable, Mac-app-name energy. And it's where Claude comes to roost when it needs your attention.

🎯 Target User

Developers running multiple Claude Code sessions across terminal windows/panes — who are tired of cmd-tabbing to approve permissions and answer questions.

⚡ Why Fork Claude Island?

MIT-licensed, already has NSPanel overlay, Unix socket IPC, Claude Code hooks, auto-setup, and markdown rendering. You're adding two-way comms + multi-session + terminal jumping on a proven foundation.

Scope Definition

What's in, what's out, and what that means for effort.

✓ IN SCOPE

Claude Code — only AI tool
Multi-session — unlimited concurrent CC sessions
Two-way interaction — permissions, Q&A, plan review
Terminal jumping — iTerm2, Terminal.app, Ghostty, Kitty
Notch overlay — non-activating NSPanel
Floating bar — fallback for non-notch/external displays
Session picker — switch between active sessions
Status indicators — idle, thinking, tool-use, waiting
Markdown plan rendering
Sound alerts — when attention needed

✗ OUT OF SCOPE

~~Codex CLI, Gemini CLI, Cursor, OpenCode, Droid~~
~~Multi-format config handling (TOML)~~
~~VSIX IDE extension~~
~~License/payment system~~
~~13+ terminal apps~~ (4 is enough)
~~Custom sound packs~~ (basic alerts only)
~~Pixel art / animated sprites~~
~~Token/cost tracking~~
~~Analytics / telemetry~~

Effort Reduction

Cutting 5 of 6 agents, TOML config parsing, VSIX extension, licensing, and 9+ terminal apps drops the build from 8-12 weeks (Vibe Island parity) to 3-5 weeks. The biggest remaining effort is terminal jumping + two-way interaction.

Perch vs Vibe Island vs Claude Island

Feature	Claude Island (base)	Perch (your build)	Vibe Island ($20)
AI Agents	Claude Code	Claude Code	6 agents
Multi-session	No	Yes	Yes
Two-way interaction	Read-only	Full	Full
Permission approval	No	Yes	Yes
Q&A from notch	No	Yes	Yes
Plan review	Yes	Yes	Yes
Terminal jumping	No	4 apps	13+ apps
Notch overlay	Yes	Yes	Yes
Sound alerts	No	Basic	8-bit synth
Price	Free (MIT)	Free (your build)	$19.99
Build effort	Done	3-5 weeks	8-12 weeks

Feature Spec

Complete feature list for Perch.

Core Multi-Session Claude Code Control

Session registry — Track all active CC sessions with unique IDs, PIDs, and working directories

Session picker — Horizontal scrollable list in notch showing all sessions with status badges

Permission approval — Allow/Deny buttons when CC requests tool execution (Bash, Edit, Write, etc.)

AskUserQuestion response — Option buttons + free-text input rendered in notch panel

Plan review — Expandable markdown view of CC plans with approve/reject actions

Status tracking — Per-session state: idle, thinking, tool-use, waiting-for-permission, asking-question

UI Notch Interface

Notch overlay — NSPanel in notch area, non-activating, never steals focus

Compact mode — Collapsed: shows session count + attention-needed badge

Expanded mode — Click to expand: session list, active session detail, interaction panel

Floating bar — Fallback for external monitors and non-notch Macs

Attention pulse — Gentle glow animation when a session needs input

Session color coding — Each session gets a unique color for quick identification

Navigation Terminal Jumping

iTerm2 — AppleScript: activate window, select tab, select pane by session ID

Terminal.app — AppleScript: activate window, select tab

Ghostty 1.3+ — Ghostty IPC protocol for window/tab focus

Kitty — kitten @ remote control for window focus

Audio Alerts

Permission needed — Distinct sound when CC is waiting for tool approval

Question asked — Sound when CC asks a question via AskUserQuestion

Session completed — Chime when a CC session finishes its task

Error/crash — Alert sound when a session errors

Setup Configuration

Auto-setup — On first launch, writes hook config to ~/.claude/settings.json

Zero-config — No manual setup required; hooks auto-installed

Menu bar icon — Quick access to settings, session list, quit

Architecture

How Perch works under the hood.

Event Flow

      Claude Code → Hook (shell script) → Unix Socket → Perch Event Parser → Session State Machine → UI Update

      User Action (Allow/Deny/Answer) → Perch → Unix Socket response → Hook returns to Claude Code

Two-Way Communication Detail

/* Permission Flow */
CC requests Bash("rm -rf /tmp/test") → hook fires pre_tool_use
  → Perch shows: "Bash: rm -rf /tmp/test" [Allow] [Deny]
  → User clicks Allow → hook returns exit 0
  → User clicks Deny → hook returns exit 2 (BLOCK)

/* Question Flow */
CC calls AskUserQuestion → hook fires notification
  → Perch shows question + option buttons
  → User selects option → response written to stdin/socket

/* Multi-Session */
Each CC session gets unique session_id from hook env vars
  → Perch maintains Map<SessionID, SessionState>
  → UI shows all sessions, highlights ones needing attention

System Components

🔌 Socket Server

Unix domain socket at /tmp/perch.sock
Accepts JSON event messages from hook scripts
Returns responses for two-way hooks (permissions, Q&A)
Each connection tagged with session ID

🛠 Hook Scripts

Auto-installed to ~/.claude/settings.json
PreToolUse — sends tool name + args, waits for allow/deny
PostToolUse — sends result for status update
Notification — sends questions, plan mode events
Stop — session ended, clean up

🎨 Notch Panel

NSPanel + .nonactivatingPanel
SwiftUI views via NSHostingView
Collapsed: session dots + attention badge
Expanded: session list + interaction panel
Core Animation transitions

📋 Session Manager

Registers new sessions on first hook event
Tracks state per session (idle, thinking, waiting)
Maps session ID → terminal app + window/tab/pane
Cleans up on session end or timeout
Publishes state changes to UI via Combine/ObservableObject

💻 Terminal Jumper

iTerm2: AppleScript — tell app "iTerm2" to select session id
Terminal.app: AppleScript — activate + select tab
Ghostty: IPC via ghostty +ipc
Kitty: kitten @ focus-window --match id:X

🔊 Alert System

NSSound or AVAudioPlayer for bundled .aiff/.wav
4 distinct alert types (permission, question, done, error)
Respects macOS Do Not Disturb
Optional: mute when terminal is focused

Build Spec

Technical requirements to build Perch.

Development Environment

🛠 Tools

Xcode 15+
macOS 14+ SDK (Sonoma)
Apple Developer account (for signing)
Swift 5.9+

📦 Dependencies

Swift NIO — Unix socket server
swift-markdown — Plan rendering
DynamicNotchKit — Notch UI helper (MIT)
All system frameworks (AppKit, AVFoundation, CoreAnimation)

Component Build Matrix

Component	Technology	Complexity	Est. Time
Notch panel + floating bar	NSPanel + SwiftUI	Medium	3-4 days
Unix socket server	Swift NIO	Medium	2-3 days
Hook scripts + auto-installer	Shell + JSON config write	Low	1 day
Event parser	Swift Codable	Low	1 day
Session state machine	Swift enum + Combine	Medium	2-3 days
Multi-session UI	SwiftUI list + badges	Medium	2-3 days
Permission approval UI	SwiftUI + socket response	Medium	2-3 days
Q&A response UI	SwiftUI + socket response	Medium	2-3 days
Markdown plan viewer	swift-markdown	Low-Med	1-2 days
Terminal jumping (4 apps)	AppleScript + IPC	High	5-7 days
Sound alerts	NSSound / AVAudioPlayer	Low	1 day
Notch geometry + fallback	CGDisplay APIs	Low-Med	1-2 days
Menu bar integration	NSStatusItem	Low	0.5 day

Two-Way Hook Implementation

Claude Code hooks support blocking: a PreToolUse hook can return exit 0 (allow) or exit 2 (block). The hook script connects to the Unix socket, sends the tool request, and blocks waiting for Perch to respond. When the user clicks Allow/Deny in the notch, Perch writes the response back and the hook exits. This is the key mechanism enabling two-way control.

Build Plan

3 phases, 3-5 weeks total. Ship early, iterate.

Phase 1 Core + Two-Way

~1.5 weeks

Goal: Single CC session with full two-way control in notch.

Fork Claude Island repo
Refactor existing socket server for bidirectional communication
Add PreToolUse blocking hook with Allow/Deny UI
Add AskUserQuestion response UI (option buttons + text input)
Update notch panel to show permission/question prompts
Test end-to-end: CC requests permission → Perch shows → user clicks → CC continues

Milestone: Demo video of approving a Bash command from the notch.

Phase 2 Multi-Session + Jumping

~2 weeks

Goal: Run 3+ CC sessions, see all in notch, jump to any terminal.

Build session registry (Map<SessionID, SessionState>)
Session picker UI in notch (horizontal scroll, color-coded dots)
Attention badge system (pulse when session needs input)
Terminal jumping: iTerm2 (AppleScript), Terminal.app (AppleScript)
Terminal jumping: Ghostty (IPC), Kitty (kitten @)
Session → terminal mapping (detect which terminal launched which CC session)
Floating bar fallback for non-notch displays

Milestone: 3 concurrent CC sessions, approve permissions on any, click to jump to terminal.

Phase 3 Polish + Ship

~1-1.5 weeks

Goal: Production quality. Ready for daily use.

Sound alerts (4 types: permission, question, done, error)
Markdown plan viewer with approve/reject
Menu bar icon + settings panel
Edge cases: CC crash recovery, orphaned sessions, display changes
Auto-setup improvements (detect existing hooks, merge safely)
Multi-display handling (notch on laptop, floating on external)
Code signing + notarization for distribution
README + installation guide

Milestone: Ship v1.0 as signed .dmg.

Risk: Terminal Jumping

Terminal jumping is the most unpredictable component. iTerm2 and Terminal.app have stable AppleScript APIs. Ghostty and Kitty IPC may require experimentation. Budget 1-2 extra days for edge cases (tmux panes, split windows, multiple tabs).

Fork Strategy

What Claude Island gives you for free, and what you need to build.

✓ Get Free from Claude Island
NSPanel notch overlay — non-activating, positioned
Unix socket server — basic IPC infrastructure
Claude Code hooks — shell scripts + auto-installer
Event parsing — JSON decoding of CC events
Status display — basic state rendering in notch
Markdown rendering — plan/message display
Auto-setup — first-launch hook configuration
Dark/light theme — matches macOS appearance

🔨 Build Yourself

Bidirectional socket — hooks block and wait for response
Permission UI — Allow/Deny with tool details
Q&A UI — Option buttons + text input
Multi-session registry — session tracking + lifecycle
Session picker UI — horizontal list + color coding
Terminal jumping — 4 terminal app integrations
Sound alerts — 4 event-type sounds
Floating bar fallback — non-notch display mode

Claude Island Repo

github.com/farouqaldori/claude-island

License: MIT — free to fork, modify, and distribute (even commercially)
Language: Swift
Framework: AppKit + SwiftUI
Stars: Active development, regular updates
Key files to study: NSPanel setup, socket server, hook installer, event parser

Alternatives to Forking

Option	Pros	Cons	Recommendation
Fork Claude Island	Fastest start, proven foundation, MIT license	Inherit their code style/decisions	Best option
Fork AgentNotch	Already has multi-agent, uses OpenTelemetry	OTLP-based (different IPC pattern), more complex	Consider
Build from scratch	Clean architecture, no inherited debt	2-3x longer, reinventing solved problems	Avoid
Use DynamicNotchKit only	Just the notch UI library, build the rest	Still need socket, hooks, event system from scratch	If Claude Island doesn't fit

Bottom Line

Fork Claude Island. It gives you ~40% of Perch for free. Spend your 3-5 weeks on the hard parts: two-way comms, multi-session, and terminal jumping. Ship a signed .dmg that does one thing better than anything else: let you run multiple Claude Code sessions and control them all from the notch.