{"id":36630276,"url":"https://github.com/slauger/espresso-macos","last_synced_at":"2026-01-15T03:16:07.178Z","repository":{"id":332055170,"uuid":"1130992297","full_name":"slauger/espresso-macos","owner":"slauger","description":"Keep your macOS apps awake - Session keepalive + audio/visual notification monitoring for remote desktop apps","archived":false,"fork":false,"pushed_at":"2026-01-12T13:07:05.000Z","size":1996,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-12T17:11:14.618Z","etag":null,"topics":["citrix","keepalive","macos","menu-bar-app","notification-monitor","python","remote-desktop","teams"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/slauger.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-09T10:07:21.000Z","updated_at":"2026-01-12T13:07:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/slauger/espresso-macos","commit_stats":null,"previous_names":["slauger/espresso-macos"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/slauger/espresso-macos","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slauger%2Fespresso-macos","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slauger%2Fespresso-macos/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slauger%2Fespresso-macos/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slauger%2Fespresso-macos/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/slauger","download_url":"https://codeload.github.com/slauger/espresso-macos/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slauger%2Fespresso-macos/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28442254,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-15T00:55:22.719Z","status":"online","status_checked_at":"2026-01-15T02:00:08.019Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["citrix","keepalive","macos","menu-bar-app","notification-monitor","python","remote-desktop","teams"],"created_at":"2026-01-12T09:36:30.230Z","updated_at":"2026-01-15T03:16:07.172Z","avatar_url":"https://github.com/slauger.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"icons/icon-256.png\" alt=\"Espresso Logo\" width=\"128\" height=\"128\"\u003e\n\n  # ☕ Espresso\n\n  **Keep your macOS apps awake and never miss a notification**\n\n  [![License](https://img.shields.io/github/license/simonlauger/espresso)](LICENSE)\n  [![Python](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)\n\n\u003c/div\u003e\n\n---\n\n## What is Espresso?\n\nEspresso prevents session timeouts and monitors for notifications in remote desktop applications (like Citrix Viewer) on macOS.\n\n**Three monitoring modes:**\n- 🎹 **Keepalive** - Simulates keyboard activity to prevent timeouts\n- 🔔 **Audio Monitoring** - Detects Teams calls/notifications via audio\n- 📺 **Screen Monitoring** - Visual notification detection with OCR\n\n## Quick Start\n\n### Option 1: Homebrew (Easiest)\n\n```bash\n# Install directly (tap is added automatically)\nbrew install slauger/tap/espresso\n\n# Launch\nopen /Applications/Espresso.app\n```\n\nThe ☕ icon appears in your menu bar. Click it to enable features.\n\n\u003e **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`\n\n### Option 2: Download Binary\n\n1. Download the latest release from [GitHub Releases](https://github.com/slauger/espresso-macos/releases)\n2. Open the DMG and drag **Espresso.app** to Applications\n3. **First launch**: Right-click Espresso.app → \"Open\" → Click \"Open\" again\n   - macOS will show a Gatekeeper warning (app is not signed)\n   - Alternative: `xattr -cr /Applications/Espresso.app` in Terminal\n\nThe ☕ icon appears in your menu bar. Click it to enable features.\n\n\u003e **Note**: The app is not code-signed (requires Apple Developer Account $99/year). It's safe to run, source code is public.\n\n### Option 3: Install from Source\n\n```bash\n# Clone and install\ngit clone https://github.com/slauger/espresso-macos.git\ncd espresso-macos\npip install -e .[full]\n\n# Launch GUI (works without config!)\nespresso-gui\n\n# Optional: Setup autostart with config\nmkdir -p ~/.espresso\ncp examples/config-autostart.json ~/.espresso/config.json\n```\n\n## Features\n\n- ☕ **Universal** - Works with any macOS app (Citrix, Teams, Slack)\n- 🎨 **Menu Bar GUI** - Simple click-to-enable interface\n- ⚙️ **Configurable** - JSON config or command-line options\n- 🧠 **Smart** - Only monitors when app is running\n- 🔒 **Non-intrusive** - Keyboard simulation (no mouse movement)\n- 📦 **Lightweight** - Minimal resource usage\n\n## Configuration\n\n**Configuration is optional!** Espresso works out of the box with sensible defaults.\n\n### Optional: Create `~/.espresso/config.json`\n\n```json\n{\n  \"app_name\": \"Citrix Viewer\",\n  \"interval_seconds\": 60,\n  \"autostart\": true,\n  \"autostart_audio\": true,\n  \"audio_device\": \"BlackHole 2ch\"\n}\n```\n\n**Default values** (when no config exists):\n- `app_name`: \"Citrix Viewer\"\n- `interval_seconds`: 60\n- `autostart`: false (manual start)\n- `audio_device`: null (configure for audio monitoring)\n\nSee [`examples/`](examples/) for complete configuration examples.\n\n## Advanced Features\n\n### Audio Monitoring\nMonitor audio from remote desktop to catch Teams calls and notifications.\n\n📖 **[Audio Monitoring Setup Guide](docs/AUDIO_SETUP.md)**\n\n### Screen Monitoring\nDetect notifications visually via screenshot analysis and OCR.\n\n📖 **[Screen Monitoring Setup Guide](docs/SCREEN_MONITORING.md)**\n\n## Documentation\n\n- 📖 [Audio Monitoring Setup](docs/AUDIO_SETUP.md)\n- 📖 [Audio Fingerprinting](docs/AUDIO_FINGERPRINTING.md)\n- 📖 [Screen Monitoring Setup](docs/SCREEN_MONITORING.md)\n- 📖 [Development Guide](docs/DEVELOPMENT.md)\n- 📖 [Homebrew Tap Setup](docs/HOMEBREW_SETUP.md) (for maintainers)\n- 📋 [Config Examples](examples/)\n\n## Development\n\n### Build Your Own Binary\n\n```bash\n# Install dependencies\npip install -e .[full,dev]\n\n# Build with PyInstaller\npyinstaller espresso-gui.spec\n\n# Output: dist/Espresso.app\n```\n\n### Release Process\n\nReleases are automated via semantic-release:\n- Push to `main` with conventional commits (`feat:`, `fix:`, etc.)\n- GitHub Actions automatically:\n  - Creates git tag and GitHub Release\n  - Builds macOS binary (.app)\n  - Generates DMG and ZIP archives\n  - Updates Homebrew tap\n\nSee [HOMEBREW_SETUP.md](docs/HOMEBREW_SETUP.md) for Homebrew tap configuration.\n\n## Usage\n\n### Launch the App\n\n- **Binary**: Open Espresso.app from Applications\n- **From source**: Run `espresso-gui` in terminal\n\nClick the ☕ menu bar icon to:\n- Enable/disable keepalive\n- Enable/disable audio monitoring\n- Enable/disable screen monitoring\n- View status and logs\n\n### CLI (Optional)\n\nFor automation or headless usage:\n```bash\nespresso --app \"Citrix Viewer\" --interval 60 --config ~/.espresso/config.json\n```\n\n## Command-Line Options\n\n```\nespresso-gui [OPTIONS]\n\nOptions:\n  --app TEXT              Target application name (default: Citrix Viewer)\n  --interval INT          Seconds between keepalive actions (default: 60)\n  --audio-device TEXT     Audio device for monitoring (e.g., BlackHole)\n  --autostart            Start keepalive automatically\n  --autostart-audio      Start audio monitoring automatically\n  --autostart-screen     Start screen monitoring automatically\n  --debug                Enable verbose logging\n  --config PATH          Path to JSON config file\n```\n\n## Requirements\n\n- macOS 10.15+\n- Python 3.9+\n\n**Optional:**\n- [BlackHole](https://github.com/ExistentialAudio/BlackHole) for audio monitoring\n- Screen Recording permission for screen monitoring\n\n## Why \"Espresso\"?\n\nJust like a shot of espresso keeps *you* awake, this app keeps your *sessions* awake! ☕\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## Contributing\n\nIssues and pull requests welcome!\n\nFor major changes, please open an issue first to discuss what you'd like to change.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fslauger%2Fespresso-macos","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fslauger%2Fespresso-macos","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fslauger%2Fespresso-macos/lists"}