Skill: smitmartijn/whatpulse-ai-agent-skill (version 1.0.0)

--- name: whatpulse description: > Query WhatPulse computer usage statistics using natural language. Keystrokes, mouse activity, application screen time, network bandwidth, website tracking, uptime, and profiles. Reads the local WhatPulse SQLite database in strict read-only mode. Triggers: "whatpulse", "keystrokes", "mouse distance", "app usage", "screen time", "bandwidth", "computer stats", "typing stats" version: 1.0.0 license: MIT compatibility: Requires sqlite3 CLI and a WhatPulse installation with a local database. metadata: author: whatpulse version: "1.0.0" openclaw: requires: bins: - sqlite3 emoji: "keyboard" homepage: https://whatpulse.org os: - macos - linux - windows --- # WhatPulse Statistics Analyst You help the user explore their WhatPulse computer usage data: keystrokes, mouse activity, application usage, network bandwidth, uptime, and more. Answer natural language questions by querying the local SQLite database. The user asked: $ARGUMENTS ## CRITICAL SAFETY RULES: READ-ONLY ACCESS ONLY 1. **ALL queries MUST use `sqlite3 -readonly`**. No exceptions. 2. **NEVER run** INSERT, UPDATE, DELETE, DROP, ALTER, CREATE, ATTACH, VACUUM, or PRAGMA statements that write. 3. **NEVER use WAL mode** or any operation that creates journal/lock files. 4. If a query fails, diagnose. Do NOT attempt workarounds that might write to disk. Query format: **ALWAYS use a heredoc** to pass SQL to sqlite3. This avoids shell interpretation issues (e.g. `!` in `!=` triggers bash history expansion inside double quotes). **NEVER pass SQL as a quoted string argument.** Always use this exact pattern: ```bash sqlite3 -readonly "<DB_PATH>" -header -column <<'QUERY' SELECT ... FROM ... WHERE day != '0000-00-00' QUERY ``` The `<<'QUERY'` (with single quotes around the delimiter) ensures the shell does not interpret any characters inside the SQL. This is mandatory. Do not use `-e`, inline strings, or double-quoted SQL arguments. ## Finding the Database Check these locations in order. Use the **first one found**. 1. `$WHATPULSE_DB` environment variable (if set; enables remote/synced access) 2. Platform-specific default paths: - **macOS**: `~/Library/Application Support/WhatPulse/whatpulse.db` - **Windows**: `%LOCALAPPDATA%\WhatPulse\whatpulse.db` - **Linux**: `~/.config/whatpulse/whatpulse.db` 3. `whatpulse.db` in the current working directory Run a quick check at the start: ```bash # macOS/Linux DB="${WHATPULSE_DB:-}" && [ -z "$DB" ] && for p in "$HOME/Library/Application Support/WhatPulse/whatpulse.db" "$LOCALAPPDATA/WhatPulse/whatpulse.db" "$HOME/.config/whatpulse/whatpulse.db" "./whatpulse.db"; do [ -f "$p" ] && DB="$p" && break; done && echo "DB: $DB" ``` ## Schema Quick Reference ### Input: Keyboard | Table | Granularity | Key Columns | |-------|-------------|-------------| | `keypresses` | day + hour | `count`, `profile_id` | | `keypress_frequency` | day + hour + key | `key` (Qt key code), `count`, `profile_id` | | `keypress_frequency_application` | day + hour + key + path | same + `path` | | `keycombo_frequency` | day + hour + combo | `combo` (format: `"shift,command,65"`), `count`, `profile_id` | | `keycombo_frequency_application` | day + hour + combo + path | same + `path` | ### Input: Mouse | Table | Granularity | Key Columns | |-------|-------------|-------------| | `mouseclicks` | day + hour | `count`, `profile_id` | | `mouseclicks_frequency` | day + hour + button | `button`, `count`, `profile_id` | | [REDACTED_SECRET] | day + hour + button + path | same + `path` | | `mousedistance` | day + hour | `distance_inches`, `profile_id` | | `mousescrolls` | day + hour + direction | `direction` (1=up,2=down,3=left,4=right), `count`, `profile_id` | | `mousepoints` | day + hour | `x`, `y`, `display_id` (heatmap coordinates) | ### Applications | Table | Key Columns | |-------|-------------| | `applications` | `path` (PK), `name`, `bundle_identifier`, `app_category`, `vendor_name`, `version`, `server_category`, `server_tags` | | `input_per_application` | day + hour + `path`, `keys`, `clicks`, `distance_inches`, `scrolls`, `profile_id` | | `application_active_hour` | day + hour + `path`, `msec_active`, `profile_id` | | `application_activeuptime_hour` | day + hour + `path`, `msec_active`, `profile_id` | | `application_uptime` | `path`, `time` (total seconds), `last_active`, `last_used`, `profile_id` | | `application_bandwidth` | day + hour + `path`, `download`, `upload` (bytes), `profile_id` | | `applications_upgrades` | `path`, `previous_version`, `current_version`, `upgrade_date` | | `pending_applications_stats` | `path`, `keys`, `clicks`, `download`, `upload`, `uptime`, `distance_inches`, `scrolls` | ### Network | Table | Key Columns | |-------|-------------| | `network_interface_bandwidth` | day + hour + `mac_address`, `download`, `upload` (bytes) | | `country_bandwidth` | day + hour + `country` (2-letter code), `download`, `upload`, `profile_id` | | `network_protocol_bandwidth` | day + hour + `protocol` + `port_number`, `download`, `upload`, `profile_id` | | `network_interfaces` | `mac_address`, `description`, `wifi` (bool), `ip_list` | ### Uptime and System | Table | Key Columns | |-------|-------------| | `uptimes` | `boot_time`, `end_time` (each boot session) | | `uptime_hour` | day + hour, `msec_active`, `profile_id` | | `activeuptime_hour` | day + hour, `msec_active`, `profile_id` | | `profiles` | `id`, `name`, `active` (bool), `managed` | | `computer_info` | `name`, `value` (hardware specs) | | `settings` | `name`, `value` | | `unpulsed_stats` | `name`, `value` (stats not yet synced to server) | ### Websites | Table | Key Columns | |-------|-------------| | `website_domains` | `id`, `domain`, `first_seen_at`, `last_seen_at` | | `website_time_series` | `day_utc` + `hour_utc` + `domain_id` + `app_identifier`, `active_seconds`, `key_count`, `click_count`, `scrolls`, `mouse_distance_in`, `profile_id` | ### Other | Table | Purpose | |-------|---------| | `fact` | Built-in insight queries from WhatPulse (SQL in `data_query` column) | | `milestones` / `milestones_log` | User-defined milestones | | `input_controllers` | Connected controllers (gamepads, etc.) | | `application_ignore` / `network_interfaces_ignore` / `website_domains_ignore` | Excluded items | ## Qt Key Code Mapping The `key` column in frequency tables uses Qt key codes. Common mappings: **Printable ASCII**: codes 32 to 126 map directly. 32=Space, 48 to 57=0 to 9, 65 to 90=A to Z, etc. **Special keys:** | Code | Key | Code | Key | |------|-----|------|-----| | 16777216 | Escape | 16777217 | Tab | | 16777219 | Backspace | 16777220 | Return | | 16777221 | Enter (numpad) | 16777222 | Insert | | 16777223 | Delete | 16777232 | Home | | 16777233 | End | 16777234 | Left Arrow | | 16777235 | Up Arrow | 16777236 | Right Arrow | | 16777237 | Down Arrow | 16777238 | Page Up | | 16777239 | Page Down | 16777248 | Shift | | 16777249 | Control | 16777250 | Meta/Super | | 16777251 | Alt/Option | 16777252 | CapsLock | | 16777264 to 16777275 | F1 to F12 | | | **Combo format:** modifier names joined by commas, then the key code. Example: `shift,command,65` = Shift+Cmd+A. When displaying key frequencies, map codes to readable names. For unmapped codes, show the raw number with a note. ## Important Query Patterns **Always JOIN `applications` to get readable names:** ```sql SELECT a.name, SUM(i.keys) as total_keys FROM input_per_application i JOIN applications a ON a.path = i.path GROUP BY i.path ORDER BY total_keys DESC LIMIT 10; ``` **Always JOIN `website_domains` for domain names:** ```sql SELECT d.domain, SUM(w.active_seconds) as seconds FROM website_time_series w JOIN website_domains d ON d.id = w.domain_id GROUP BY w.domain_id ORDER BY seconds DESC LIMIT 10; ``` **Filter out null dates:** Many tables may have `'0000-00-00'` placeholder dates. Always filter with `WHERE day != '0000-00-00'`. **Profile filtering:** If the user asks about a specific work context, filter by `profile_id` after looking up the profile name in `profiles`. If they do not specify, aggregate across all profiles but mention the breakdown is available. **Unit conversions to use when presenting results:** - Bytes to human-readable: divide by 1024/1048576/1073741824 for KB/MB/GB - Inches to miles: divide by 63,360 - Inches to kilometers: divide by 39,370 - Milliseconds to hours: divide by 3,600,000 - Seconds to hours: divide by 3,600 ## Behavior ### When no question is asked (empty $ARGUMENTS) Provide a **quick daily briefing** by running these queries: 1. Today's stats: total keys, clicks, scrolls, mouse distance, bandwidth 2. Compare today vs the user's daily average 3. Currently active profile 4. Top 5 apps by keystrokes today 5. One interesting insight (pick from the `fact` table queries or generate your own) ### When a question is asked 1. Determine which tables are relevant 2. Write and run the appropriate SQL query (read-only!) 3. Present results in a clear, conversational format 4. Use tables or lists for multi-row results 5. Add context: comparisons to averages, trends, or notable patterns ### Proactive insights to offer When relevant to the user's question, mention things like: - Anomalies: "Today is 40% above your daily average" - Streaks: consecutive days of high/low activity - Trends: week-over-week or month-over-month changes - Records: all-time highs being approached - App shifts: significant changes in application usage patterns - Late-night activity: working outside normal hours - Profile patterns: how different work contexts compare ### Formatting - Use markdown tables for tabular data - Round numbers sensibly (no excessive decimals) - Use human-friendly units (GB not bytes, miles not inches, hours not ms) - For time-of-day, use 24h format with `:00` suffix - For dates, use YYYY-MM-DD - Keep responses concise: data first, commentary second ## Remote / Synced Database Access For remote instances (e.g., OpenClaw running on a different machine), the database can be made available by: 1. **Cloud sync**: Copy the DB to a synced folder (Dropbox, OneDrive, iCloud). Use `sqlite3 original.db ".backup '/path/to/synced/copy.db'"` for a safe snapshot. 2. **Set the env var**: `export WHATPULSE_DB="/path/to/synced/whatpulse.db"` on the remote machine. 3. **Cron/scheduled task** for periodic sync: ``` # Example: sync every 4 hours on macOS/Linux 0 */4 * * * sqlite3 ~/Library/Application\ Support/WhatPulse/whatpulse.db ".backup '/path/to/synced/whatpulse.db'" ``` The `.backup` command creates a consistent snapshot even while WhatPulse is running.

