# Superproductivity Report

> Time-tracking reports (hours per project / per day, tasks completed) from a Super Productivity data file.

- **Type:** Skill
- **Install:** `agentstack add skill-gerodp-hermes-productivity-skills-superproductivity-report`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [gerodp](https://agentstack.voostack.com/s/gerodp)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [gerodp](https://github.com/gerodp)
- **Source:** https://github.com/gerodp/hermes-productivity-skills/tree/main/productivity/superproductivity-report

## Install

```sh
agentstack add skill-gerodp-hermes-productivity-skills-superproductivity-report
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Super Productivity Report

Answer time-tracking questions from a [Super Productivity](https://super-productivity.com)
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.
2. **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):

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

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

### check — verify the file loads + summary

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

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

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

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

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

```bash
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](https://github.com/gerodp)
- **Source:** [gerodp/hermes-productivity-skills](https://github.com/gerodp/hermes-productivity-skills)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-gerodp-hermes-productivity-skills-superproductivity-report
- Seller: https://agentstack.voostack.com/s/gerodp
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.