macOS Dynamic Island for Claude Code

Monitor your Claude Code sessions
as cute little crabs

A floating Dynamic Island for macOS that gives each Claude Code session a unique crab identity. See working, idle, and permission states at a glance across all your terminals — or from your phone via the built-in web dashboard.

Get Started View on GitHub
Compact
2 working 3
click to expand
Expanded
2 working 3
Pinchy my-api tmux WORKING
~/workspace/projects/my-api
3m
!
Clawdia frontend ghostty PERMISSION
~/workspace/projects/frontend
12m
Write to src/config.json
~ src/config.json
1{
2 "name": "my-app",
3 "port": 3000,
4 "debug": true,
5 "features": {
6 "darkMode": true
7 }
8}
Scuttles infra iterm WORKING
~/workspace/projects/infra
1m
Features

All your Claude Code sessions at a glance

Keep track of all your parallel Claude Code sessions without switching between terminal windows. Real-time status, sound alerts, inline permissions, and a web dashboard for your phone.

Dynamic Island

A floating pill near your notch with an animated crab. Compact when idle, expands on click to reveal all sessions.

Ambient Glow

The island glows green while working, pulses orange when a session needs input, and flashes pink on errors.

Sound Alerts

Hear a sound when any session needs your input or permission. Never miss a prompt while multitasking.

Inline Permissions

Approve or deny tool permissions directly from the island widget. Allow, Deny, or Always Allow with a single click.

Code Preview

See a scrollable, syntax-highlighted preview of file changes before approving write permissions.

Click-to-Focus

Click any session to focus its terminal. Supports tmux panes, Ghostty, iTerm2, Terminal.app, and more.

New

Web Dashboard

Local web server with real-time updates. Monitor sessions and approve permissions from your phone. Installable as a PWA.

New

Expandable Content

Expand large permission content to 50% screen width with up to 80 lines visible. Works in both the island and web dashboard.

Unique Crab Names

Each session is deterministically assigned a charming crab name like Pinchy, Clawdia, or Captain Claw.

Stale Session Cleanup

Automatically detects and removes dead sessions when a Claude process crashes without firing a session end event.

Zero Config

One command installs everything: compiles the Swift app, copies hooks, and configures Claude Code settings.

Crab States

Meet the moods

Each crab visually reflects what its Claude session is doing right now.

Working

Wiggling legs and sparkles. Claude is processing.

!

Needs Input

Bouncing with "!" badge. Needs your attention.

!

Permission

Wants tool approval. Allow or deny inline.

z z

Idle

Closed eyes and "zzz". Waiting for a prompt.

!

Error

Pink crab with alert. An API error occurred.

Terminal Support

Click any session, focus any terminal

Click a session in the island to instantly jump to its terminal. Detects your terminal app automatically by walking the process tree.

tmux tmux
Ghostty ghostty
iTerm2 iterm
Terminal.app term
WezTerm wez
Alacritty alac
kitty kitty
Architecture

How Claude Observer works

Claude Observer uses Claude Code's hook system to track session lifecycle events in real time via lightweight JSON files.

1

Hook Events Fire

Claude Code triggers hooks on lifecycle events: session start/end, prompt submit, tool use, notifications, permission requests, and subagent activity.

2

Python Hook Writes State

The observer hook script receives event data via stdin and atomically writes a JSON file per session to ~/.claude-observer/sessions/.

3

Dynamic Island Polls

The floating panel polls the sessions directory every 2 seconds, reads JSON files, and updates the island with animated crabs and glow effects.

4

Interact & Navigate

Respond to permission requests inline, hear sound alerts, click sessions to jump to their terminal, or approve from your phone via the web dashboard. Dead sessions are auto-cleaned.

Claude Code triggers hook event
SessionStart Stop Notification ...
↓
Python hook writes JSON
~/.claude-observer/sessions/{id}.json
↓
Dynamic island reads & renders
NSPanel + animated crabs + glow
Tracked Events
SessionStartCreates session file UserPromptSubmitMarks as "working" PreToolUseMarks as "working" PostToolUseMarks as "working" StopMarks as "idle" StopFailureMarks as "error" NotificationMarks as "needs input" PermissionRequestShows inline prompt SubagentStartMarks as "working" SubagentStopUpdates activity SessionEndRemoves session file
Getting Started

Install Claude Observer in seconds

Requires macOS 12+, Xcode Command Line Tools, and Python 3. One command does everything.

1

Clone the repository

git clone https://github.com/svenliebig/claude-observer.git
cd claude-observer
2

Install

Compiles the Swift app, installs the hook script, and configures Claude Code hooks.

make install
3

Run

make run
# or directly:
~/.claude-observer/bin/claude-observer &

Stop

make stop

Uninstall

make uninstall

Tip: Add the binary to System Settings > General > Login Items for auto-start on login.

50 Unique Names

Meet the crew

Each repository gets a persistent crab name stored across sessions. The same project always gets the same crab.

Pinchy Snippy Clawdia Scuttles Sheldon Bubbles Sandy Hermie Captain Claw Rusty Coral Neptune Barnacle Tidbit Shelly Crusty Wobbles Chomper Skipper Pebbles Biscuit Snapper Gizmo Pepper Ziggy Pickle Noodle Sprocket Tango Mango Fiddler Coconut Cheddar Waffles Bongo Clementine Puddles Driftwood Starfish Jellybean Anchovy Ripple Barnaby Tempest Breeze Crumble Scooter Peanut Sushi Pretzel