Metadata-Version: 2.2
Name: activity-driver
Version: 1.0.4
Summary: Simulates realistic user activity on macOS
Home-page: https://github.com/amitsengar/activity-driver
Author: Amit Sengar
Author-email: Amit Sengar <amit.sengar@example.com>
License: Proprietary
Project-URL: Homepage, https://github.com/amitsengar/activity-driver
Project-URL: Documentation, https://github.com/amitsengar/activity-driver#readme
Project-URL: Bug Reports, https://github.com/amitsengar/activity-driver/issues
Project-URL: Repository, https://github.com/amitsengar/activity-driver.git
Keywords: activity,driver,automation,macOS,productivity
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyautogui>=0.9.54
Requires-Dist: pyobjc-framework-Quartz>=9.0; sys_platform == "darwin"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=3.0; extra == "dev"
Requires-Dist: black>=22.0; extra == "dev"
Requires-Dist: flake8>=4.0; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: requires-python

# 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)

```bash
pip install activity-driver
```

### Development Install (editable)

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

### Verify Installation

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

---

## Quick Start

### First Time Setup

On first run, configure your settings:

```bash
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)

```bash
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:**
```bash
activity-driver
```

**Daily Report only (on custom port):**
```bash
activity-report 8080
```

**From Python:**
```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

```bash
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
```bash
activity-launcher
```

### activity-driver
Run only the activity simulation engine
```bash
activity-driver
```

### activity-report
Run only the dashboard (HTTP server)
```bash
activity-report 3006        # Default port
activity-report 8080        # Custom port
```

### activity-config
Manage settings
```bash
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:

```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:

```bash
pip install pyobjc-framework-Quartz
```

### Dashboard not loading

Check the port isn't in use:

```bash
lsof -i :3006
```

Use a custom port:

```bash
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

```bash
pip install -e ".[dev]"
```

### Run Tests

```bash
pytest -v
pytest --cov=src/activity_driver
```

### Code Style

Format with Black:

```bash
black src/
```

Lint with Flake8:

```bash
flake8 src/
```

---

## Uninstall

```bash
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)
