Watch this repo to get notified of new releases. 👀
/ˈkrɒn.əˌlɪt.ɪks/ (noun)
- Cron analytics and observability.
- 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, the autonomous agent framework by Nous Research.
| I am... | Path |
|---|---|
| A New User | Install Guide (Fresh Start) |
| An Existing v1.0.x User | Upgrade Guide (v1.1 Migration) |
| Exploring Features | Usage & Workflows or Feature Catalog |
The dashboard is insightful, but the CLI + Skill are the real superpower.
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.
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
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.
After install, the plugin needs data:
- Wait for a cron job to run — the
on_session_endhook captures it automatically. - 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 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.
 |
 |
 |
 |
 |
 |
 |
 |
 |
 |
 |
 |
- Captures every cron job run as it completes via the
on_session_endhook - 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:
- 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 | 90Dpresets + 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)
summary— headline aggregates + leader board + cost-by-model tablejobs— per-job table with ID, runs, cost, tokens, pace, avg durationruns --job <id>— individual run history (time, duration, cost, tokens, model)models— per-model aggregate tabletrends— daily bar chart (ASCII) of cost + runshealth— fact DB metadata, job count, last syncall— chains health → summary → jobs → models → trends- All commands support
--days N,--outcome, and--mode; every data command exceptallsupports--json - Job name resolution from
~/.hermes/cron/jobs.json
- 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.jsoncross-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.
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 — $0.00 costs, estimated vs actual, and why Cronalytics differs from your provider invoice.
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 |
- 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 for Success vs Failure, agent vs no-agent jobs, and what Pace really means.
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? for a checklist of common reasons jobs don't appear.
- INSTALL.md — Installation guide (dashboard plugin + pip CLI + skill setup)
- UPGRADE.md — Transition guide for v1.0.x users (Namespace restructure)
- UNINSTALL.md — Clean removal instructions
- USAGE.md — Dashboard and CLI usage guide
- TROUBLESHOOTING.md — Common issues and fixes
- RELEASE_NOTES.md — Per-release upgrade notes and highlights
- FAQ.md — Common questions and quick answers
- BRIEF.md — Product opportunity brief & positioning
- DESIGN.md — Architecture, data flow, and technical decisions
- FEATURES.md — Complete feature catalog with formulas
- DEV_SETUP.md — Development environment setup
- CHANGELOG.md — Full version history
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.
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.
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.
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)
name: cronalytics
version: 1.1.0
description: Cost and operational observability for Hermes cron jobs
provides_hooks:
- on_session_endAll 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.jsonPENDING_FILE:~/.hermes/plugins/cronalytics/pending.jsonl
- Wrapper-level success only. The
successboolean reflects whether the session wrapper completed, not whether the agent task succeeded. - Abandoned sessions are invisible. Sessions where the gateway crashed or the job got stuck are never ingested (they never reach
ended_at). - No user-editable config file yet. All tuning values are hardcoded in
config.py. - Actual cost is often null. Most runs only populate
estimated_cost_usd;actual_cost_usddepends on provider billing data. - Dashboard server caches plugins per-process. Changes to
manifest.jsonorplugin_api.pyrequire a full dashboard restart. - Mobile layout tested but not optimized. The table may require horizontal scroll on narrow viewports.
- Job detail modal capped at 200 runs. High-frequency jobs show full count in the table but the drill-down is limited.
See FAQ for more: the 250-run limit, agent vs no-agent, models breakdown, snapshotting your facts.db, and getting cronalytics on your PATH.
Found a bug? Open a GitHub Issue with reproduction steps. Have a feature idea? Open a Discussion or fork it.
See 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). Verify anything mission-critical independently.
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)
MIT — see LICENSE for full text.
Thanks to my wife Gaby for the Spanish translation review — and to everyone who starred, opened issues, and helped shape v1.1.
See CHANGELOG.md for the full version history.
Plugin path: ~/.hermes/plugins/cronalytics/
Fact DB: ~/.hermes/plugins/cronalytics/facts.db
API base: /api/plugins/cronalytics/