axon sch

Create and manage schedules that wake an agent on a cron cadence.

axon sch list                         # list schedules
axon sch state                        # scheduler state and next wake
axon sch create <id> [options]         # create a schedule
axon sch show <id>                    # inspect one
axon sch update <id> [options]         # update one
axon sch pause <id>                  # pause one
axon sch resume <id>                 # resume one
axon sch run <id>                    # run one occurrence now
axon sch remove <id>                 # remove one

sch is the short form of schedule. The daemon owns schedules, so they continue to exist after the terminal command exits.

A schedule is a trigger

A schedule is not a job and not an agent run:

• a schedule says when and what to wake;
• a run is one execution of that schedule;
• a job is durable repository work stored as Markdown.

A schedule may wake an agent to inspect or advance a job, but the schedule itself remains operational daemon state.

Create a schedule

A schedule needs an ID, an agent, a project, a five-field cron expression, and exactly one target: a prompt or a script.

axon sch create daily-review \
  --agent @cody/terry \
  --project /home/cody/git/arclabs \
  --every "0 9 * * 1-5" \
  -P task/exec

Or schedule a script:

axon sch create nightly-check \
  --agent @cody/terry \
  --project /home/cody/git/arclabs \
  --every "0 2 * * *" \
  -s health

The target is exclusive: use either -P or -s, not both. Arguments belong to the target and should be declared explicitly:

axon sch create review \
  --agent @cody/terry \
  --project /home/cody/git/arclabs \
  --every "0 9 * * 1-5" \
  -P task/exec \
  --arg mode=review \
  --arg depth=2

Scheduled jobs

A schedule can target a repository job:

axon sch create job-001-review \
  --job /home/cody/git/arclabs/.agents/work/001.md \
  --every "0 9 * * 1-5" \
  --agent @cody/terry \
  -P task/exec

--job is a first-class target, not an ordinary script argument. When the schedule fires, the job document becomes the durable context for the run and the resulting report can be appended to that job.

The general agent target remains useful for recurring work that is not tied to one job.

Inspect schedules

axon sch list
axon sch list --agent @cody/terry
axon sch show daily-review
axon sch state
axon sch state --json

A list should show the operational fields people need at a glance:

ID              STATE    NEXT RUN             TARGET
daily-review    active   2026-09-15 09:00 UTC @cody/terry · task/exec
nightly-check   paused   —                    @cody/terry · health

show includes the agent, project, cadence, target, arguments, pause state, next occurrence, last run, and last result.

Change the lifecycle

axon sch pause daily-review
axon sch resume daily-review
axon sch run daily-review
axon sch update daily-review --every "30 9 * * 1-5"
axon sch remove daily-review

run executes one occurrence immediately. It does not alter the cadence. A paused schedule does not run until resumed; an explicit run of a paused schedule is reported as skipped rather than silently changing its state.

Time and results

--every uses a five-field cron expression. The daemon evaluates it in the configured schedule timezone; when no timezone is configured, output should say UTC rather than leaving the default implicit.

Each occurrence produces one result:

{
    status: "succeeded" | "failed" | "skipped",
    sessionId?: string,
    message?: string,
}

The schedule retains its last run time and last result. A failed execution is visible through show and --json; it does not become an unclassified process error.

Options

Schedule IDs are stable references. Missing, ambiguous, malformed, or invalid schedules should produce classified errors rather than a stack trace. Listing should skip malformed schedule files while showing healthy entries.

Design boundary

The daemon is the durable owner of schedules. The CLI is a client of its lifecycle API:

list · state · create · show · update · remove · pause · resume · run

Jobs remain repository documents, and agent runs remain session records. Keeping those boundaries separate lets a schedule wake a job workflow without turning recurring infrastructure into another job format.