Agent Cron

AI agent workflow scheduler -- run your AI agents on a schedule, reliably, portably, and transparently.

Overview

Agent Cron is a local orchestration platform for scheduling AI agent workflows across multiple AI coding CLIs. It provides:

• 5 built-in adapters: Claude, OpenCode, Gemini, Codex, Copilot
• Markdown-based job definitions with YAML frontmatter -- no proprietary config formats
• Tokio-based Rust daemon with JSON-RPC 2.0 communication over Unix domain socket
• 6 conversational skills for guided setup and management via any AI CLI
• Full CLI (agcron) with 11 subcommands for daemon control, job management, and monitoring

Installation

Homebrew (macOS)

brew tap SpillwaveSolutions/tap
brew install agcron

Shell installer (macOS/Linux)

curl -sSfL https://raw.githubusercontent.com/SpillwaveSolutions/agent-cron/main/scripts/install.sh | sh

Build from source

cargo install --path rust

Quick Start

# Initialize a project
agcron init

# Create a job file
cat > .cron/jobs/nightly-review.md << 'EOF'
---
schedule: "0 2 * * *"
agent: claude
model: claude-3-5-sonnet
---

Review open pull requests and summarize findings.
EOF

# Start the daemon
agcron daemon

# Check status
agcron status

# List jobs
agcron jobs list

CLI Usage

Command	Description
agcron daemon [-d]	Start the daemon (optionally in background)
agcron status	Show daemon status including uptime, job counts, queue depth
agcron stop	Stop the running daemon gracefully
agcron ps	Show job queue status and statistics
agcron watch [--once] [-j]	Watch live daemon activity
agcron jobs list	List all loaded jobs with schedules
agcron jobs info <JOB_ID>	Show detailed job information
agcron jobs trigger <JOB_ID>	Queue job for immediate execution
agcron jobs history [JOB_ID] [--all]	Show execution history
agcron jobs run <JOB> [--direct]	Run a job immediately
agcron stats [JOB_ID]	Show aggregate execution statistics
agcron logs show <JOB_ID>	Show logs from most recent execution
agcron logs tail <JOB_ID>	Tail real-time log output
agcron roots list	List managed project directories
agcron completions <SHELL>	Generate shell completions (bash, zsh, fish, powershell, elvish)
agcron init [--path PATH]	Initialize a project directory

Configuration

Configuration is at ~/.config/agent-cron/config.toml.

Field	Default	Description
project_roots	[]	Directories to watch for job files
concurrency_limit	4	Maximum concurrent job executions
default_agent	"claude"	Default agent when not specified in job
default_model	"claude-3-5-sonnet"	Default model when not specified in job
log_retention_days	30	Days to retain execution logs
default_timeout_secs	300	Default execution timeout in seconds
max_retries	2	Maximum retry attempts for failed jobs
schema_strictness	strict	Validation: strict, warn-but-load, best-effort

Environment variable overrides: AGENT_CRON_CONFIG (config file path), AGENT_CRON_SOCKET (socket path).

For the full 19-field config schema, see the truth document or use the managing-daemon conversational skill.

Job Format

Jobs are markdown files in .cron/jobs/ with YAML frontmatter:

---
schedule: "0 2 * * *"
agent: claude
model: claude-3-5-sonnet
fallback_agent: codex
fallback_model: gpt-4o-mini
timeout: 600
max_retries: 3
auto_approve: false
---

Your task description in markdown body.

All Job Fields (13)

All fields are optional. Defaults come from config.toml.

Field	Description
schedule	Cron expression (e.g., "0 * * * *")
timezone	Timezone for schedule interpretation (e.g., "America/Los_Angeles")
agent	Primary agent CLI to use (claude, opencode, gemini, etc.)
model	Model identifier for the agent
fallback_agent	Fallback agent if primary fails
fallback_model	Fallback model if primary fails
timeout	Execution timeout in seconds
max_retries	Maximum retry attempts
auto_approve	Enable auto-approve/unattended mode (default: false)
extends	Template file to extend (e.g., "template.md")
id	Slug-safe identifier for the job
description	Short description of the job's purpose
tags	Classification tags (e.g., ["review", "nightly"])

Adapters

Built-in Adapters

Adapter	Binary	Prompt Delivery
claude	claude	stdin
opencode	opencode	positional
gemini	gemini	positional
codex	codex	positional
copilot	copilot	positional

Custom adapters can be added via [[adapters]] sections in config.toml. See the truth document for the full CliAdapterConfig schema.

Conversational Skills

Skills provide guided, interactive workflows through any AI CLI. Located in skills/agcron/:

Skill	Description
installing-agcron	Guided installation and setup
creating-jobs	Create new scheduled jobs interactively
editing-jobs	Modify existing jobs with natural language
managing-daemon	Start, stop, configure the daemon
monitoring-jobs	Monitor job execution and troubleshoot
run-agent	Generic agent execution skill

Documentation

• PRD: docs/PRD.md
• CLOD Schema: clod/SCHEMA.md
• Skills: skills/agcron/
• Truth Document: docs/plans/truth-document.md

License

See repository root for license information.

Last validated: 2026-03-21 (v1.9 documentation audit)