https://github.com/slauger/espresso-macos
Keep your macOS apps awake - Session keepalive + audio/visual notification monitoring for remote desktop apps
https://github.com/slauger/espresso-macos
citrix keepalive macos menu-bar-app notification-monitor python remote-desktop teams
Last synced: 5 months ago
JSON representation
Keep your macOS apps awake - Session keepalive + audio/visual notification monitoring for remote desktop apps
- Host: GitHub
- URL: https://github.com/slauger/espresso-macos
- Owner: slauger
- License: mit
- Created: 2026-01-09T10:07:21.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-01-12T13:07:05.000Z (5 months ago)
- Last Synced: 2026-01-12T17:11:14.618Z (5 months ago)
- Topics: citrix, keepalive, macos, menu-bar-app, notification-monitor, python, remote-desktop, teams
- Language: Python
- Homepage:
- Size: 1.9 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ☕ Espresso
**Keep your macOS apps awake and never miss a notification**
[](LICENSE)
[](https://www.python.org/downloads/)
---
## 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)
```bash
# 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](https://github.com/slauger/espresso-macos/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
```bash
# 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`
```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/`](examples/) for complete configuration examples.
## Advanced Features
### Audio Monitoring
Monitor audio from remote desktop to catch Teams calls and notifications.
📖 **[Audio Monitoring Setup Guide](docs/AUDIO_SETUP.md)**
### Screen Monitoring
Detect notifications visually via screenshot analysis and OCR.
📖 **[Screen Monitoring Setup Guide](docs/SCREEN_MONITORING.md)**
## Documentation
- 📖 [Audio Monitoring Setup](docs/AUDIO_SETUP.md)
- 📖 [Audio Fingerprinting](docs/AUDIO_FINGERPRINTING.md)
- 📖 [Screen Monitoring Setup](docs/SCREEN_MONITORING.md)
- 📖 [Development Guide](docs/DEVELOPMENT.md)
- 📖 [Homebrew Tap Setup](docs/HOMEBREW_SETUP.md) (for maintainers)
- 📋 [Config Examples](examples/)
## Development
### Build Your Own Binary
```bash
# 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](docs/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:
```bash
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](https://github.com/ExistentialAudio/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](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.