managing-daemon

name	managing-daemon
description	Start, stop, restart, and check the status of the agent-cron daemon. Use when you need to manage the daemon lifecycle, check if the daemon is running, restart after config changes, or troubleshoot daemon startup issues.
last_validated	"2026-03-21T00:00:00.000Z"

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 agcron binary 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:

1. Stopping daemon... — the daemon received the shutdown signal.
2. 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_path or project_roots require 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