gerodp/hermes-productivity-skills / analytics/umami-report
umami-report
VerifiedPer-site visitor & pageview reports from a private (self-hosted) Umami instance.
Umami Report
Report visitor and pageview numbers for every website on a private, self-hosted Umami analytics instance — in one command. Zero dependencies (Python stdlib only); all sites are queried concurrently so a full report returns in a couple of seconds. Each metric is shown with its delta versus the previous equal-length period (▲/▼).
Script path: ~/.hermes/skills/analytics/umami-report/scripts/umami_report.py
When to Use
- User asks "how many visitors did my sites get?" / "traffic report" /
"umami stats" / "pageviews this week/month" →
report - User wants one site only →
report --site <name> - User wants a specific window →
report --days Nor--sinceor--start/--end - User wants machine-readable output to post-process →
report --json
Prerequisites
Python 3.8+ (stdlib only — no installs). Three environment variables, injected
automatically into the sandbox from ~/.hermes/.env:
UMAMI_URL, UMAMI_USERNAME, UMAMI_PASSWORD.
Always run check first. If it reports missing variables, the user must set
them themselves — guide them, do not collect secrets in chat:
hermes config # edit config, or
$EDITOR ~/.hermes/.env # add: UMAMI_URL=..., UMAMI_USERNAME=..., UMAMI_PASSWORD=...
~/.hermes/.env is mode 600. After editing, re-run check.
Secret Safety (MANDATORY)
- Never print, echo,
cat, or interpolate$UMAMI_PASSWORD(or the other vars) into a command line, log, or chat message. - Never ask the user to paste their password into the conversation — they
set it in
~/.hermes/.envon their own machine. - To confirm credentials work, use only the
checkcommand. The script is written to never print secrets or the auth token.
Commands
SCRIPT=~/.hermes/skills/analytics/umami-report/scripts/umami_report.py
check — verify config + login
python3 $SCRIPT check
Prints OK — authenticated to <url>; N website(s) visible. on success, or a
clear, secret-free error. Exit code is non-zero on any failure.
report — per-site visit table (default)
python3 $SCRIPT report # all sites, last 7 days
python3 $SCRIPT report --days 30 # last 30 days
python3 $SCRIPT report --since today # today so far
python3 $SCRIPT report --start 2026-06-01 --end 2026-06-07
python3 $SCRIPT report --site blog # only sites matching "blog"
python3 $SCRIPT report --days 30 --json # machine-readable
report is the default, so python3 $SCRIPT with no args == last 7 days.
Output columns: Site, Visitors, Visits, Pageviews, Bounce%, sorted by
pageviews descending, with a TOTAL row. Visitors/Visits/Pageviews each show
the ▲/▼ change versus the immediately preceding period of equal length. The
--json output additionally carries site_id (the Umami website id, for telling
multiple sites apart / verification), bounce_pct, avg_duration and
avg_duration_prev (average visit duration in seconds) per site.
Present the table to the user as-is (it's already aligned). When they ask about a single number, read it from the relevant cell rather than re-querying.
Pitfalls
--start/--endmust be given together (YYYY-MM-DD); the end date is inclusive (counts the whole day). They override--days/--since.- Dates/windows are computed in UTC for deterministic output; numbers may differ slightly from the Umami dashboard if it uses a local timezone.
- A wrong
UMAMI_URL(orhttpvshttps) shows up as a network/HTTP error fromcheck— fix the env var, don't retry blindly. - This skill targets self-hosted Umami (username/password login). Umami
Cloud uses an
x-umami-api-keyheader instead — not supported here.
Verification
python3 ~/.hermes/skills/analytics/umami-report/scripts/umami_report.py check
# → "OK — authenticated to https://...; N website(s) visible."
python3 ~/.hermes/skills/analytics/umami-report/scripts/umami_report.py report
# → aligned table of all sites for the last 7 days, with a TOTAL row.
Offline unit tests (no network) live next to the script:
python3 ~/.hermes/skills/analytics/umami-report/scripts/test_umami_report.py
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |