Plaude

A macOS menu bar app that plays your Plex media in a floating picture-in-picture window, automatically synced to Claude CLI's thinking state. Video plays while Claude thinks and pauses when it goes idle.

How it works

1. Plaude installs hooks into Claude CLI's settings that fire a companion tool (plaude-ctl) on prompt submission and stop events
2. plaude-ctl sends signals over a Unix domain socket to the running Plaude app
3. When Claude starts thinking, video resumes; when Claude goes idle, video pauses
4. Media is fetched from your Plex server (Continue Watching / On Deck) and played via VLCKit in a floating panel

Requirements

• macOS 14+
• Xcode 15+
• mise (installs XcodeGen and SwiftLint automatically)
• Claude CLI installed
• A Plex account with at least one media server

Building

The Xcode project is generated from project.yml via XcodeGen. If you have mise installed, it handles tool versions automatically:

mise install          # install XcodeGen + SwiftLint
mise run generate     # generate Plaude.xcodeproj
mise run build        # build the app

Or manually:

xcodegen generate
xcodebuild -project Plaude.xcodeproj -scheme Plaude -configuration Release build

Note: The app runs without App Sandbox because it needs to read ~/.claude/settings.json, bind a Unix domain socket, and communicate with local Plex servers.

Setup

1. Launch Plaude -- it appears as a menu bar icon
2. Sign in with your Plex account (opens browser for OAuth)
3. Click "Install Hooks" to configure Claude CLI integration
4. Start a Claude CLI session -- Plaude will detect it automatically
5. Pick something from your On Deck list and it will play in a floating PiP window

Features

• Floating always-on-top PiP window with full playback controls
• Configurable resume/pause debounce delays and grace period
• Auto-advances through episode queues
• Reports watch progress back to Plex (scrobbling)
• Media key support (play/pause/skip via keyboard or Touch Bar)
• Multi-session support (stays playing if any Claude session is thinking)
• Mini player mode
• Subtitle and audio track selection
• Launch at login

Project structure

Sources/
  Plaude/               # Main macOS app
    Claude/             # Claude state monitoring via Unix socket
    Coordination/       # State coordination, play queue, watch tracking
    Player/             # VLCKit playback, PiP panel, progress reporting
    Plex/               # Plex auth, API, server discovery, models
    Views/              # SwiftUI menu bar, player, settings views
  plaude-ctl/           # CLI tool invoked by Claude hooks
  Resources/            # Info.plist, entitlements, asset catalog
Tests/                  # Unit tests

Architecture

Plaude is a Swift 6 app using strict concurrency throughout:

• PlaudeApp -- SwiftUI menu bar app entry point
• AppCoordinator -- Wires all components together
• PlexAuth -- Plex OAuth PIN-based authentication
• PlexAPI -- Plex server communication (On Deck, timeline reporting, scrobbling)
• PlexServerDiscovery -- Discovers and probes Plex servers with connection priority
• ClaudeStateMonitor -- Listens for state signals via Unix socket
• StateCoordinator -- Debounces Claude state changes into play/pause actions
• MPVCoordinator -- VLCKit-based video playback
• plaude-ctl -- Lightweight CLI tool invoked by Claude hooks

Third-party dependencies

• VLCKitSPM (LGPL-2.1+) -- VLC media playback
• swift-argument-parser (Apache-2.0) -- CLI argument parsing
• MPVKit (LGPL-3.0) -- Transitive dependency via VLCKitSPM

License

MIT -- see LICENSE for details.

Note: This project depends on LGPL-licensed libraries (VLCKit, MPVKit) which are dynamically linked as xcframeworks. See their respective repositories for license terms.