Monitoring Jobs

Monitoring Agent Cron Jobs

This skill instructs you, the AI agent, on how to help a user monitor job execution, view history, check logs, diagnose failures, and review statistics for agent-cron scheduled jobs. Follow each section as written. Always show raw CLI output first, then provide your conversational interpretation.

Before You Start

Run which agcron to confirm the CLI is installed. If the command is not found, stop and invoke the installing-agcron skill instead.

Run agcron status to confirm the daemon is running. If the daemon is not running, stop and invoke the managing-daemon skill to start it first.

Once both checks pass, proceed to the relevant section below based on what the user asked.

MON-01 Checking Job Status

Use this section when the user asks what jobs exist, what is running, or when jobs will run next.

List all loaded jobs:

agcron jobs list

Show the raw output to the user. Then summarize: how many jobs are loaded, their schedules, and when the next run is for each.

Show currently running jobs:

agcron ps

Show the raw output. Summarize what is actively running, how long each has been running, and the queue depth (how many jobs are waiting for a concurrency slot). If nothing is running, say so and report the queue depth as zero.

Get detailed info on a specific job:

agcron jobs info <id>

Replace <id> with the job ID the user asked about. Show the raw output, then highlight the key fields: schedule, agent, model, timeout, and next run time.

Live dashboard (optional):

If the user wants continuous monitoring, suggest:

agcron watch

This shows a live auto-refreshing dashboard. Tell the user to press Ctrl+C to exit. For a one-time snapshot without live refresh, use:

agcron watch --once

Disambiguation:

• If the user asks "what jobs are running?" use agcron ps.
• If the user asks "what jobs do I have?" use agcron jobs list.
• If the user asks about a specific job by name, use agcron jobs info <id>.
• If the user asks to "watch" or "monitor" jobs continuously, use agcron watch.

MON-02 Viewing Execution History

Use this section when the user asks about past runs, success rates, or execution records.

History for a specific job:

agcron jobs history <id>

History for all jobs:

agcron jobs history --all

Limit the number of entries:

agcron jobs history <id> -n 10

Filter by status (e.g., only failures):

agcron jobs history <id> --status failed

Always show the raw output first. Then provide a conversational summary. Count successes versus failures and note any patterns. For example: "Out of the last 10 runs, 8 succeeded and 2 failed. Both failures occurred on Monday mornings."

The CLI defaults to showing the last 25 entries. If the user wants fewer, suggest -n 10 to keep output manageable.

MON-03 Viewing Logs

Use this section when the user asks to see log output from a job execution.

Start with the last 50 lines (default):

agcron logs show <job-id> | tail -50

Show the raw output. If the user wants more context, increase to 100 lines:

agcron logs show <job-id> | tail -100

Full log output (use only when explicitly requested):

agcron logs show <job-id>

View only error output:

agcron logs show <job-id> --stderr | tail -50

View logs from a specific date:

agcron logs show <job-id> --date YYYY-MM-DD

Stream logs in real time:

agcron logs tail <job-id>

Tell the user to press Ctrl+C to stop streaming.

Progressive disclosure: Always start with 50 lines. If the user needs more, offer 100 lines or the full log. Do not dump full logs unprompted.

Note: If piping to tail does not work in the current AI CLI environment, run agcron logs show <job-id> and manually truncate the displayed output to the last 50 lines.

MON-04 Diagnosing Failures

Use this section when the user asks why a job failed, what went wrong, or how to fix an error.

Follow these steps in order:

Step 1 — Check recent history:

agcron jobs history <job-id> -n 10

Show the raw output. Determine the failure pattern:

• All 10 failed: likely a configuration or setup issue.
• Intermittent failures: likely timeouts or external dependencies.
• Recent change from passing to failing: likely a job file edit or adapter update.

Step 2 — Get error details:

agcron logs show <job-id> --stderr | tail -50

Show the raw error output to the user. Do not hide or summarize errors without showing the original text.

Step 3 — Diagnose:

Compare the error output against known patterns in references/failure-patterns.md. Provide the matching diagnosis and fix.

Common patterns to check:

• "adapter not found" — wrong agent CLI name in job frontmatter.
• "timeout" status — job exceeded its timeout limit.
• "Permission denied on socket" — stale socket or wrong permissions.
• "model not found" — invalid model name in job frontmatter.
• Non-zero exit with no stderr — adapter binary crashed.

Step 4 — If the error does not match any known pattern:

Show the raw output to the user and suggest:

• Reviewing the full stderr log: agcron logs show <job-id> --stderr
• Checking the job file syntax and frontmatter values.
• Trying to run the prompt manually with the same adapter.

See references/failure-patterns.md for the complete failure diagnosis decision tree.

MON-05 Viewing Statistics

Use this section when the user asks about success rates, performance trends, or aggregate metrics.

Global overview:

agcron stats

Per-job detailed stats:

agcron stats <job-id>

Custom time period (e.g., last 30 days):

agcron stats <job-id> -d 30

Show the raw output first. Then interpret using these thresholds:

Provide a plain-language assessment. Examples:

• "Your daily-backup job has a 98% success rate over the last 30 days. That is healthy."
• "The code-review job has a 72% success rate. That is a significant reliability problem. 6 of the 21 failures were timeouts."
• "P95 duration is 4 minutes versus an average of 45 seconds. Some runs are much slower than normal."

If failures are present, suggest running the diagnosis workflow from MON-04.

Reference Materials

For complete CLI command syntax, see references/cli-commands.md. For failure diagnosis patterns, see references/failure-patterns.md. For example CLI output with interpretation guidance, see references/output-examples.md.