Skip to content
Back to search

cronalytics

Hermes Agent plugin for cron analytics and observability. The dashboard for agentic automations in Hermes.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/8bit64k--cronalytics/badge.svg)](/listings/8bit64k--cronalytics)

HTML

<a href="/listings/8bit64k--cronalytics"><img src="/api/listings/8bit64k--cronalytics/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

> The dashboard is insightful, but the CLI + Skill are the real superpower.

**Dashboard — *Observe***

Use the dedicated `/cronalytics` tab inside `hermes dashboard` for visual exploration. Charts, cards, and filters let you see cost, pace, and failure patterns at a glance.

**CLI — *Measure***

Use the terminal tool for programmatic access, `--json` output, and agent consumption. Precise queries, exact numbers, and scriptable data exports. Features eight commands, three global filters, and json output.

usage: cronalytics [-h] [--db DB] [--days DAYS] [--outcome {all,success,failure}]
                   [--mode {all,agent,no_agent}] [--json]
                   {summary,jobs,models,trends,health,runs,all,sync} ...

Cronalytics CLI — dump cron run insights to the terminal

positional arguments:
  {summary,jobs,models,trends,health,runs,all,sync}
    summary             Aggregate headline summary
    jobs                Per-job breakdown with pace
    models              Per-model estimated cost breakdown
    trends              Daily run-count / estimated cost sparkline
    health              Fact DB health check
    runs                Individual runs for a job
    all                 Run health + summary + jobs + models + trends
    sync                Backfill cron sessions from state.db into fact DB

options:
  -h, --help            show this help message and exit
  --db DB               Path to fact DB (default: auto-detected from plugin directory)
  --days DAYS           Number of days to look back (default: 30, 0 = all time)
  --outcome {all,success,failure}
                        Filter by outcome (default: all)
  --mode {all,agent,no_agent}
                        Filter by job mode (default: all)
  --json                Output raw JSON instead of formatted tables

**Agent Skill — *Optimize***

A built-in diagnostic skill that teaches Hermes agents how to analyze your cron jobs with confidence-graded anomaly detection and ranked recommendations. Ask your agent:

> "Check my cron jobs for the last two weeks — flag anything that looks off."

The agent loads the `cronalytics` skill, follows a structured 7-step diagnostic workflow (time window verification → baseline → job-level drill → per-run investigation → failure pattern → model economics → trend validation), cross-references `jobs.json`, and grades every finding by confidence (HIGH / MEDIUM / LOW) with supporting evidence and alternative explanations.

First-Time Setup

After install, the plugin needs data:

1. **Wait for a cron job to run** — the `on_session_end` hook captures it automatically. 2. **Or trigger a manual backfill** — click **Sync Now** in the dashboard.

If the dashboard shows "No cron jobs captured," click **Sync Now**.

See **[FAQ: Visibility & Data](docs/FAQ.md)** for more help — how data updates, how far back you can look, and the 250-run modal limit.

