Install
$ npx skills add 8bit64k/cronalyticsREADME
# GitHub Repository: 8bit64k/cronalytics
**URL:** https://github.com/8bit64k/cronalytics
**Author:** 8bit64k
**Description:** Hermes Agent plugin for cron analytics and observability. The dashboard for agentic automations in Hermes.
**Homepage:**
**Language:** Python
## Stats
- Stars: 95
- Forks: 2
- Open Issues: 1
- Commits: 374
- Created: 2026-05-12T17:33:06Z
- Updated: 2026-06-24T17:58:59Z
- Pushed: 2026-06-24T17:58:27Z
## README
# Cronalytics
<a href="https://github.com/8bit64k/cronalytics/releases">
<img src="https://img.shields.io/badge/Release-v1.1.0-blue" alt="Latest Release">
</a>
<a href="https://github.com/8bit64k/cronalytics/blob/master/LICENSE">
<img src="https://img.shields.io/github/license/8bit64k/cronalytics" alt="License">
</a>
<a href="https://github.com/8bit64k/cronalytics/commits/master">
<img src="https://img.shields.io/github/last-commit/8bit64k/cronalytics/master" alt="Last Commit">
</a>
<a href="https://github.com/8bit64k/cronalytics/actions/workflows/ci.yml">
<img src="https://github.com/8bit64k/cronalytics/actions/workflows/ci.yml/badge.svg" alt="CI">
</a>
<a href="#">
<img src="https://img.shields.io/badge/Hermes_Agent-supported-blueviolet.svg" alt="Hermes Agent">
</a>
<a href="https://x.com/intent/tweet?text=Check%20out%20this%20project%20on%20GitHub:%20https://github.com/8bit64k/cronalytics%20%23HermesAgent%20%23NousResearch">
<img src="https://img.shields.io/badge/share-000000?logo=x&logoColor=white">
</a>
<a href="https://www.reddit.com/submit?title=Check%20out%20this%20project%20on%20GitHub:%20https://github.com/8bit64k/cronalytics">
<img src="https://img.shields.io/badge/share-FF4500?logo=reddit&logoColor=white">
</a>
<a href="https://t.me/share/url?url=https://github.com/8bit64k/cronalytics&text=Check%20out%20this%20project%20on%20GitHub">
<img src="https://img.shields.io/badge/share-0088CC?logo=telegram&logoColor=white">
</a>
[Watch this repo](https://github.com/8bit64k/cronalytics/subscription) to get notified of new releases. 👀
<br/>
/ˈkrɒn.əˌlɪt.ɪks/ (noun)
1. Cron analytics and observability.
2. The dashboard for agentic automations in Hermes.
Observe. Measure. Optimize.
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.
> Built for **[Hermes Agent](https://github.com/nousresearch/hermes-agent)**, the autonomous agent framework by **[Nous Research](https://nousresearch.com)**.
---
## Getting Started
| I am... | Path |
| :--- | :--- |
| **A New User** | [Install Guide (Fresh Start)](docs/INSTALL.md) |
| **An Existing v1.0.x User** | [Upgrade Guide (v1.1 Migration)](docs/UPGRADE.md) |
| **Exploring Features** | [Usage & Workflows](docs/USAGE.md) or [Feature Catalog](dev/FEATURES.md) |
---
## Quick Start and Usage
> 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)**.
---
## Features
### Mini-Tour
<table>
<tr>
<td width="33%"><img src="docs/screenshots/S01_dashboard-english.png" width="100%" alt="English Dashboard"/></td>
<td width="33%"><img src="docs/screenshots/S02_dashboard-chinese.png" width="100%" alt="Chinese Dashboard"/></td>
<td width="33%"><img src="docs/screenshots/S03_dashboard-spanish.png" width="100%" alt="Spanish Dashboard"/></td>
</tr>
<tr>
<td width="33%"><img src="docs/screenshots/S04_summary-success.png" width="100%" alt="Summary: Success mode"/></td>
<td width="33%"><img src="docs/screenshots/S05_summary-failures.png" width="100%" alt="Summary: Failure mode"/></td>
<td width="33%"><img src="docs/screenshots/S06_pace-modal.png" width="100%" alt="Pace explainer modal"/></td>
</tr>
<tr>
<td width="33%"><img src="docs/screenshots/S07_model-breakdown.png" width="100%" alt="Per-model breakdown"/></td>
<td width="33%"><img src="docs/screenshots/S08_jobs-breakdown.png" width="100%" alt="Jobs breakdown table"/></td>
<td width="33%"><img src="docs/screenshots/S09_job-runs.png" width="100%" alt="Job run history modal"/></td>
</tr>
<tr>
<td width="33%"><img src="docs/screenshots/S10_cli-summary.png" width="100%" alt="CLI summary output"/></td>
<td width="33%"><img src="docs/screenshots/S11_cli-14-day-lead-to-assessment.png" width="100%" alt="CLI full report"/></td>
<td width="33%"><img src="docs/screenshots/S12_agent-report-w-viz.png" width="100%" alt="Agent diagnostic report"/></td>
</tr>
</table>
---
### What Cronalytics Does
- **Captures** every cron job run as it completes via the `on_session_end` hook
- **Persists** cost, token counts, model, duration, and success state to a local fact database
- **Backfills** historical data automatically on plugin load and on demand via reconciliation scanner
- **Surfaces** data through three interfaces:
### Dashboard — visual exploration:
- Summary cards (total runs, estimated cost, tokens, pace)
- Leader board (top runs, top cost, top tokens, top pace)
- Cost-by-model breakdown with proportional bars
- Per-job table with runs, cost, duration, projections, and sortable columns
- Expandable detail rows showing token breakdown, schedule, and success/failure split
- Job detail modal with full run history (sortable, 200-run limit)
- Educational modals explaining Pace, Nominal, Trend, and cost math
- Outcome filter (All / Success / Failure) with conditional card colors
- Mode filter (All / Agent / No agent) for script-only job visibility
- Day selector `7D | 30D | 90D` presets + custom input (0–365 days, Enter/Go)
- Refresh — re-fetches summary and jobs
- Sync Now button to trigger backfill on demand
**Multi-Locale Support**
Cronalytics implements a self-hosted internationalization layer for independent Hermes plugins. All UI elements, educational explainers, and metrics are fully localized for:
- 🇺🇸 **English** (Source of Truth)
- 🇪🇸 **Spanish** (Professional/Technical)
- 🇨🇳 **Chinese Simplified** (zh)
- 🇹🇼 **Chinese Traditional** (zh-hant)
### CLI — terminal access:
- `summary` — headline aggregates + leader board + cost-by-model table
- `jobs` — per-job table with ID, runs, cost, tokens, pace, avg duration
- `runs --job <id>` — individual run history (time, duration, cost, tokens, model)
- `models` — per-model aggregate table
- `trends` — daily bar chart (ASCII) of cost + runs
- `health` — fact DB metadata, job count, last sync
- `all` — chains health → summary → jobs → models → trends
- All commands support `--days N`, `--outcome`, and `--mode`; every data command except `all` supports `--json`
- Job name resolution from `~/.hermes/cron/jobs.json`
### Agent Skill — agent-guided diagnostics:
- Structured 7-step workflow: time window verification → baseline → job-level drill → per-run investigation → failure pattern → model economics → trend validation
- Confidence-graded anomaly detection (HIGH / MEDIUM / LOW)
- `jobs.json` cross-reference for temporal context and silent failure detection
- "Known Ways to Fool Yourself" guardrails prevent false positives
- Works in any terminal session or messaging channel
To explore the complete feature catalog see **[FEATURES.md](dev/FEATURES.md)**.
---
## ⚠️ Important Notes
### **Cost data is estimated, not exact.**
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.
> See **[FAQ: Cost & Billing](docs/FAQ.md)** — $0.00 costs, estimated vs actual, and why Cronalytics differs from your provider invoice.
### Understanding Success
**Cronalytics tracks two different notions of "success"**:
| Signal | What It Means | Source |
|--------|--------------|--------|
| **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 |
| **Payload Success** | The agent's actual output was correct, useful, or achieved the intended goal. | **Not tracked** |
### How to interpret the dashboard
- **Success = high, Failure = low** → Your cron jobs are mechanically reliable.
- **Success = high, but output quality is poor** → The infrastructure is fine; the issue is in the prompt, model choice, or task definition.
- **Failure = high** → Investigate timeouts, API errors, or wrapper crashes.
> The Success/Failure toggle is a **reliability** signal, not a **correctness** signal.
See **[FAQ: Metrics & Interpretation](docs/FAQ.md)** for Success vs Failure, agent vs no-agent jobs, and what Pace really means.
### **Single-profile cron by default.**
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.
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.
Multi-profile cron support is on our roadmap.
See **[FAQ: Where are my jobs?](docs/FAQ.md)** for a checklist of common reasons jobs don't appear.
---
## Documentation Index
### User Documentation (`docs/`)
- **[INSTALL.md](docs/INSTALL.md)** — Installation guide (dashboard plugin + pip CLI + skill setup)
- **[UPGRADE.md](docs/UPGRADE.md)** — Transition guide for v1.0.x users (Namespace restructure)
- **[UNINSTALL.md](docs/UNINSTALL.md)** — Clean removal instructions
- **[USAGE.md](docs/USAGE.md)** — Dashboard and CLI usage guide
- **[TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)** — Common issues and fixes
- **[RELEASE_NOTES.md](docs/RELEASE_NOTES.md)** — Per-release upgrade notes and highlights
- **[FAQ.md](docs/FAQ.md)** — Common questions and quick answers
### Developer Documentation (`dev/`)
- **[BRIEF.md](dev/BRIEF.md)** — Product opportunity brief & positioning
- **[DESIGN.md](dev/DESIGN.md)** — Architecture, data flow, and technical decisions
- **[FEATURES.md](dev/FEATURES.md)** — Complete feature catalog with formulas
- **[DEV_SETUP.md](dev/DEV_SETUP.md)** — Development environment setup
### Project Meta
- **[CHANGELOG.md](CHANGELOG.md)** — Full version history
---
## Architecture at a Glance
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).
For the full architecture diagram, data flow, and technical decisions, see **[DESIGN.md](dev/DESIGN.md#3-architecture)**.
---
## API Endpoints
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`.
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)**.
---
## Data Model
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`.
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)**.
---
## File Layout
```
cronalytics/
├─── plugin.yaml # Plugin manifest (hooks, version)
├─── __init__.py # Register hook + bootstrap scanner
├─── cronalytics/ # Core package
│ ├── cli.py # Terminal interface (entry point)
│ ├── config.py # Paths + defaults
│ ├── facts.py # SQLite fact DB: schema, insert, queries
│ ├── ingester.py # Deferred ingestion worker + crash recovery
│ ├── scanner.py # Reconciliation scanner + watermark I/O
│ ├── schedule.py # Cron parsing + projection math
│ ├── logger.py # Shared logger
│ └── checkpoint.py # Session state persistence
├─── skills/
│ └─── devops/
│ └─── cronalytics/
│ └─── SKILL.md # Built-in diagnostic skill for agents
├─── dashboard/
│ ├─── manifest.json # Slot registration + routes
│ ├─── plugin_api.py # REST API mounted at /api/plugins/cronalytics/
│ ├─── build.js # esbuild bundler script
│ ├─── src/ # Modular frontend source
│ └─── dist/
│ └─── index.js # Bundled React frontend
└─── tests/ # Unit tests (run with pytest)
```
---
## Configuration
### `plugin.yaml`
```yaml
name: cronalytics
version: 1.1.0
description: Cost and operational observability for Hermes cron jobs
provides_hooks:
- on_session_end
```
### `config.py` (static defaults)
All current settings are hardcoded defaults. There is no user-editable config file yet (planned for a future release).
| Setting | Default | Meaning |
|---------|---------|---------|
| `RETRY_DELAYS` | `[3.0, 8.0, 15.0]` | Seconds to wait before each worker retry |
| `JITTER_MAX` | `2.0` | Max random seconds added to each retry delay |
| `MAX_RETRIES` | `3` | Total attempts to read a session from `state.db` |
Paths are resolved automatically:
- `STATE_DB`: `~/.hermes/state.db` (Hermes core session store)
- `FACT_DB`: `~/.hermes/plugins/cronalytics/facts.db` (plugin-owned SQLite)
- `WATERMARK_FILE`: `~/.hermes/plugins/cronalytics/watermark.json`
- `PENDING_FILE`: `~/.hermes/plugins/cronalytics/pending.jsonl`
---
## Known Limitations
1. **Wrapper-level success only.** The `success` boolean reflects whether the session wrapper completed, not whether the agent task succeeded.
2. **Abandoned sessions are invisible.** Sessions where the gateway crashed or the job got stuck are never ingested (they never reach `ended_at`).
3. **No user-editable config file yet.** All tuning values are hardcoded in `config.py`.
4. **Actual cost is often null.** Most runs only populate `estimated_cost_usd`; `actual_cost_usd` depends on provider billing data.
5. **Dashboard server caches plugins per-process.** Changes to `manifest.json` or `plugin_api.py` require a full dashboard restart.
6. **Mobile layout tested but not optimized.** The table may require horizontal scroll on narrow viewports.
7. **Job detail modal capped at 200 runs.** High-frequency jobs show full count in the table but the drill-down is limited.
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.
---
## Support
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.
See **[SUPPORT.md](SUPPORT.md)** for the full help guide, FAQ, and response expectations.
**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.
---
## Requirements
If you are running Hermes Agent you have everything you need:
- Hermes Agent with plugin hook support (`on_session_end`)
- Hermes dashboard server for UI components
- SQLite (bundled with Python)
---
## License
MIT — see [`LICENSE`](LICENSE) for full text.
---
## Acknowledgments
Thanks to my wife **Gaby** for the Spanish translation review — and to everyone who starred, opened issues, and helped shape v1.1.
---
## Changelog
See **[CHANGELOG.md](CHANGELOG.md)** for the full version history.
---
*Plugin path: `~/.hermes/plugins/cronalytics/`*
*Fact DB: `~/.hermes/plugins/cronalytics/facts.db`*
*API base: `/api/plugins/cronalytics/`*
Information
Repository
Language
Python
Created
2026/6/25
Updated
2026/6/26