spillwavesolutions Managing the Agent Cron Daemon
This skill instructs you, the AI agent, on how to help a user start, stop, and check the status of the agent-cron daemon. Follow each section as written. Always show raw CLI output first, then provide your conversational interpretation.
Before You Start
Run the following command to confirm the agcron binary is installed:
which agcron
If the command prints a path (e.g., /usr/local/bin/agcron), the binary is
available. Proceed to the section the user needs.
If the command prints nothing or returns "not found", tell the user:
The
agcronbinary is not on your PATH. You need to install it first. I can help you with that using the installing-agcron skill.
Do not continue with any daemon operations until the binary is confirmed present.
Starting the Daemon
Requirements: DAEM-01 (start), DAEM-04 (double-start prevention)
Step 1 — Check whether the daemon is already running
Run:
agcron status
Show the complete output to the user.
If the output contains "Status: running":
Tell the user the daemon is already running. Extract the PID and uptime from the output and present them conversationally. For example:
The daemon is already running (PID 48201, uptime 3h 12m). No action needed.
Do NOT attempt to start the daemon again. Ask if the user wants to do something else instead (check status details, stop, etc.).
If the output contains "Error: Daemon is not running" (exit code 69):
Proceed to Step 2.
Step 2 — Start the daemon
Run:
agcron daemon -d
Show the complete output to the user.
Expected success output: Daemon started (backgrounded)
If the output says "Daemon already running (PID N)": This means a race condition occurred between your status check and start attempt. Tell the user the daemon is already running with that PID. Do not retry.
Step 3 — Verify the daemon started
Run:
agcron status
Show the complete output to the user. Confirm the daemon is running by checking for "Status: running" in the output. Summarize the key fields:
The daemon started successfully. It is running as PID 48201 with N jobs loaded. The next scheduled run is at HH:MM.
If the status still shows the daemon is not running, tell the user the start failed. Suggest running in foreground mode for diagnostic output:
RUST_LOG=debug agcron daemon
This runs the daemon in the foreground with verbose logging so the user can see
exactly what is failing. Once the issue is identified, stop it with Ctrl+C and
start normally with agcron daemon -d. Also refer them to the Troubleshooting
section for common error messages and fixes.
Stopping the Daemon
Requirement: DAEM-02
Step 1 — Check whether the daemon is running
Run:
agcron status
Show the complete output to the user.
If the output contains "Error: Daemon is not running", tell the user:
The daemon is not currently running, so there is nothing to stop.
Do not attempt to stop it. Ask if they want to start it instead.
Step 2 — Stop the daemon
If the daemon is running, run:
agcron stop
Show the complete output to the user.
Expected output sequence:
Stopping daemon...— the daemon received the shutdown signal.Daemon stopped— clean shutdown completed.
If the output contains "Warning: daemon may still be draining": Tell the user that in-flight jobs are still completing. The daemon will exit once all running jobs finish or the shutdown timeout (default 30 seconds) is reached. Suggest waiting a moment and then checking status:
agcron status
Step 3 — Confirm shutdown
Run:
agcron status
Show the complete output to the user. Confirm that the daemon is no longer running:
The daemon has been stopped successfully.
If it is still running, it may be draining in-flight jobs. Tell the user to wait and check again, or refer to the Troubleshooting section.
Restarting the Daemon
Use this when the user asks to restart agent-cron, for example after changing configuration or updating the binary. A restart is a stop followed by a start.
Step 1 — Stop the daemon
Follow the Stopping the Daemon procedure above (check status, run
agcron stop, confirm shutdown).
Step 2 — Start the daemon
Once the daemon has fully stopped (confirmed via agcron status showing
"Error: Daemon is not running"), follow the Starting the Daemon procedure
above (run agcron daemon -d, verify with agcron status).
Summarize the result:
The daemon has been restarted. It is now running as PID 48305 with N jobs loaded.
If the stop phase shows the daemon is draining in-flight jobs, wait for it to finish before starting again. Do not start a new daemon while the old one is still shutting down.
Checking Status
Requirement: DAEM-03
Run:
agcron status
Show the complete raw output to the user first. Then interpret the fields.
When the daemon is running
The output includes these fields:
| Field | Meaning |
|---|---|
| Status | running — daemon is active |
| PID | Process ID of the daemon |
| Uptime | How long the daemon has been running |
| Loaded Jobs | Number of cron job definitions currently loaded |
| Queue Depth | Number of jobs waiting to execute |
| Next Scheduled Run | When the next job will fire |
| Memory | Current memory usage of the daemon process |
Provide a conversational summary. For example:
The daemon is healthy and running as PID 48201 (uptime 3h 12m). It has 5 jobs loaded with none queued. The next scheduled run is at 14:30 UTC. Memory usage is 12 MB.
If queue depth is high relative to loaded jobs, note this:
Queue depth is 8 with only 3 jobs loaded. This may indicate jobs are backing up. Check concurrency settings or job execution times.
When the daemon is not running
The output will contain "Error: Daemon is not running" and the exit code will be 69. Tell the user:
The daemon is not running. Would you like me to start it?
Assessing Overall Health
Requirement: HLTH-01
Use this section when the user asks a general question about how agcron is doing, whether everything is OK, or whether the daemon is healthy.
Disambiguation:
- For a quick overall "is everything OK?" answer, use this section.
- For detailed per-job statistics, trend analysis, or diagnosing a specific failure, use the monitoring-jobs skill (MON-05).
Step 1 — Check daemon status
Run:
agcron status
Show the complete raw output to the user.
If the output contains "Error: Daemon is not running":
Tell the user:
The daemon is not running, so no health data is available. Would you like me to start it?
Do not run any further commands. Offer to start the daemon via the Starting the Daemon section. Stop here.
If the output contains "Status: running":
Note the following values for use in the synthesis at Step 4: PID, Uptime, Loaded Jobs, Queue Depth, and Memory. Proceed to Step 2.
Step 2 — Collect statistics
Run:
agcron stats
Show the complete raw output to the user. Apply the following thresholds to each job in the output:
| Metric | Healthy | Warning | Problem |
|---|---|---|---|
| Success rate | > 95% | 80–95% | < 80% |
| P95 duration vs average | Within 2x | 2–5x average | > 5x average |
| Failure trend | Stable or decreasing | Flat | Increasing |
Note which jobs fall into the Warning or Problem band. Note these for the synthesis at Step 4.
If agcron stats fails with a socket error, show the error to the user, skip this step's data, and note the gap in the synthesis.
Step 3 — List loaded jobs
Run:
agcron jobs list
Show the complete raw output to the user. Note the total job count and the soonest next-run time for the synthesis at Step 4.
If agcron jobs list fails with a socket error, show the error to the user, skip this step's data, and note the gap in the synthesis.
Step 4 — Synthesize into a single health verdict
Write ONE paragraph that combines the findings from Steps 1, 2, and 3 into a unified verdict. Do not produce three separate summaries — produce a single coherent assessment.
Example of a healthy verdict:
agcron is healthy. The daemon has been running for 3h 12m (PID 48201) with 5 jobs loaded and nothing queued. Over the last 7 days, the overall success rate is 95.2% — right at the healthy threshold. The daily-backup job is at 100%. The code-review job is at 93.8%, which is in the warning band; you may want to examine it with the monitoring-jobs skill (MON-05). The next scheduled run is at 14:30 UTC.
Example of a verdict with problems:
agcron has reliability problems. The daemon is running (PID 48201, uptime 14m — it may have restarted recently), but the overall 7-day success rate is 72%, well below the 80% problem threshold. Three jobs are in the problem band. I recommend running the failure diagnosis workflow in the monitoring-jobs skill (MON-04) to find the root cause.
If any step failed, include that context in the verdict and refer to the Troubleshooting section for the socket error.
Changing Configuration
Requirement: HLTH-02
Use this section when the user wants to change a daemon setting — for example, concurrency limit, default model, timeout, or which project directories are monitored.
Understanding hot-reload
The daemon watches its config file for changes using a file-system watcher. When you save the file, the daemon parses the new config, validates it, and applies changes automatically. If validation fails, the daemon logs an error and keeps the current config (safe rollback — the daemon keeps running).
Most fields reload automatically when the file is saved — no restart needed.
Only two fields require a daemon restart:
| Fields requiring restart | Why |
|---|---|
socket_path |
The Unix socket is bound at startup; it cannot be rebound without a restart |
project_roots |
The file watcher is set up at startup; directories cannot be added or removed live |
All other fields — including concurrency_limit, default_agent, default_model, default_timeout_secs, max_retries, retry_delay_secs, and log_retention_days — reload automatically.
Step 1 — Find the config file
The default config path is ~/.config/agent-cron/config.toml. If the user has set the AGENT_CRON_CONFIG environment variable, their config is at that path instead. Check with:
echo "${AGENT_CRON_CONFIG:-~/.config/agent-cron/config.toml}"
Show the output so the user knows exactly which file is being edited.
Step 2 — View the current config
Run:
cat ~/.config/agent-cron/config.toml
(Replace the path if AGENT_CRON_CONFIG is set.) Show the complete output to the user so they can see the current values before changing anything.
Step 3 — Edit the field
Open the config file in the user's preferred editor, or apply the change directly. Common changes and their TOML syntax:
Concurrency limit (max jobs running at once):
concurrency_limit = 6
Default AI adapter:
default_agent = "claude"
Default model:
default_model = "claude-opus-4-5"
Per-job execution timeout (seconds):
default_timeout_secs = 300
Project directories to monitor (requires restart after change):
project_roots = [
"/home/user/projects/alpha",
"/home/user/projects/beta"
]
After editing, save the file.
Step 4 — Verify the change took effect
For fields other than socket_path and project_roots (auto-reload):
Wait two to three seconds for the file-watcher debounce window to pass. Then run:
agcron status
Show the output to the user. Confirm the daemon is still running with the same PID. If the daemon is running and the PID is unchanged, the reload succeeded. Provide a conversational confirmation. For example:
The config was reloaded automatically. The daemon is still running as PID 48201. Your concurrency limit change is now active.
If the daemon log is accessible (running in foreground with RUST_LOG=info agcron daemon), tell the user to look for: Config reloaded successfully (generation N).
If the daemon stopped or the PID changed unexpectedly, the new config likely failed validation. Refer to the Troubleshooting section.
For socket_path or project_roots changes (restart required):
Tell the user:
Changes to
socket_pathorproject_rootsrequire a daemon restart to take effect. The daemon logged a warning about this. I will restart it now.
Follow the Restarting the Daemon procedure. After the restart, verify with agcron status and confirm the Loaded Jobs count reflects the updated project_roots.
Troubleshooting
If you encounter errors during any daemon operation, consult the troubleshooting guide for diagnosis and resolution steps:
See references/troubleshooting.md
Common issues include permission errors on the socket file, stale socket files blocking startup, config parse errors, and daemons that hang during shutdown. The troubleshooting guide provides the exact error messages and fix steps for each case.
Reference Materials
For the complete CLI command reference including all flags, environment variables, and expected outputs, see:
references/cli-commands.md