ActivityWatch Skill

This skill generates project-level computer usage reports by combining ActivityWatch active window data with Codex thread metadata.

Install ActivityWatch

ActivityWatch must be installed and running before this skill can produce useful reports. Use the official ActivityWatch downloads page or the Getting started guide.

Recommended install paths:

• Windows: download and run the official installer.
• macOS: download the official .dmg, then drag ActivityWatch.app into Applications.
• Linux: use the .zip, .AppImage, AUR package, or Nix package listed on the official downloads page.

ActivityWatch includes the default AFK watcher and window watcher. These are the minimum required data sources for this skill: AFK data is used to remove away-from-keyboard time, and window data is used as the source of active computer time.

For stronger URL-based project attribution, install the ActivityWatch browser watcher for the browsers you use. Without it, the report can still use application/window titles and Codex metadata, but url rules will have less ActivityWatch data to match.

• Chrome/Edge extension: ActivityWatch Web Watcher
• Firefox extension: ActivityWatch - Open Source Time Tracker

You can verify ActivityWatch is collecting data by opening its web UI, normally available at:

http://localhost:5600

The script auto-detects the standard ActivityWatch database locations on macOS, Linux, and Windows. If ActivityWatch was installed with a non-default data location, pass the SQLite database explicitly:

node --experimental-strip-types scripts/generate-report.ts --period daily --activitywatch-db "/path/to/peewee-sqlite.v2.db"

When updating ActivityWatch on macOS, empty window titles can indicate stale Accessibility permissions. Remove ActivityWatch from the Accessibility permission list and add it again if that happens.

Autostart ActivityWatch

ActivityWatch should start when you log in so generated reports cover the whole work session. The official ActivityWatch autostart guide recommends starting aw-qt, which starts the server and the default watchers.

• Windows: autostart is configured automatically by the official installer.
• macOS: add ActivityWatch.app to your Login Items after installing it from the .dmg.
• Arch Linux: the activitywatch-bin AUR package configures autostart automatically when the desktop environment supports XDG Autostart. In other environments, enable XDG Autostart with dex or add aw-qt to the window manager startup configuration.
• Ubuntu: open Startup Applications, click Add, and use the path to the aw-qt executable as the command. For example: /home/<your username>/.local/opt/activitywatch/aw-qt.
• Other Linux and desktop environments: use the operating system's autostart settings and start the aw-qt executable from the ActivityWatch installation directory.

After enabling autostart, sign out and back in or reboot, then verify that the ActivityWatch web UI is available at http://localhost:5600 and that AFK/window data is being collected. If ActivityWatch runs behind a proxy, make sure NO_PROXY includes 127.0.0.1 before aw-qt starts.

Local Rules File

By default, auto-managed and manual project attribution rules are stored inside the current user's home directory:

• macOS: ~/.awcodex/rules.json
• Linux: ~/.awcodex/rules.json
• Windows PowerShell: $env:USERPROFILE\.awcodex\rules.json
• Windows cmd: %USERPROFILE%\.awcodex\rules.json

The schema is stored beside it:

• macOS: ~/.awcodex/rules.schema.json
• Linux: ~/.awcodex/rules.schema.json
• Windows PowerShell: $env:USERPROFILE\.awcodex\rules.schema.json
• Windows cmd: %USERPROFILE%\.awcodex\rules.schema.json

Reports are generated in the reports subdirectory beside rules.json:

• macOS: ~/.awcodex/reports
• Linux: ~/.awcodex/reports
• Windows PowerShell: $env:USERPROFILE\.awcodex\reports
• Windows cmd: %USERPROFILE%\.awcodex\reports

This keeps rules and generated reports shared across projects and Codex sessions instead of tying them to this repository. If you pass --rules with a different rules file, reports are written to the reports subdirectory beside that file.

Each report is written into a period-key subdirectory:

• Day: reports/2026-05-23/2026-05-23.md and .json
• Week: reports/2026-05-W1/2026-05-W1.md and .json
• Month: reports/2026-05/2026-05.md and .json
• Year: reports/2026/2026.md and .json

The same folder also contains excluded-only reports, for example reports/2026-05/2026-05-excluded.md and reports/2026-05/2026-05-excluded.json.

Rules can assign ActivityWatch windows to projects using directory, URL, application, and title patterns:

{
    "projects": [
        {
            "id": "activity-watch-skill",
            "name": "ActivityWatch Skill",
            "rules": [
                {
                    "dir": "/Users/danieleperilli/Dev/projects/activity-watch-skill"
                },
                {
                    "app": "Code",
                    "title": "*activity-watch-skill*"
                }
            ],
            "manual": true
        }
    ],
    "exclude": {
        "projects": [
            "personal"
        ],
        "rules": [
            {
                "app": "ActivityWatch"
            },
            {
                "app": "Chrome",
                "url": "localhost:5600"
            },
            {
                "title": "*private*"
            }
        ]
    }
}

• id: stable project identity used for sync, report ids, and exclusions. Keep it unchanged when renaming the project.
• name: display title used in reports; Codex sets it only when creating a new entry and never changes it during sync.
• rules: project attribution rules. Fields inside one rule object are AND conditions; multiple rule objects are OR alternatives.
• rules[].dir: static directory values match that directory and its children; wildcard patterns support * and ?.
• rules[].url: static values match when they appear in URL evidence; wildcard patterns support * and ?.
• rules[].app: static values match the ActivityWatch app name exactly, case-insensitively; wildcard patterns support * and ?.
• rules[].title: static values match when they appear in title evidence, and short values use word-boundary matching; wildcard patterns support * and ?.
• manual: set true when you own the rule and Codex must not modify it; set false when Codex may update it from discovered cwd and git metadata.
• exclude.projects: stable project ids to remove from reportable totals after allocation. Excluded time is tracked as excludedHours and in the excluded report.
• exclude.rules: global exclusion rules evaluated before project attribution. They use the same AND semantics as project rules and have priority over inclusion rules.

Auto-managed projects can keep adding dir and url rules while preserving your name edits. Codex does not create title rules because window and thread titles are fragile matching evidence. Legacy dirs, urls, apps, titles, exclude.apps, exclude.urls, and exclude.titles are migrated into the new rules format when the file is rewritten.

Allowing Codex To Write The Rules Directory

Codex runs with a filesystem sandbox. In workspace-write mode it can write only inside the current workspace and the configured writable roots. If the home-directory .awcodex folder is not a writable root, Codex may ask for approval when the report generator creates or updates rules.json.

To make the rules directory writable without per-command approval, add this top-level block to:

~/.codex/config.toml

macOS:

[sandbox_workspace_write]
writable_roots = [
    "~/.awcodex",
]

Linux:

[sandbox_workspace_write]
writable_roots = [
    "~/.awcodex",
]

Windows:

[sandbox_workspace_write]
writable_roots = [
    "C:/Users/<USER>/.awcodex",
]

Restart Codex Desktop or start a new Codex session after editing the config. Existing sessions usually do not pick up new writable roots retroactively.

For CLI sessions, the equivalent one-off option is:

codex -C /path/to/activity-watch-skill --add-dir "$HOME/.awcodex"

On Windows PowerShell:

codex -C C:\path\to\activity-watch-skill --add-dir "$env:USERPROFILE\.awcodex"