# 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)
```bash
brew tap SpillwaveSolutions/tap
brew install agcron
```
### Shell installer (macOS/Linux)
```bash
curl -sSfL https://raw.githubusercontent.com/SpillwaveSolutions/agent-cron/main/scripts/install.sh | sh
```
### Build from source
```bash
cargo install --path rust
```
## Quick Start
```bash
# 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](plans/truth-document.md) or use the `managing-daemon` conversational skill.
## Job Format
Jobs are markdown files in `.cron/jobs/` with YAML frontmatter:
```yaml
---
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](plans/truth-document.md) 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`](PRD.md)
- **CLOD Schema:** [`clod/SCHEMA.md`](../clod/SCHEMA.md)
- **Skills:** [`skills/agcron/`](../skills/agcron/)
- **Truth Document:** [`docs/plans/truth-document.md`](plans/truth-document.md)
## License
See repository root for license information.
*Last validated: 2026-03-21 (v1.9 documentation audit)*