{"id":29061659,"url":"https://github.com/fullofcaffeine/espressobar","last_synced_at":"2026-04-16T19:43:55.891Z","repository":{"id":301059583,"uuid":"1008038111","full_name":"fullofcaffeine/EspressoBar","owner":"fullofcaffeine","description":"Your org repo's focus area. A persistent workbench for what matters right now. For emacs/orgmode enthusiasts.","archived":false,"fork":false,"pushed_at":"2025-06-25T00:29:14.000Z","size":0,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-25T00:29:24.685Z","etag":null,"topics":["claude","cursor","electron","emacs","focus","gtd","org","orgmode"],"latest_commit_sha":null,"homepage":"https://fullofcaffeine.co","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fullofcaffeine.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}},"created_at":"2025-06-24T23:47:15.000Z","updated_at":"2025-06-25T00:29:17.000Z","dependencies_parsed_at":"2025-06-25T00:41:05.043Z","dependency_job_id":null,"html_url":"https://github.com/fullofcaffeine/EspressoBar","commit_stats":null,"previous_names":["fullofcaffeine/espressobar"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/fullofcaffeine/EspressoBar","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fullofcaffeine%2FEspressoBar","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fullofcaffeine%2FEspressoBar/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fullofcaffeine%2FEspressoBar/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fullofcaffeine%2FEspressoBar/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fullofcaffeine","download_url":"https://codeload.github.com/fullofcaffeine/EspressoBar/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fullofcaffeine%2FEspressoBar/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262219803,"owners_count":23276888,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["claude","cursor","electron","emacs","focus","gtd","org","orgmode"],"created_at":"2025-06-27T08:03:14.525Z","updated_at":"2026-04-16T19:43:55.811Z","avatar_url":"https://github.com/fullofcaffeine.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# EspressoBar\n\n\u003e Your org repo's focus area. A persistent workbench for what matters right now.\n\nEspressoBar transforms pinned org-mode headlines into an always-ready tray application. Think of it as your **working memory** - a curated view of your current focus that persists across Emacs sessions and stays accessible from anywhere on your system.\n\nIt's alpha quality and still a WIP. There will be bugs and UX issues. Use at your own risk.\n\n![Showcase](./resources/showcase.png)\n\n## Features\n\n- **📌 Pin org headlines** with `:pinned:` tag and they appear in your tray\n- **🚀 Quick access** - System tray popup shows your focus area instantly\n- **⚡ Jump to Emacs** - \"Open in Emacs\" button opens files at exact lines\n- **💾 Persistent** - Your focus survives Emacs restarts and system reboots\n- **🎯 Background scanning** - Automatically finds pinned items across org directories\n\n## Quick Start\n\n1. **Pin something** in your org files:\n   ```org\n   * TODO Review Q4 planning deck    :pinned:\n   * NEXT Call Sarah about project timeline    :pinned:\n   ```\n\n2. **Start Emacs server** (add to your config):\n   ```elisp\n   (server-start)\n   ```\n\n3. **Install and run EspressoBar:**\n   ```bash\n   npm install\n   npm start\n   ```\n\n4. **Scan your org directories** in EspressoBar preferences\n\n5. **Access instantly** from the system tray - your focus area is always there\n\n6. **Jump to context** with \"Open in Emacs\" to continue where you left off\n\n## Emacs Integration\n\nEspressoBar uses `emacsclient` for seamless file opening - no complex setup required!\n\n### Setup\n\n**1. Ensure Emacs server is running:**\n```elisp\n;; Add to your Emacs config (.emacs, init.el, or Doom's config.el)\n(server-start)\n```\n\n**2. Verify your setup:**\n```bash\n# Test everything works\nnode tests/test-emacs-integration.js\n```\n\nThis test will check if `emacsclient` is installed and if Emacs server is running.\n\n### Installation by Platform\n\n**macOS:**\n```bash\nbrew install emacs  # Recommended\n```\n\n**Linux:**\n```bash\nsudo apt install emacs      # Ubuntu/Debian\nsudo pacman -S emacs        # Arch\n```\n\n**Windows:**\n```bash\nchoco install emacs         # Chocolatey\n```\n\n### Troubleshooting\n\n**\"emacsclient not found\":**\n- Install Emacs properly or ensure `emacsclient` is in your PATH\n- Restart EspressoBar after installation\n\n**\"Emacs server is not running\":**\n- Run `M-x server-start` in Emacs\n- Or add `(server-start)` to your Emacs config\n\n**Still having issues?**\n- Run the test script: `node tests/test-emacs-integration.js`\n- Check that `emacsclient --version` works in your terminal\n\n### How It Works\n\nWhen you click \"Open in Emacs\" on a pin:\n1. EspressoBar finds your `emacsclient` binary across platforms\n2. Runs `emacsclient --no-wait +LINE:1 /path/to/file.org`\n3. Emacs opens the file at the exact line of your org headline\n4. If emacsclient fails, elisp code is copied to your clipboard as fallback\n\n## Development\n\n### Getting Started\n\n```bash\nnpm install\nnpm start          # Development mode\nnpm run build      # Production build\nnpm run test:e2e   # End-to-end tests\n```\n\n### Release Management\n\nEspressoBar uses automated semantic versioning with [semantic-release](https://github.com/semantic-release/semantic-release). Releases are automatically created based on commit messages following [Conventional Commits](https://conventionalcommits.org/).\n\n**Commit Message Format:**\n- `fix: description` → Patch release (1.0.0 → 1.0.1)\n- `feat: description` → Minor release (1.0.0 → 1.1.0)\n- `feat!: description` or `BREAKING CHANGE:` → Major release (1.0.0 → 2.0.0)\n\n**Release Process:**\n1. Make changes using conventional commit messages\n2. Push to `main` branch or merge PR\n3. GitHub Actions automatically:\n   - Runs tests and builds for all platforms\n   - Determines next version from commits\n   - Generates changelog\n   - Creates GitHub release with artifacts\n   - Updates package.json version\n\n\n### Tech Stack\n\n- **Runtime**: Electron 28.x for cross-platform desktop app\n- **UI**: React 18 + Tailwind CSS + shadcn/ui components\n- **State**: Zustand for simple, focused state management\n- **Build**: Vite for fast development and optimized builds\n- **Config**: electron-store for persistent settings\n- **Testing**: Playwright for comprehensive E2E tests\n\n### Architecture\n\nEspressoBar follows a secure Electron architecture:\n\n- **Main Process**: Handles org file scanning, emacs integration, and system tray\n- **Preload Script**: Secure IPC bridge using contextBridge (no node integration)\n- **Renderer Process**: React app with strict security policies\n- **Services**: Modular backend services for org parsing, file caching, and emacs communication\n\n### Key Features Implemented\n\n✅ **Org File Scanning** - Recursive directory scanning with smart caching  \n✅ **Pin Detail View** - Rich content display with timestamps and metadata  \n✅ **Emacs Integration** - Cross-platform emacsclient support with fallbacks  \n✅ **Settings Persistence** - User preferences saved across sessions  \n✅ **Background Operation** - Efficient scanning without blocking UI  \n✅ **Test Coverage** - Comprehensive E2E test suite (30+ tests). No lower-level unit tests to keep things simple (might introduce if the app grows more complex in the future).\n\n## Testing\n\n### E2E Tests\n```bash\nnpm run test:e2e              # Run all tests\nnpm run test:e2e:ui          # Interactive test runner  \n```\n\n### Integration Testing\n```bash\nnode tests/test-emacs-integration.js  # Test emacs setup\n```\n\n## Philosophy\n\nYour org system is your **external brain**. EspressoBar is your **working memory** - the small set of things you're actively thinking about. By keeping this separate but connected, you maintain focus without losing the bigger picture.\n\n**Design Principles:**\n- **Focused**: Show only what's pinned, not everything\n- **Persistent**: Survives across sessions and context switches\n- **Accessible**: Always available from system tray\n- **Connected**: Seamless integration back to org files\n- **Simple**: Minimal setup, maximum utility\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Add tests for new functionality\n4. Ensure all E2E tests pass\n5. **Use conventional commit messages** (see Release Management section)\n6. Submit a pull request\n\n**Important:** This project uses automated semantic versioning. Please follow [Conventional Commits](https://conventionalcommits.org/) format for your commit messages to ensure proper version bumping and changelog generation.\n\nEspressoBar was \"guide-coded\" with Cursor / Sonnet 4 from scratch in about a day. Minor manual edits here and there from me. It also serves as an example of how to build a cross-platform Electron app with Cursor and how to setup a basic CI/release flow for it on GitHub.\n\n## License\n\nGPL-3.0-or-later - see LICENSE file for details\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffullofcaffeine%2Fespressobar","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffullofcaffeine%2Fespressobar","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffullofcaffeine%2Fespressobar/lists"}