HereIAm/README.md

HereIAm - Mouse Movement Monitor

Overview

HereIAm is a sophisticated macOS application that runs discretely in the system menu bar. It intelligently monitors mouse activity and automatically moves the cursor to prevent system inactivity when needed. The application features a clean PyQt5-based interface with adaptive theming and comprehensive logging.

Features

Core Functionality

• Smart Mouse Monitoring: Tracks mouse position and automatically moves cursor after a configurable period of inactivity
• System Menu Bar Integration: Runs as a native macOS menu bar application with context menu controls
• Adaptive Icon Theming: Automatically adjusts icons based on system dark/light mode
• Thread-Safe Operation: Mouse monitoring runs in a separate thread for responsive UI

User Interface

• Right-click Context Menu: Easy enable/disable controls with visual status indicators
• Double-click Toggle: Quick enable/disable by double-clicking the menu bar icon
• About Dialog: Displays application information and version details
• Status Display: Real-time status indication in the context menu

Advanced Features

• Comprehensive Logging: Detailed logging with configurable levels (DEBUG/INFO)
• Error Handling: Robust error handling and recovery mechanisms
• Configuration Management: Centralized configuration with easy customization
• System Integration: Proper macOS system tray integration with fail-safes

Installation

Prerequisites

• macOS (tested on macOS 10.14+)
• Python 3.8 or higher
• System with menu bar/system tray support

Setup Steps

1. Clone the repository:

   git clone <repository-url>
   cd HereIAm
   

2. Create a virtual environment (recommended):

   python3 -m venv .venv
   source .venv/bin/activate
   

3. Install dependencies:

   pip install -r requirements.txt
   

4. Install as package (optional):

   pip install -e .
   

Usage

Running the Application

From source:

python src/main.py

If installed as package:

hereiam

Using the Application

1. Launch: The application will appear in your menu bar with an icon
2. Enable/Disable: Right-click the icon to access the context menu
3. Quick Toggle: Double-click the icon for instant enable/disable
4. Status Monitoring: The icon changes to indicate current state:
   • ✅ Enabled: Green icon when mouse monitoring is active
   • ❌ Disabled: Gray icon (theme-aware) when monitoring is off

Menu Options

• Status: Shows current monitoring state
• Enable HereIAm: Starts mouse movement monitoring
• Disable HereIAm: Stops mouse movement monitoring
• About HereIAm: Application information and version
• Quit: Cleanly exits the application

Configuration

Main Settings (src/config.py)

WAITTIME = 240      # Wait time in seconds before moving mouse (default: 4 minutes)
MovePx = 10         # Pixels to move mouse (default: 10px)
StartEnabled = True # Start with monitoring enabled (default: True)
DEBUG = False       # Enable debug logging (default: False)

Logging Configuration

• Log Location: ~/.hereiam/logs/hereiam.log (same directory as config file)
• Log Persistence: Logs are persistent across reboots
• Log Rotation: Automatic (when DEBUG mode is enabled)
• Log Levels: INFO (default) or DEBUG (when DEBUG=True in options)

Startup Configuration

• Launch at Startup: Automatically launch HereIAm when you log in to macOS
• Implementation: Uses macOS Launch Agents (~/Library/LaunchAgents/)
• Requirements: Only available when using the built .app bundle
• Configuration: Can be enabled/disabled through the Options dialog

Dependencies

Core Runtime Dependencies

• PyQt5 (≥5.15.0): GUI framework and system tray integration
• pyautogui (≥0.9.54): Mouse movement and position detection
• pyobjc-framework-Cocoa (≥9.0): macOS system integration
• pyobjc-framework-Quartz (≥9.0): macOS graphics and display APIs

Development Dependencies (Optional)

• pytest (≥7.0.0): Testing framework
• black (≥22.0.0): Code formatting
• flake8 (≥4.0.0): Code linting

Project Structure

