activity-driver 1.0.4

Simulates realistic user activity on macOS

Activity Driver

Simulates realistic user activity (browser, file, HID mouse/keyboard events) on macOS. Prevents macOS idle sleep and auto-logout via caffeinate. Includes a live dashboard at http://localhost:3006.

Overview

Activity Driver is a Python library that simulates realistic work activity to maintain your online presence. It includes:

• Activity Driver — Core event simulation engine (browser, file, HID events)
• HID Events — Real OS-level HID event generation via macOS Quartz
• Daily Report — Live HTML dashboard showing activity metrics
• Launcher — Orchestrates Activity Driver + Daily Report together

---

Installation

Prerequisites

• macOS 10.13+
• Python 3.9+
• Google Chrome (for browser activity simulation)
• Accessibility Permission (for keyboard/mouse events)

System-Wide Install (Recommended)

pip install activity-driver

Development Install (editable)

pip install -e /path/to/activity-driver

Verify Installation

python -c "import activity_driver; print(activity_driver.__version__)"

---

Quick Start

First Time Setup

On first run, configure your settings:

activity-config show        # Display current settings
activity-config domains     # Add productive URLs
activity-config profile     # Set your Chrome profile

Settings are saved to ~/.config/activity-driver/config.json

Run All Components (Driver + Dashboard)

activity-launcher

This will:

1. Start the Activity Driver in the background
2. Start the Daily Report dashboard on http://localhost:3006
3. Auto-open your browser to the dashboard

Stop with Ctrl-C

Run Individual Components

Activity Driver only:

activity-driver

Daily Report only (on custom port):

activity-report 8080

From Python:

from activity_driver.activity_driver import main
main()

---

Configuration

Settings are saved to ~/.config/activity-driver/config.json and automatically used by the driver.

Manage Configuration Anytime

activity-config show        # Display current config
activity-config domains     # Edit productive URLs
activity-config profile     # Change Chrome profile
activity-config reset       # Reset to defaults

CLI Commands

activity-launcher

Start all components (driver + dashboard) together

activity-launcher

activity-driver

Run only the activity simulation engine

activity-driver

activity-report

Run only the dashboard (HTTP server)

activity-report 3006        # Default port
activity-report 8080        # Custom port

activity-config

Manage settings

activity-config show        # Display all settings
activity-config domains     # Edit productive URLs
activity-config profile     # Change Chrome profile
activity-config reset       # Reset to factory defaults

Permissions

Accessibility (Optional)

For keyboard clicks to work, grant Accessibility permission:

1. System Settings → Security & Privacy → Privacy → Accessibility
2. Add your Python interpreter or terminal app
3. Restart the driver

Without Accessibility: Mouse movement and scroll events still work, which is sufficient for most activity tracking systems.

Chrome Profile Access

The driver must be able to open Chrome. Ensure your profile is accessible in /Users/$USER/Library/Application\ Support/Google/Chrome/

---

Dashboard Features

The live dashboard at http://localhost:3006 shows:

• Total events — Total activity count for today/yesterday
• Event breakdown — Browser (unique/repeated), file writes, app switches
• Top URLs — Most frequently visited domains
• Hourly activity — Bar chart of events per hour
• Active window — First and last activity timestamps
• Auto-purge — Logs older than 2 days are automatically removed

Dashboard auto-refreshes every 30 seconds.

---

Technical Details

HID Event Generation

Real OS-level events via macOS Quartz API:

Event	Permission	Recognized by System
Mouse move	✅ NO Accessibility	✅ Yes (resets HIDIdleTime)
Scroll wheel	✅ NO Accessibility	✅ Yes
Click	⚠️ Accessibility required	✅ Yes
Keyboard	⚠️ Accessibility required	✅ Yes

Without Accessibility, mouse + scroll events are sufficient to reset system idle timers.

Idle Prevention

• Heartbeat — caffeinate -u runs every 25 seconds to assert user activity
• Anti-idle — Guaranteed lightweight event every 90 seconds during reads
• No gaps — Events spaced to ensure continuous activity detection

Log Format

Events are stored in .session_data as JSON:

{
  "ts": "2026-06-18T14:23:45",
  "date": "2026-06-18",
  "hour": 14,
  "type": "BROWSER",
  "label": "repeated",
  "detail": "https://example.com/shared"
}

Retention: 2 days (auto-purged)

---

Troubleshooting

"WARNING: Quartz not available"

Install the required dependency:

pip install pyobjc-framework-Quartz

Dashboard not loading

Check the port isn't in use:

lsof -i :3006

Use a custom port:

activity-report 8080

Chrome not opening URLs

1. Verify Chrome is installed at /Applications/Google Chrome.app
2. Check your Chrome profile name at chrome://version
3. Update CHROME_PROFILE in the driver config

Accessibility permission missing

Grant Accessibility permission in System Settings → Security & Privacy → Privacy

---

Development

Install for Development

pip install -e ".[dev]"

Run Tests

pytest -v
pytest --cov=src/activity_driver

Code Style

Format with Black:

black src/

Lint with Flake8:

flake8 src/

---

Uninstall

pip uninstall activity-driver

---

License

Proprietary License. All rights reserved.

---

Support

For issues, feature requests, or questions, see the GitHub repository documentation.

---

Version History

1.0.4 (2026-06-19)

• Fixed config variable assignment bug in activity_driver.py
• Improved README with CLI commands and prerequisites
• Better setup instructions for first-time users
• Removed all brand-specific references
• Complete documentation with permissions guide
• Clean, production-ready package for any Mac

1.0.0 (2026-06-18)

• Initial release
• Activity Driver core engine
• HID event generation (Quartz)
• Daily Report dashboard
• Launcher orchestrator
• macOS LaunchAgent support (via setup.sh)