Superproductivity Report

Super Productivity Report

Answer time-tracking questions from a Super Productivity data file — hours per project, hours per day, and tasks completed — for any window. Zero dependencies (Python stdlib only). Windows are computed in local time with Monday-start weeks. Completed/archived tasks are included (it reads the active list and archiveYoung/archiveOld).

Script path: ~/.hermes/skills/productivity/superproductivity-report/scripts/sp_report.py

When to Use

• "How many hours did I spend on Contoso this week?" →

projects --project contoso (default window is this week)

• "Hours per day this month?" → days --period this-month
• "Tasks I completed this week, by project?" → done
• "Time per project last month?" → projects --period last-month
• Any of the above for a custom range → --start/--end or --days N

Prerequisites

Python 3.8+ (stdlib only — no installs). One environment variable, injected automatically into the sandbox from ~/.hermes/.env:

• SP_DATA_FILE — absolute path to a Super Productivity JSON file.

Get that file one of two ways (either works — the skill auto-detects the shape):

1. Backup export (recommended, most stable): in the app, **Settings →

Sync & Export → Export Data**. Saves sp-backup_.json. Point SP_DATA_FILE at it. Re-export when you want fresh numbers.

1. Local file sync: enable Settings → Sync → Local File Sync and point it

at a folder; the app keeps sync-data.json updated there. Point SP_DATA_FILE at that sync-data.json for always-current data. (If you enabled sync encryption, the skill can't read it — use a backup export instead, or turn encryption off.)

Set the variable (do not paste the path into chat repeatedly — set it once):

hermes config           # edit config, or
$EDITOR ~/.hermes/.env  # add: SP_DATA_FILE=/Users/you/SuperProductivity/sync-data.json

Always run check first to confirm the file loads. You can also override the configured path ad hoc with --file PATH on any command.

Commands

SCRIPT=~/.hermes/skills/productivity/superproductivity-report/scripts/sp_report.py

check — verify the file loads + summary

python3 $SCRIPT check

Prints task/project counts, total tracked time, and the date span of the data. Run this first; if it errors, fix SP_DATA_FILE before reporting.

projects — hours per project (default)

python3 $SCRIPT projects                       # this week, all projects
python3 $SCRIPT projects --project contoso     # only projects whose TITLE matches "contoso"
python3 $SCRIPT projects --folder Contoso      # ALL projects inside the "Contoso" sidebar folder
python3 $SCRIPT projects --folder Contoso --detail   # + task list ordered by duration
python3 $SCRIPT projects --period this-month
python3 $SCRIPT projects --period last-month
python3 $SCRIPT projects --days 14
python3 $SCRIPT projects --start 2026-06-01 --end 2026-06-15
python3 $SCRIPT projects --json

projects is the default, so python3 $SCRIPT with no args == this week's per-project breakdown. Output: Project, Time (Hh MMm), Hours (decimal), Share%, sorted by time desc, with a TOTAL row.

--project NAME matches both project titles AND sidebar folder names — so --project Contoso returns the project literally titled "Contoso" and every project filed under the "Contoso" folder (e.g. CTS - Chatbot, whose title doesn't contain the word). Use --folder NAME to force folder-only matching. When the user asks how much time they spent on a named project/folder, add --detail so the answer includes the task breakdown ordered by time spent (most → least).

days — hours per day

python3 $SCRIPT days --period this-month        # one row per day this month
python3 $SCRIPT days                            # this week
python3 $SCRIPT days --project contoso          # only Contoso time, per day

Output: one row per calendar day in the window (including zero days), plus a TOTAL and an average-per-worked-day line.

done — tasks completed, grouped by project

python3 $SCRIPT done                            # this week
python3 $SCRIPT done --period last-week
python3 $SCRIPT done --project contoso

Lists every task whose completion date falls in the window, grouped by project, each with its completion date and total time spent. Sub-tasks are shown indented (↳).

Windows (shared by projects / days / done)

| Flag | Meaning | | --- | --- | | --period | today, this-week (default), last-week, this-month, last-month, this-year, last-year | | --days N | the last N days, inclusive of today | | --start / --end | explicit YYYY-MM-DD range (both required, end inclusive) | | --project NAME | filter to projects whose title OR sidebar folder contains NAME (case-insensitive) | | --folder NAME | filter to all projects inside the sidebar folder matching NAME (folder-only) | | --tag NAME | filter to tasks carrying a tag whose title contains NAME | | --detail | (projects) also list tasks ordered by duration, most→least | | --json | machine-readable output |

Precedence: --start/--end > --days > --period. Current periods (today, this-week, this-month, this-year) are capped at today so reports don't list empty future days.

How time is counted (read before interpreting numbers)

• Time comes from each task's timeSpentOnDay map (YYYY-MM-DD → ms). The skill

sums leaf tasks only — a parent task's time already rolls up its sub-tasks, so counting both would double-count. Filtering and per-day/per-project sums all use this rule.

• Date keys are local dates as Super Productivity recorded them (respecting

your "start of next day" setting), so day boundaries match the app, not UTC.

• done uses each task's doneOn timestamp (converted to a local date).
• A task with no project shows as (no project).

Pitfalls

• Stale file: a backup export is a point-in-time snapshot — re-export to get

today's numbers. sync-data.json updates live as long as the app is syncing.

• Encrypted sync: if check reports the file looks encrypted, use an

unencrypted backup export (or disable sync encryption). The skill never asks for an encryption key.

• --start/--end must be given together (YYYY-MM-DD); end is inclusive.
• "This week" is Monday→today; last-week is the full previous Mon–Sun.
• --project/--tag match on title substrings, case-insensitive — if a

filter returns nothing, run check (or projects unfiltered) to see the exact project titles.

Verification

python3 ~/.hermes/skills/productivity/superproductivity-report/scripts/sp_report.py check
# → "OK — loaded Super Productivity data." with counts and date span.

python3 ~/.hermes/skills/productivity/superproductivity-report/scripts/sp_report.py projects
# → per-project time table for this week, with a TOTAL row.

Offline unit tests (no file system, no network) live next to the script:

python3 ~/.hermes/skills/productivity/superproductivity-report/scripts/test_sp_report.py

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: gerodp
• Source: gerodp/hermes-productivity-skills
• License: MIT

Install and usage instructions live in the source repository linked above.