HereIAm/
├── src/                 # Source code
│   ├── main.py          # Application entry point and main GUI logic
│   ├── mouse_mover.py   # Mouse monitoring and movement logic
│   ├── config_manager.py # Configuration management
│   ├── logging_config.py # Logging configuration
│   ├── options_dialog.py # Options dialog UI
│   └── utils.py         # Utility functions and safety features
├── assets/              # Application assets
│   ├── Enabled.icns     # Icon for enabled state
│   ├── Disabled-Light.icns  # Icon for disabled state (light theme)
│   └── Disabled-Dark.icns   # Icon for disabled state (dark theme)
├── tests/               # Test scripts and test documentation
│   ├── test_config.py   # Configuration tests
│   ├── test_dialog.py   # Dialog functionality tests
│   ├── test_logging.py  # Logging tests
│   ├── test_restart.py  # Restart functionality tests
│   ├── test_app.sh      # App bundle integration tests
│   └── README.md        # Test documentation
├── build_app.sh         # Build script for macOS app bundle
├── create_dmg.sh        # DMG creation script
├── requirements.txt     # Python dependencies
├── requirements-build.txt # Build dependencies
├── setup.py             # Package installation configuration
└── README.md            # This file

Technical Details

Architecture

• Main Application (main.py): PyQt5-based GUI with system tray integration
• Mouse Monitor (mouse_mover.py): Threaded mouse position tracking and automatic movement
• Configuration (config.py): Centralized settings and logging configuration
• Utilities (utils.py): Safety features and error handling for mouse operations

How It Works

1. Monitoring: The application continuously tracks mouse position in a background thread
2. Timer Management: A countdown timer resets whenever mouse movement is detected
3. Automatic Movement: When the timer expires, the mouse is moved slightly and returned to position
4. User Feedback: The menu bar icon and status reflect the current monitoring state

Safety Features

• Bounds Checking: Mouse movements are constrained to screen boundaries
• Error Recovery: Comprehensive exception handling prevents crashes
• Graceful Shutdown: Clean thread termination and resource cleanup
• Fail-Safe Integration: PyAutoGUI safety features configured appropriately

Testing

The project includes comprehensive test scripts located in the tests/ directory.

Running Tests

Python Unit Tests:

cd tests
python3 test_config.py      # Test configuration management
python3 test_dialog.py      # Test options dialog
python3 test_logging.py     # Test logging functionality
python3 test_restart.py     # Test restart functionality

Application Bundle Test:

cd tests
./test_app.sh               # Test built macOS app bundle

Note: Make sure to build the application first with ./build_app.sh before running app bundle tests.

4. Testing Startup Functionality:

   ./test_startup.py
   

For detailed testing information, see tests/README.md.

Troubleshooting

Common Issues

Application doesn't appear in menu bar:

• Ensure system tray is available on your system
• Check that PyQt5 is properly installed
• Verify you have necessary permissions for GUI applications

Mouse movement not working:

• Check that accessibility permissions are granted to Terminal/Python
• Verify pyautogui installation: python -c "import pyautogui; print('OK')"
• Review logs in ~/.hereiam/logs/hereiam.log for error details

Icons not displaying:

• Verify all .icns files are present in the assets/ directory
• Check file permissions on the assets folder
• Enable DEBUG mode in config.py for detailed icon loading logs

Debugging

1. Enable debug mode in the Options dialog: set Log Level to "DEBUG"
2. Run from terminal to see console output
3. Check ~/.hereiam/logs/hereiam.log for detailed operation logs
4. Use Activity Monitor to verify the application is running

Development

Building from Source

# Setup development environment
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# Run in development mode
python src/main.py

Building for Distribution

Create macOS .app Bundle

# Install build dependencies
pip install -r requirements-build.txt

# Build the application
./build_app.sh

This creates dist/HereIAm.app - a standalone application bundle.

Create Distribution DMG

# Create installer DMG
./create_dmg.sh

This creates dist/HereIAm-1.0.0.dmg ready for distribution.

Full Distribution Workflow

# Complete build and package process
./build_app.sh && ./create_dmg.sh

See DISTRIBUTION.md for detailed building, code signing, and distribution instructions.

Creating a Standalone App (macOS)

# Install PyInstaller
pip install pyinstaller

# Create app bundle
pyinstaller --windowed --onefile --add-data "assets:assets" --icon="assets/Enabled.icns" src/main.py

Author & Support

Author: Jerico Thomas
Email: jerico@tekop.net
Version: 1.0.0

License

This project is licensed under the MIT License. See the LICENSE file for details.

---

HereIAm - Keeping your Mac awake, one mouse movement at a time.