Cronalytics

Watch this repo to get notified of new releases. 👀

/ˈ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, the autonomous agent framework by Nous Research.

Getting Started

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 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.

Features

Mini-Tour

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.