☕ Espresso

Keep your macOS apps awake and never miss a notification

---

What is Espresso?

Espresso prevents session timeouts and monitors for notifications in remote desktop applications (like Citrix Viewer) on macOS.

Three monitoring modes:

• 🎹 Keepalive - Simulates keyboard activity to prevent timeouts
• 🔔 Audio Monitoring - Detects Teams calls/notifications via audio
• 📺 Screen Monitoring - Visual notification detection with OCR

Quick Start

Option 1: Homebrew (Easiest)

# Install directly (tap is added automatically)
brew install slauger/tap/espresso

# Launch
open /Applications/Espresso.app

The ☕ icon appears in your menu bar. Click it to enable features.

Note: On first launch, macOS will show a Gatekeeper warning (app is not signed). Right-click Espresso.app → "Open" → Click "Open" again, or run: xattr -cr /Applications/Espresso.app

Option 2: Download Binary

1. Download the latest release from GitHub Releases
2. Open the DMG and drag Espresso.app to Applications
3. First launch: Right-click Espresso.app → "Open" → Click "Open" again
   • macOS will show a Gatekeeper warning (app is not signed)
   • Alternative: xattr -cr /Applications/Espresso.app in Terminal

The ☕ icon appears in your menu bar. Click it to enable features.

Note: The app is not code-signed (requires Apple Developer Account $99/year). It's safe to run, source code is public.

Option 3: Install from Source

# Clone and install
git clone https://github.com/slauger/espresso-macos.git
cd espresso-macos
pip install -e .[full]

# Launch GUI (works without config!)
espresso-gui

# Optional: Setup autostart with config
mkdir -p ~/.espresso
cp examples/config-autostart.json ~/.espresso/config.json

Features

• ☕ Universal - Works with any macOS app (Citrix, Teams, Slack)
• 🎨 Menu Bar GUI - Simple click-to-enable interface
• ⚙️ Configurable - JSON config or command-line options
• 🧠 Smart - Only monitors when app is running
• 🔒 Non-intrusive - Keyboard simulation (no mouse movement)
• 📦 Lightweight - Minimal resource usage

Configuration

Configuration is optional! Espresso works out of the box with sensible defaults.

Optional: Create ~/.espresso/config.json

{
  "app_name": "Citrix Viewer",
  "interval_seconds": 60,
  "autostart": true,
  "autostart_audio": true,
  "audio_device": "BlackHole 2ch"
}

Default values (when no config exists):

• app_name: "Citrix Viewer"
• interval_seconds: 60
• autostart: false (manual start)
• audio_device: null (configure for audio monitoring)

See examples/ for complete configuration examples.

Advanced Features

Audio Monitoring

Monitor audio from remote desktop to catch Teams calls and notifications.

📖 Audio Monitoring Setup Guide

Screen Monitoring

Detect notifications visually via screenshot analysis and OCR.

📖 Screen Monitoring Setup Guide

Documentation

• 📖 Audio Monitoring Setup
• 📖 Audio Fingerprinting
• 📖 Screen Monitoring Setup
• 📖 Development Guide
• 📖 Homebrew Tap Setup (for maintainers)
• 📋 Config Examples

Development

Build Your Own Binary

# Install dependencies
pip install -e .[full,dev]

# Build with PyInstaller
pyinstaller espresso-gui.spec

# Output: dist/Espresso.app

Release Process

Releases are automated via semantic-release:

• Push to main with conventional commits (feat:, fix:, etc.)
• GitHub Actions automatically:
  • Creates git tag and GitHub Release
  • Builds macOS binary (.app)
  • Generates DMG and ZIP archives
  • Updates Homebrew tap

See HOMEBREW_SETUP.md for Homebrew tap configuration.

Usage

Launch the App

• Binary: Open Espresso.app from Applications
• From source: Run espresso-gui in terminal

Click the ☕ menu bar icon to:

• Enable/disable keepalive
• Enable/disable audio monitoring
• Enable/disable screen monitoring
• View status and logs

CLI (Optional)

For automation or headless usage:

espresso --app "Citrix Viewer" --interval 60 --config ~/.espresso/config.json

Command-Line Options

espresso-gui [OPTIONS]

Options:
  --app TEXT              Target application name (default: Citrix Viewer)
  --interval INT          Seconds between keepalive actions (default: 60)
  --audio-device TEXT     Audio device for monitoring (e.g., BlackHole)
  --autostart            Start keepalive automatically
  --autostart-audio      Start audio monitoring automatically
  --autostart-screen     Start screen monitoring automatically
  --debug                Enable verbose logging
  --config PATH          Path to JSON config file

Requirements

• macOS 10.15+
• Python 3.9+

Optional:

• BlackHole for audio monitoring
• Screen Recording permission for screen monitoring

Why "Espresso"?

Just like a shot of espresso keeps you awake, this app keeps your sessions awake! ☕

License

MIT License - see LICENSE file for details.

Contributing

Issues and pull requests welcome!

For major changes, please open an issue first to discuss what you'd like to change.