A Dynamic Island for Claude Code on macOS. See all your active sessions at a glance — across machines and LLM providers.
Most Dynamic Island apps for Claude Code work by injecting hooks into your Claude configuration — cluttering ~/.claude/ with extra scripts, modifying your setup, and breaking when Claude updates. Clotch takes a different approach:
- Zero hooks — never touches your Claude config. Your
settings.jsonstays untouched, no injected scripts, nothing to break on updates. - File-based only — reads Claude's native session files and JSONL logs directly. The agent writes a single summary JSON; the UI reads it. That's the entire contract.
- No network code — no WebSocket servers, no HTTP APIs, no localhost ports. Remote monitoring is just file sync (rsync, Syncthing, etc.), not another daemon.
brew install tuannvm/mcp/clotchThis installs the Dynamic Island app and the session scanner agent. Then:
brew services start clotch-agent # start the scanner
open /Applications/Clotch.app # launch the UIOn Linux, only the session scanner agent is available (no GUI):
brew install tuannvm/mcp/clotch-agent
brew services start clotch-agentThe agent writes session data to ~/.config/clotch/summaries/<hostname>.json. Sync this directory to your Mac to see remote sessions in the Dynamic Island — see Remote Machine Setup.
git clone https://github.com/tuannvm/clotch.git
cd clotch
make install # Go agent + Swift binaries to /usr/local/bin (macOS only)
make install-app # install Clotch.app to /Applications
# or
make install-agent # Go agent only (macOS + Linux)Requires Go 1.21+. Swift 6.0+ and macOS 14+ required for the macOS app.
- Dynamic Island UI — a floating pill at the screen top, expands on hover, collapses on exit with a golden-ratio delay
- Notch-aware — on MacBook Pro notch displays, the pill overlays the notch with pure #000000 black and content in flanking wings; on non-notch Macs, it acts as a capsule pill
- Liquid Glass — on macOS 26+, the expanded panel uses Apple's Liquid Glass translucent material; on older macOS, a solid dark background with colored border
- Primary display pinned — always stays on the user's primary display, never jumps to secondary monitors
- Multi-provider — auto-discovers
~/.claude/,~/.claude-zai/,~/.claude-openai/, and any~/.claude-*/directory - Multi-machine — run the agent on remote Linux/macOS servers, sync the summary file, see everything in one view
- Session details — repo name, recap/last assistant message, provider glyph, relative timestamp, circular provider avatar with brand color
- Active/stale indicators — header shows active session count (updated within 24h); stale sessions are dimmed for visual clarity
- Session Switching (experimental) — focus button on each session row to switch to the terminal running that session. Works with Ghostty and tmux — local switching resolves pane ancestry, prefers the matching tmux client deterministically, routes to the matching Ghostty tab by tmux session name, and uses
tmux switch-clientstatus for success/failure. Uses native macOS APIs and Ghostty AppleScript/Accessibility integration — no SSH required - Settings — configure max sessions, poll interval, message length, menu bar icon, and experimental features via the gear icon
Run the agent on any Linux or macOS server and sync the output back to your Mac. See docs/remote-setup.md for step-by-step instructions.
Right-click the status bar icon for:
- Quit Clotch (Cmd+Q)
The menu bar icon can be hidden in Settings.
For terminals and scripting:
clotch # prints sessions every 3sClick the gear icon in the expanded view to configure:
| Setting | Default | Description |
|---|---|---|
| Max sessions | 20 | Maximum sessions displayed (1–50) |
| Poll interval | 3s | How often the UI reads summary files (1–30s) |
| Message length | 120 | Truncation length for recap/last message (40–500 chars) |
| Prefer Recap | On | Prefer recap text over last message when both exist |
| Liquid Glass | On | Enable Liquid Glass material on macOS 26+ |
| Menu bar icon | On | Show/hide the status bar icon |
| Setting | Default | Description |
|---|---|---|
| Session Switching | Off | Show a focus button on each session to switch to its terminal |
Enabling Session Switching prompts for Accessibility permissions (required to activate terminal windows). Permissions persist across rebuilds when the app is signed with a Developer ID certificate.
When using Ghostty with multiple tmux sessions (each in its own tab), Clotch maps each Claude session to the correct tmux client and Ghostty tab automatically. Tab matching uses the tmux session name — for best results, ensure your tmux titles include the session name (e.g., set -g set-titles on).
Settings are saved to ~/.config/clotch/settings.json.
The app bundle is signed during make app. Signing mode is controlled by the CODESIGN env var:
| Mode | Command | Behavior |
|---|---|---|
dev (default) |
make app |
Tries Developer ID (hardened runtime + entitlements), falls back to ad-hoc |
release |
CODESIGN=release make app |
Requires Developer ID + hardened runtime + secure timestamp (for notarization) |
Developer ID signing keeps a stable code identity, so macOS preserves Accessibility permissions across rebuilds. Ad-hoc signing generates a new identity each time, requiring re-granting permissions.
Release builds can be notarized via make release (requires AC_PASSWORD keychain profile for notarytool). By default, make release auto-increments the patch version from the latest vX.Y.Z git tag; pass VERSION=... to override explicitly.
MIT