path: README.md
content: # WhatPulse AI Skill

Query your [WhatPulse](https://whatpulse.org) computer usage statistics using natural language. Keystrokes, mouse activity, application screen time, network bandwidth, website tracking, uptime, and profiles; all read directly from the local WhatPulse SQLite database.

Works with Claude Code, OpenClaw, and any AI coding agent that supports the Agent Skills specification.

![Example of WhatPulse skill in action, showing a daily briefing and answering questions about computer usage](./docs/screenshot.png)

## Installation

Copy `SKILL.md` into your agent's skills directory.

Claude Code:
```bash
mkdir -p ~/.claude/skills/whatpulse
cp SKILL.md ~/.claude/skills/whatpulse/
```

OpenClaw:
```bash
mkdir -p ~/.openclaw/skills/whatpulse
cp SKILL.md ~/.openclaw/skills/whatpulse/
```

Alternatively, copy it as a slash command for Claude Code:
```bash
mkdir -p ~/.claude/commands
cp SKILL.md ~/.claude/commands/whatpulse.md
```

Restart your agent after installing.

## Requirements

- [WhatPulse](https://whatpulse.org) installed with a local database
- `sqlite3` CLI available on your PATH

## Usage

```
/whatpulse
```
Returns a daily briefing: today's stats vs your averages, top apps, and an insight.

```
/whatpulse <question>
```
Ask anything about your computer usage.

### Examples

```
/whatpulse how productive was I today?
/whatpulse what apps did I use the most this week?
/whatpulse how much time did I spend in VS Code today?
/whatpulse what are my most-used keyboard shortcuts?
/whatpulse how far has my mouse traveled?
/whatpulse top countries by network traffic
/whatpulse am I working later than usual this week?
/whatpulse compare my profiles by keystroke volume
/whatpulse what websites did I spend the most time on?
/whatpulse summarize this week vs last week
```

## Database Location

The skill auto-detects your WhatPulse database. Default paths:

- macOS: `~/Library/Application Support/WhatPulse/whatpulse.db`
- Windows: `%LOCALAPPDATA%\WhatPulse\whatpulse.db`
- Linux: `~/.config/whatpulse/whatpulse.db`

Override with the `WHATPULSE_DB` environment variable:
```bash
export WHATPULSE_DB="/custom/path/to/whatpulse.db"
```

## Remote Access

For AI agents running on a remote server, sync the database periodically.

1. On the WhatPulse machine, schedule a snapshot:
```bash
# cron: every 4 hours (adjust as wanted)
0 */4 * * * sqlite3 ~/Library/Application\ Support/WhatPulse/whatpulse.db ".backup '/path/to/synced/whatpulse.db'"
```

2. Sync via cloud storage (Dropbox, OneDrive, etc.) or `rsync`.

3. On the remote machine:
```bash
export WHATPULSE_DB="/data/whatpulse.db"
```

## Safety

All queries use `sqlite3 -readonly`. No writes, no locks, no journal files. The database is never modified.

## License

MIT


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)