For full details about usage and common workflows see **[USAGE.md](docs/USAGE.md)**.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 396 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Cronalytics
  2. <a href="https://github.com/8bit64k/cronalytics/releases">
  3. <img src="https://img.shields.io/badge/Release-v1.1.0-blue" alt="Latest Release">
  4. </a>
  5. <a href="https://github.com/8bit64k/cronalytics/blob/master/LICENSE">
  6. <img src="https://img.shields.io/github/license/8bit64k/cronalytics" alt="License">
  7. </a>
  8. <a href="https://github.com/8bit64k/cronalytics/commits/master">
  9. <img src="https://img.shields.io/github/last-commit/8bit64k/cronalytics/master" alt="Last Commit">
  10. </a>
  11. <a href="https://github.com/8bit64k/cronalytics/actions/workflows/ci.yml">
  12. <img src="https://github.com/8bit64k/cronalytics/actions/workflows/ci.yml/badge.svg" alt="CI">
  13. </a>
  14. <a href="#">
  15. <img src="https://img.shields.io/badge/Hermes_Agent-supported-blueviolet.svg" alt="Hermes Agent">
  16. </a>
  17. <a href="https://x.com/intent/tweet?text=Check%20out%20this%20project%20on%20GitHub:%20https://github.com/8bit64k/cronalytics%20%23HermesAgent%20%23NousResearch">
  18. <img src="https://img.shields.io/badge/share-000000?logo=x&logoColor=white">
  19. </a>
  20. <a href="https://www.reddit.com/submit?title=Check%20out%20this%20project%20on%20GitHub:%20https://github.com/8bit64k/cronalytics">
  21. <img src="https://img.shields.io/badge/share-FF4500?logo=reddit&logoColor=white">
  22. </a>
  23. <a href="https://t.me/share/url?url=https://github.com/8bit64k/cronalytics&text=Check%20out%20this%20project%20on%20GitHub">
  24. <img src="https://img.shields.io/badge/share-0088CC?logo=telegram&logoColor=white">
  25. </a>
  26. [Watch this repo](https://github.com/8bit64k/cronalytics/subscription) to get notified of new releases. 👀
  27. <br/>
  28. /ˈkrɒn.əˌlɪt.ɪks/ (noun)
  29. 1. Cron analytics and observability.
  30. 2. The dashboard for agentic automations in Hermes.
  31. Observe. Measure. Optimize.
  32. Cronalytics is a Hermes Agent plugin that attributes session-level usage and estimated cost to every cron-originated run, so you can see what your scheduled jobs are costing you. It hooks into `on_session_end`, stores derived analytics in a local SQLite fact database, and surfaces them through **three** complementary interfaces: a hermes dashboard tab, a CLI tool for programmatic access, and an agent skill for cron health/diagnostics and comprehensive assessments. The current version is v1.1.0.
  33. > Built for **[Hermes Agent](https://github.com/nousresearch/hermes-agent)**, the autonomous agent framework by **[Nous Research](https://nousresearch.com)**.
  34. ---
  35. ## Getting Started
  36. | I am... | Path |
  37. | :--- | :--- |
  38. | **A New User** | [Install Guide (Fresh Start)](docs/INSTALL.md) |
  39. | **An Existing v1.0.x User** | [Upgrade Guide (v1.1 Migration)](docs/UPGRADE.md) |
  40. | **Exploring Features** | [Usage & Workflows](docs/USAGE.md) or [Feature Catalog](dev/FEATURES.md) |
  41. ---
  42. ## Quick Start and Usage
  43. > The dashboard is insightful, but the CLI + Skill are the real superpower.
  44. #### **Dashboard — *Observe***
  45. Use the dedicated `/cronalytics` tab inside `hermes dashboard` for visual exploration. Charts, cards, and filters let you see cost, pace, and failure patterns at a glance.
  46. #### **CLI — *Measure***
  47. Use the terminal tool for programmatic access, `--json` output, and agent consumption. Precise queries, exact numbers, and scriptable data exports. Features eight commands, three global filters, and json output.
  48. ```
  49. usage: cronalytics [-h] [--db DB] [--days DAYS] [--outcome {all,success,failure}]
  50. [--mode {all,agent,no_agent}] [--json]
  51. {summary,jobs,models,trends,health,runs,all,sync} ...
  52. Cronalytics CLI — dump cron run insights to the terminal
  53. positional arguments:
  54. {summary,jobs,models,trends,health,runs,all,sync}
  55. summary Aggregate headline summary
  56. jobs Per-job breakdown with pace
  57. models Per-model estimated cost breakdown
  58. trends Daily run-count / estimated cost sparkline
  59. health Fact DB health check
  60. runs Individual runs for a job
  61. all Run health + summary + jobs + models + trends
  62. sync Backfill cron sessions from state.db into fact DB
  63. options:
  64. -h, --help show this help message and exit
  65. --db DB Path to fact DB (default: auto-detected from plugin directory)
  66. --days DAYS Number of days to look back (default: 30, 0 = all time)
  67. --outcome {all,success,failure}
  68. Filter by outcome (default: all)
  69. --mode {all,agent,no_agent}
  70. Filter by job mode (default: all)
  71. --json Output raw JSON instead of formatted tables
  72. ```
  73. #### **Agent Skill — *Optimize***
  74. A built-in diagnostic skill that teaches Hermes agents how to analyze your cron jobs with confidence-graded anomaly detection and ranked recommendations. Ask your agent:
  75. > "Check my cron jobs for the last two weeks — flag anything that looks off."
  76. The agent loads the `cronalytics` skill, follows a structured 7-step diagnostic workflow (time window verification → baseline → job-level drill → per-run investigation → failure pattern → model economics → trend validation), cross-references `jobs.json`, and grades every finding by confidence (HIGH / MEDIUM / LOW) with supporting evidence and alternative explanations.
  77. ### First-Time Setup
  78. After install, the plugin needs data:
  79. 1. **Wait for a cron job to run** — the `on_session_end` hook captures it automatically.
  80. 2. **Or trigger a manual backfill** — click **Sync Now** in the dashboard.
  81. If the dashboard shows "No cron jobs captured," click **Sync Now**.
  82. See **[FAQ: Visibility & Data](docs/FAQ.md)** for more help — how data updates, how far back you can look, and the 250-run modal limit.
  83. For full details about usage and common workflows see **[USAGE.md](docs/USAGE.md)**.
  84. ---
  85. ## Features
  86. ### Mini-Tour
  87. <table>
  88. <tr>
  89. <td width="33%"><img src="docs/screenshots/S01_dashboard-english.png" width="100%" alt="English Dashboard"/></td>
  90. <td width="33%"><img src="docs/screenshots/S02_dashboard-chinese.png" width="100%" alt="Chinese Dashboard"/></td>
  91. <td width="33%"><img src="docs/screenshots/S03_dashboard-spanish.png" width="100%" alt="Spanish Dashboard"/></td>
  92. </tr>
  93. <tr>
  94. <td width="33%"><img src="docs/screenshots/S04_summary-success.png" width="100%" alt="Summary: Success mode"/></td>
  95. <td width="33%"><img src="docs/screenshots/S05_summary-failures.png" width="100%" alt="Summary: Failure mode"/></td>
  96. <td width="33%"><img src="docs/screenshots/S06_pace-modal.png" width="100%" alt="Pace explainer modal"/></td>
  97. </tr>
  98. <tr>
  99. <td width="33%"><img src="docs/screenshots/S07_model-breakdown.png" width="100%" alt="Per-model breakdown"/></td>
  100. <td width="33%"><img src="docs/screenshots/S08_jobs-breakdown.png" width="100%" alt="Jobs breakdown table"/></td>
  101. <td width="33%"><img src="docs/screenshots/S09_job-runs.png" width="100%" alt="Job run history modal"/></td>
  102. </tr>
  103. <tr>
  104. <td width="33%"><img src="docs/screenshots/S10_cli-summary.png" width="100%" alt="CLI summary output"/></td>
  105. <td width="33%"><img src="docs/screenshots/S11_cli-14-day-lead-to-assessment.png" width="100%" alt="CLI full report"/></td>
  106. <td width="33%"><img src="docs/screenshots/S12_agent-report-w-viz.png" width="100%" alt="Agent diagnostic report"/></td>
  107. </tr>
  108. </table>
  109. ---
  110. ### What Cronalytics Does
  111. - **Captures** every cron job run as it completes via the `on_session_end` hook
  112. - **Persists** cost, token counts, model, duration, and success state to a local fact database
  113. - **Backfills** historical data automatically on plugin load and on demand via reconciliation scanner
  114. - **Surfaces** data through three interfaces:
  115. ### Dashboard — visual exploration:
  116. - Summary cards (total runs, estimated cost, tokens, pace)
  117. - Leader board (top runs, top cost, top tokens, top pace)
  118. - Cost-by-model breakdown with proportional bars
  119. - Per-job table with runs, cost, duration, projections, and sortable columns
  120. - Expandable detail rows showing token breakdown, schedule, and success/failure split
  121. - Job detail modal with full run history (sortable, 200-run limit)
  122. - Educational modals explaining Pace, Nominal, Trend, and cost math
  123. - Outcome filter (All / Success / Failure) with conditional card colors
  124. - Mode filter (All / Agent / No agent) for script-only job visibility
  125. - Day selector `7D | 30D | 90D` presets + custom input (0–365 days, Enter/Go)
  126. - Refresh — re-fetches summary and jobs
  127. - Sync Now button to trigger backfill on demand
  128. **Multi-Locale Support**
  129. Cronalytics implements a self-hosted internationalization layer for independent Hermes plugins. All UI elements, educational explainers, and metrics are fully localized for:
  130. - 🇺🇸 **English** (Source of Truth)
  131. - 🇪🇸 **Spanish** (Professional/Technical)
  132. - 🇨🇳 **Chinese Simplified** (zh)
  133. - 🇹🇼 **Chinese Traditional** (zh-hant)
  134. ### CLI — terminal access:
  135. - `summary` — headline aggregates + leader board + cost-by-model table
  136. - `jobs` — per-job table with ID, runs, cost, tokens, pace, avg duration
  137. - `runs --job <id>` — individual run history (time, duration, cost, tokens, model)
  138. - `models` — per-model aggregate table
  139. - `trends` — daily bar chart (ASCII) of cost + runs
  140. - `health` — fact DB metadata, job count, last sync
  141. - `all` — chains health → summary → jobs → models → trends
  142. - All commands support `--days N`, `--outcome`, and `--mode`; every data command except `all` supports `--json`
  143. - Job name resolution from `~/.hermes/cron/jobs.json`
  144. ### Agent Skill — agent-guided diagnostics:
  145. - Structured 7-step workflow: time window verification → baseline → job-level drill → per-run investigation → failure pattern → model economics → trend validation
  146. - Confidence-graded anomaly detection (HIGH / MEDIUM / LOW)
  147. - `jobs.json` cross-reference for temporal context and silent failure detection
  148. - "Known Ways to Fool Yourself" guardrails prevent false positives
  149. - Works in any terminal session or messaging channel
  150. To explore the complete feature catalog see **[FEATURES.md](dev/FEATURES.md)**.
  151. ---
  152. ## ⚠️ Important Notes
  153. ### **Cost data is estimated, not exact.**
  154. Cronalytics reports the estimated cost that Hermes computed and stored in `state.db`. Your actual invoice may differ due to rate changes, credits, or rounding. Use this for directional awareness, not accounting.
  155. > See **[FAQ: Cost & Billing](docs/FAQ.md)** — $0.00 costs, estimated vs actual, and why Cronalytics differs from your provider invoice.
  156. ### Understanding Success
  157. **Cronalytics tracks two different notions of "success"**:
  158. | Signal | What It Means | Source |
  159. |--------|--------------|--------|
  160. | **Wrapper Success** (`success` toggle in dashboard) | The cron wrapper finished without error — the job ran, the agent responded, and the wrapper exited cleanly. | `end_reason` field |
  161. | **Payload Success** | The agent's actual output was correct, useful, or achieved the intended goal. | **Not tracked** |
  162. ### How to interpret the dashboard
  163. - **Success = high, Failure = low** → Your cron jobs are mechanically reliable.
  164. - **Success = high, but output quality is poor** → The infrastructure is fine; the issue is in the prompt, model choice, or task definition.
  165. - **Failure = high** → Investigate timeouts, API errors, or wrapper crashes.
  166. > The Success/Failure toggle is a **reliability** signal, not a **correctness** signal.
  167. See **[FAQ: Metrics & Interpretation](docs/FAQ.md)** for Success vs Failure, agent vs no-agent jobs, and what Pace really means.
  168. ### **Single-profile cron by default.**
  169. Cronalytics monitors the Hermes profile where it is installed. Most users — even those with multiple profiles configured — run cron jobs in the **default** profile. For them, Cronalytics works fully.
  170. The edge case: if you explicitly create a cron job under a non-default profile (`hermes --profile <name> cron create ...`), that job runs in an isolated gateway with its own `state.db`. Cronalytics, installed in the default profile, cannot see it.
  171. Multi-profile cron support is on our roadmap.
  172. See **[FAQ: Where are my jobs?](docs/FAQ.md)** for a checklist of common reasons jobs don't appear.
  173. ---
  174. ## Documentation Index
  175. ### User Documentation (`docs/`)
  176. - **[INSTALL.md](docs/INSTALL.md)** — Installation guide (dashboard plugin + pip CLI + skill setup)
  177. - **[UPGRADE.md](docs/UPGRADE.md)** — Transition guide for v1.0.x users (Namespace restructure)
  178. - **[UNINSTALL.md](docs/UNINSTALL.md)** — Clean removal instructions
  179. - **[USAGE.md](docs/USAGE.md)** — Dashboard and CLI usage guide
  180. - **[TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)** — Common issues and fixes
  181. - **[RELEASE_NOTES.md](docs/RELEASE_NOTES.md)** — Per-release upgrade notes and highlights
  182. - **[FAQ.md](docs/FAQ.md)** — Common questions and quick answers
  183. ### Developer Documentation (`dev/`)
  184. - **[BRIEF.md](dev/BRIEF.md)** — Product opportunity brief & positioning
  185. - **[DESIGN.md](dev/DESIGN.md)** — Architecture, data flow, and technical decisions
  186. - **[FEATURES.md](dev/FEATURES.md)** — Complete feature catalog with formulas
  187. - **[DEV_SETUP.md](dev/DEV_SETUP.md)** — Development environment setup
  188. ### Project Meta
  189. - **[CHANGELOG.md](CHANGELOG.md)** — Full version history
  190. ---
  191. ## Architecture at a Glance
  192. Cronalytics hooks into Hermes's `on_session_end`, enqueues session IDs, queries `state.db`, and stores derived analytics in a plugin-owned `facts.db`. Three interfaces read from that database: Dashboard (HTTP API), CLI (direct SQLite queries), and Agent Skill (CLI-piped heuristics).
  193. For the full architecture diagram, data flow, and technical decisions, see **[DESIGN.md](dev/DESIGN.md#3-architecture)**.
  194. ---
  195. ## API Endpoints
  196. All endpoints are mounted at `/api/plugins/cronalytics/`. Core endpoints: `GET /health`, `GET /summary`, `GET /jobs`, `GET /jobs/{job_id}/runs`, `GET /models`, `GET /trends`, `POST /sync`.
  197. For the full endpoint table with parameters and response shapes, see **[DESIGN.md §4.11 API Validation Layer](dev/DESIGN.md#411-api-validation-layer)**.
  198. ---
  199. ## Data Model
  200. The fact database (`facts.db`) is append-only — rows are inserted once and never updated or deleted. Core fields include `session_id`, `job_id`, `estimated_cost_usd`, `actual_cost_usd`, `model`, token breakdowns, `duration_seconds`, `end_reason`, and `success`.
  201. For the full schema with field descriptions, see **[DESIGN.md §4.3 Fact DB](dev/DESIGN.md#43-fact-db-plugin-owned-append-only-sqlite)**.
  202. ---
  203. ## File Layout
  204. ```
  205. cronalytics/
  206. ├─── plugin.yaml # Plugin manifest (hooks, version)
  207. ├─── __init__.py # Register hook + bootstrap scanner
  208. ├─── cronalytics/ # Core package
  209. │ ├── cli.py # Terminal interface (entry point)
  210. │ ├── config.py # Paths + defaults
  211. │ ├── facts.py # SQLite fact DB: schema, insert, queries
  212. │ ├── ingester.py # Deferred ingestion worker + crash recovery
  213. │ ├── scanner.py # Reconciliation scanner + watermark I/O
  214. │ ├── schedule.py # Cron parsing + projection math
  215. │ ├── logger.py # Shared logger
  216. │ └── checkpoint.py # Session state persistence
  217. ├─── skills/
  218. │ └─── devops/
  219. │ └─── cronalytics/
  220. │ └─── SKILL.md # Built-in diagnostic skill for agents
  221. ├─── dashboard/
  222. │ ├─── manifest.json # Slot registration + routes
  223. │ ├─── plugin_api.py # REST API mounted at /api/plugins/cronalytics/
  224. │ ├─── build.js # esbuild bundler script
  225. │ ├─── src/ # Modular frontend source
  226. │ └─── dist/
  227. │ └─── index.js # Bundled React frontend
  228. └─── tests/ # Unit tests (run with pytest)
  229. ```
  230. ---
  231. ## Configuration
  232. ### `plugin.yaml`
  233. ```yaml
  234. name: cronalytics
  235. version: 1.1.0
  236. description: Cost and operational observability for Hermes cron jobs
  237. provides_hooks:
  238. - on_session_end
  239. ```
  240. ### `config.py` (static defaults)
  241. All current settings are hardcoded defaults. There is no user-editable config file yet (planned for a future release).
  242. | Setting | Default | Meaning |
  243. |---------|---------|---------|
  244. | `RETRY_DELAYS` | `[3.0, 8.0, 15.0]` | Seconds to wait before each worker retry |
  245. | `JITTER_MAX` | `2.0` | Max random seconds added to each retry delay |
  246. | `MAX_RETRIES` | `3` | Total attempts to read a session from `state.db` |
  247. Paths are resolved automatically:
  248. - `STATE_DB`: `~/.hermes/state.db` (Hermes core session store)
  249. - `FACT_DB`: `~/.hermes/plugins/cronalytics/facts.db` (plugin-owned SQLite)
  250. - `WATERMARK_FILE`: `~/.hermes/plugins/cronalytics/watermark.json`
  251. - `PENDING_FILE`: `~/.hermes/plugins/cronalytics/pending.jsonl`
  252. ---
  253. ## Known Limitations
  254. 1. **Wrapper-level success only.** The `success` boolean reflects whether the session wrapper completed, not whether the agent task succeeded.
  255. 2. **Abandoned sessions are invisible.** Sessions where the gateway crashed or the job got stuck are never ingested (they never reach `ended_at`).
  256. 3. **No user-editable config file yet.** All tuning values are hardcoded in `config.py`.
  257. 4. **Actual cost is often null.** Most runs only populate `estimated_cost_usd`; `actual_cost_usd` depends on provider billing data.
  258. 5. **Dashboard server caches plugins per-process.** Changes to `manifest.json` or `plugin_api.py` require a full dashboard restart.
  259. 6. **Mobile layout tested but not optimized.** The table may require horizontal scroll on narrow viewports.
  260. 7. **Job detail modal capped at 200 runs.** High-frequency jobs show full count in the table but the drill-down is limited.
  261. See **[FAQ](docs/FAQ.md)** for more: the 250-run limit, agent vs no-agent, models breakdown, snapshotting your facts.db, and getting `cronalytics` on your PATH.
  262. ---
  263. ## Support
  264. Found a bug? Open a [GitHub Issue](https://github.com/8bit64k/cronalytics/issues) with reproduction steps. Have a feature idea? Open a [Discussion](https://github.com/8bit64k/cronalytics/discussions) or fork it.
  265. See **[SUPPORT.md](SUPPORT.md)** for the full help guide, FAQ, and response expectations.
  266. **Caveat**: The cost estimates are approximate and as recorded by the Hermes Agent framework. The success/failure signal is wrapper-level only (see [Understanding Success](#understanding-success)). Verify anything mission-critical independently.
  267. ---
  268. ## Requirements
  269. If you are running Hermes Agent you have everything you need:
  270. - Hermes Agent with plugin hook support (`on_session_end`)
  271. - Hermes dashboard server for UI components
  272. - SQLite (bundled with Python)
  273. ---
  274. ## License
  275. MIT — see [`LICENSE`](LICENSE) for full text.
  276. ---
  277. ## Acknowledgments
  278. Thanks to my wife **Gaby** for the Spanish translation review — and to everyone who starred, opened issues, and helped shape v1.1.
  279. ---
  280. ## Changelog
  281. See **[CHANGELOG.md](CHANGELOG.md)** for the full version history.
  282. ---
  283. *Plugin path: `~/.hermes/plugins/cronalytics/`*
  284. *Fact DB: `~/.hermes/plugins/cronalytics/facts.db`*
  285. *API base: `/api/plugins/cronalytics/`*

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.