Periodic Prompter Development

A skill for developing Periodic Prompter, a macOS menu bar application that periodically prompts users about their work plans using native macOS integrations.

What This Skill Does

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.

Architecture Overview

Core Components

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

Key Patterns

Data Storage Locations

Instructions

Initial Setup

1. Install dependencies using Poetry:

```bash

poetry install

```

Development Workflow

2. Run the application in development mode:

```bash

Preferred method using rumps

poetry run python -m periodic_prompter.main_rumps

Alternative method

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

Building the Application

4. Build the macOS .app bundle:

```bash

Using the build script (recommended)

poetry run python build_app.py

OR manually

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

Making Changes

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

Build System Details

The build configuration (`setup_simple.py`) includes:

Configuration

The application supports extensive configuration through the Settings GUI:

All settings are validated and have defaults in `Settings.DEFAULT_SETTINGS`.

Testing

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

Important Notes