Develop and build Periodic Prompter, a macOS menu bar app that prompts users about their work plans at regular intervals
A skill for developing Periodic Prompter, a macOS menu bar application that periodically prompts users about their work plans using native macOS integrations.
This skill provides comprehensive guidance for working with the Periodic Prompter codebase, including building, running, and understanding the architecture of this Python-based macOS menu bar application.
The application follows a modular design with clear separation of concerns:
1. **main_rumps.py** - Primary entry point using rumps framework for native macOS menu bar integration
2. **scheduler.py** - Background thread triggering prompts at configured intervals using Python's `schedule` library
3. **notifications.py** - Handles user interactions via native macOS dialogs (AppleScript) with plyer fallback
4. **storage.py** - JSON-based persistent storage for plans, history, and application state
5. **settings.py** - Configuration management with validation and default values
6. **settings_gui.py** - Tkinter-based GUI for user configuration
1. Install dependencies using Poetry:
```bash
poetry install
```
2. Run the application in development mode:
```bash
poetry run python -m periodic_prompter.main_rumps
poetry run python -m periodic_prompter.main
```
3. Test changes by running the development version and verifying:
- Menu bar icon appears and displays current plan
- Prompts trigger at configured intervals
- Settings GUI opens and saves changes correctly
- Notifications display properly
4. Build the macOS .app bundle:
```bash
poetry run python build_app.py
poetry run python setup_simple.py py2app
```
5. Launch the built application:
```bash
open "dist/Periodic Prompter.app"
```
6. Verify the built app:
- Check it runs without dock icon (LSUIElement=True)
- Confirm menu bar integration works
- Test all features match development version
7. When modifying the codebase:
- **Menu Bar Updates**: Use `update_menu_title()` to update the display, NOT `setup_menu()` which would duplicate menu items
- **Settings Window**: Remember to create hidden Tkinter root window due to rumps/Tkinter interaction
- **Native Integration**: Prefer AppleScript for dialogs over cross-platform libraries for proper macOS behavior
- **Threading**: Ensure thread safety when updating UI elements from background threads
8. After code changes, rebuild and test the .app bundle to ensure py2app packaging works correctly
The build configuration (`setup_simple.py`) includes:
The application supports extensive configuration through the Settings GUI:
All settings are validated and have defaults in `Settings.DEFAULT_SETTINGS`.
Currently no formal test suite exists. Test manually by:
1. Building the application
2. Running it in various scenarios (different times of day, settings configurations)
3. Verifying prompt timing, notifications, and data persistence
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/periodic-prompter-development/raw