activitywatch-integration

# ActivityWatch Integration Guide

## Purpose

Complete reference for working with ActivityWatch, its ecosystem of tools, watchers, client libraries, and integrations. Provides guidance for setup, configuration, custom watcher development, data analysis, and automation.

## When to Use

Activate this skill when:
- Setting up or configuring ActivityWatch
- Creating custom watchers or integrations
- Querying ActivityWatch data via API
- Integrating with external tools (Grafana, InfluxDB, AI agents)
- Troubleshooting ActivityWatch components
- Working with aw-client libraries
- Setting up multi-device sync
- Analyzing time-tracking data

## Table of Contents

- [Current Installation](#current-installation)
- [Core Components](#core-components)
- [Quick Start Guide](#quick-start-guide)
- [Tool Reference](#tool-reference)
- [Common Tasks](#common-tasks)
- [Troubleshooting](#troubleshooting)
- [Resources](#resources)

---

## Current Installation

**Status:** ✅ Installed and Running

**Details:**
- **Location:** `/Applications/ActivityWatch.app`
- **Version:** v0.13.2
- **Server:** http://localhost:5600
- **Installation Method:** Homebrew (`brew install --cask activitywatch`)

**Active Components:**
- `aw-qt` - System tray application (menu bar)
- `aw-server` - API server
- `aw-watcher-afk` - AFK detection
- `aw-watcher-window` - Window tracking

**Data Location:** `~/Library/Application Support/activitywatch/`

**Access:**
- Web UI: http://localhost:5600
- API: http://localhost:5600/api/0/

---

## Core Components

### 1. aw-qt (Desktop Application)

The main desktop tray app that manages everything.

**Key Features:**
- Autostart integration
- Watcher toggling
- Real-time activity views
- Settings management

**Access:** Menu bar icon (look for ActivityWatch icon)

### 2. aw-server (API Server)

REST API server for data storage and querying.

**Endpoints:**
- `/api/0/info` - Server information
- `/api/0/buckets` - List data buckets
- `/api/0/buckets/{id}/events` - Get/create events
- `/api/0/query` - Execute AQL queries

**See:** [API_REFERENCE.md](API_REFERENCE.md) for complete API documentation

### 3. aw-watcher Modules

Watchers are "agents" that track specific activities:

**Built-in:**
- `aw-watcher-window` - Active window/app tracking
- `aw-watcher-afk` - Keyboard/mouse activity (AFK detection)

**Optional:**
- `aw-watcher-web` - Browser tabs (install browser extension)
- `aw-watcher-vscode` - VS Code activity
- `aw-watcher-vim` - Vim/Neovim sessions

**Creating Custom Watchers:** See "Custom Watcher Development" section below

### 4. aw-client Libraries

Official SDKs for programmatic access:

**Available:**
- Python: `pip install aw-client`
- JavaScript: `aw-client-js`
- Go: `aw-client-go`
- Rust: `aw-client-rust`

**Use Cases:**
- Query and analyze data
- Create custom integrations
- Build automation scripts
- Export data to other formats

**See:** [API_REFERENCE.md](API_REFERENCE.md) for Python client examples

---

## Quick Start Guide

### Verify Installation

```bash
# Check if running
ps aux | grep activitywatch

# Test API
curl http://localhost:5600/api/0/info

# List buckets
curl http://localhost:5600/api/0/buckets
```

### Access Web UI

1. Open http://localhost:5600 in browser
2. View today's activity on Activity page
3. Configure settings in Settings page

### Enable Browser Extension

1. Visit https://activitywatch.net/downloads/
2. Install extension for your browser (Chrome, Firefox, Edge)
3. Extension will auto-connect to localhost:5600

### Python Client Setup

```bash
# Install
pip install aw-client

# Test
python3 -c "from aw_client import ActivityWatchClient; print(ActivityWatchClient().get_buckets())"
```

---

## Tool Reference

### aw-sync (Multi-Device Sync)

**Purpose:** Sync data across multiple devices via shared folder

**Installation:**
```bash
git clone https://github.com/ActivityWatch/aw-sync.git
cd aw-sync
pip install .
```

**Usage:**
```bash
# Sync to Dropbox
aw-sync --folder ~/Dropbox/ActivityWatch

# Automated sync (add to cron)
0 * * * * aw-sync --folder ~/sync/aw
```

**Cloud Options:**
- Dropbox
- Google Drive (via rclone)
- Syncthing (recommended for privacy)

### activitywatch-exporter (Analytics Integration)

**Purpose:** Export data to InfluxDB for Grafana dashboards

**Installation:**
```bash
pip install activitywatch-exporter
```

**Usage:**
```bash
activitywatch-exporter \
  --aw-url http://localhost:5600 \
  --influx-url http://localhost:8086 \
  --influx-db activitywatch
```

**See:** [INTEGRATIONS.md](INTEGRATIONS.md) for Grafana setup

### ActivityWatch MCP Server (AI Integration)

**Purpose:** AI agent interface for LLMs (Claude, Cursor)

**Installation:**
```bash
git clone https://github.com/Auriora/activitywatch-mcp.git
cd activitywatch-mcp
npm install
```

**Configuration for Claude Code:**
```json
{
  "mcpServers": {
    "activitywatch": {
      "command": "node",
      "args": ["/path/to/activitywatch-mcp/dist/index.js"],
      "env": {
        "AW_URL": "http://localhost:5600"
      }
    }
  }
}
```

**Example Queries:**
- "Summarize my coding hours this week"
- "What websites did I visit most yesterday?"
- "Show my most productive hours"

### Codewatch (Developer Focus)

**Purpose:** IDE-specific tracking with Git integration

**Features:**
- Multi-editor support
- Git commit analysis
- Project-based tracking
- Language statistics

**Installation:** Download from GitHub releases

---

## Common Tasks

### Query Data with Python

```python
from aw_client import ActivityWatchClient
from datetime import datetime, timedelta

client = ActivityWatchClient()

# Get today's window events
today = datetime.now().replace(hour=0, minute=0, second=0)
bucket_id = f"aw-watcher-window_{client.client_hostname}"
events = client.get_events(bucket_id, start=today)

# Calculate time per app
by_app = {}
for e in events:
    app = e["data"].get("app", "Unknown")
    by_app[app] = by_app.get(app, 0) + e["duration"]

# Print results
for app, duration in sorted(by_app.items(), key=lambda x: x[1], reverse=True):
    print(f"{app}: {duration/3600:.1f}h")
```

**See:** [API_REFERENCE.md](API_REFERENCE.md) for more examples

### Create Custom Watcher

```python
from aw_client import ActivityWatchClient
from datetime import datetime
import time

# Initialize
client = ActivityWatchClient("my-custom-watcher")
bucket_id = f"{client.client_name}_{client.client_hostname}"

# Create bucket
client.create_bucket(bucket_id, event_type="custom.activity")

# Send events
while True:
    event = {
        "timestamp": datetime.now(),
        "duration": 0,
        "data": {
            "label": "Custom activity",
            "value": get_custom_data()
        }
    }
    client.heartbeat(bucket_id, event, pulsetime=60)
    time.sleep(30)
```

### Export Data to CSV

```python
import pandas as pd
from aw_client import ActivityWatchClient

client = ActivityWatchClient()
bucket_id = f"aw-watcher-window_{client.client_hostname}"
events = client.get_events(bucket_id, limit=10000)

# Convert to DataFrame
df = pd.DataFrame([
    {
        "timestamp": e["timestamp"],
        "duration": e["duration"],
        "app": e["data"].get("app"),
        "title": e["data"].get("title")
    }
    for e in events
])

# Export
df.to_csv("activitywatch_export.csv", index=False)
print(f"✅ Exported {len(df)} events")
```

### Backup Data

```bash
#!/bin/bash
# backup-activitywatch.sh

DATE=$(date +%Y%m%d)
BACKUP_DIR=~/backups/activitywatch
mkdir -p $BACKUP_DIR

# Stop server
pkill -f aw-server

# Backup
tar -czf $BACKUP_DIR/aw-backup-$DATE.tar.gz \
  ~/Library/Application\ Support/activitywatch/

# Restart
/Applications/ActivityWatch.app/Contents/MacOS/aw-server &

echo "✅ Backup created: aw-backup-$DATE.tar.gz"
```

### Set Up Automation

**Daily Summary (cron):**
```bash
# Run at 6 PM daily
0 18 * * * /usr/bin/python3 /path/to/daily_summary.py
```

**Weekly Report (cron):**
```bash
# Run Sunday at 8 PM
0 20 * * 0 /usr/bin/python3 /path/to/weekly_report.py
```

**See:** [INTEGRATIONS.md](INTEGRATIONS.md) for Slack, email, and calendar integration examples

---

## Troubleshooting

### Server Not Starting

```bash
# Check if port in use
lsof -i :5600

# Kill existing process
pkill -f aw-server

# Start manually with debug
/Applications/ActivityWatch.app/Contents/MacOS/aw-server --verbose

# Check logs
tail -f ~/Library/Application\ Support/activitywatch/aw-server/aw-server.log
```

### Watchers Not Recording

```bash
# Check watcher status
curl http://localhost:5600/api/0/buckets

# Restart watchers
pkill -f aw-watcher
/Applications/ActivityWatch.app/Contents/MacOS/aw-watcher-afk &
/Applications/ActivityWatch.app/Contents/MacOS/aw-watcher-window &
```

### Database Issues

```bash
# Location
cd ~/Library/Application\ Support/activitywatch/aw-server/

# Check integrity
sqlite3 peewee-sqlite.v2.db "PRAGMA integrity_check;"

# Vacuum (reduce size)
sqlite3 peewee-sqlite.v2.db "VACUUM;"
```

### Permission Errors

```bash
# Fix permissions
chmod -R 755 ~/Library/Application\ Support/activitywatch/
```

---

## Configuration

### Server Settings

**Location:** `~/.config/activitywatch/aw-server/config.toml`

```toml
[server]
host = "127.0.0.1"  # Localhost only (recommended)
port = 5600         # Default port
cors_origins = "*"  # CORS settings
```

### Watcher Settings

**aw-watcher-afk:**
```toml
# ~/.config/activitywatch/aw-watcher-afk/config.toml
[aw-watcher-afk]
timeout = 180      # AFK timeout (seconds)
poll_time = 5      # Check interval
```

**aw-watcher-window:**
```toml
# ~/.config/activitywatch/aw-watcher-window/config.toml
[aw-watcher-window]
poll_time = 1           # Update interval
exclude_title = false   # Privacy: hide window titles
```

### Web UI Settings

Access via: http://localhost:5600/#/settings

**Categories:**
- Create rules to categorize activities
- Pattern matching on app, title, URL

**Example:**
```json
{
  "name": "Programming",
  "rule": {
    "$type": "regex",
    "regex": "VSCode|Terminal|vim"
  }
}
```

---

## Resources

### Official Documentation
- **Main Docs:** https://docs.activitywatch.net/
- **API Reference:** https://docs.activitywatch.net/en/latest/api/
- **Writing Watchers:** https://docs.activitywatch.net/en/latest/examples/writing-watchers.html

### Community
- **Forum:** https://forum.activitywatch.net/
- **Discord:** https://discord.gg/vDskV9q
- **GitHub:** https://github.com/ActivityWatch/activitywatch

### Related Projects
- **Browser Extension:** https://github.com/ActivityWatch/aw-watcher-web
- **VS Code Extension:** Marketplace → "ActivityWatch"
- **MCP Server:** https://github.com/Auriora/activitywatch-mcp

### Reference Files
- **[API_REFERENCE.md](API_REFERENCE.md)** - Complete REST API and AQL documentation
- **[INTEGRATIONS.md](INTEGRATIONS.md)** - Integration examples (Slack, Grafana, Sheets, etc.)

---

**Installation Status:** ✅ v0.13.2 via Homebrew
**Server:** ✅ http://localhost:5600
**Watchers:** ✅ afk, window active