Why Gitcron?

AI agents need cron. Agents review PRs, fix lint, run audits, validate models, and track compliance — but there's no standard way to schedule them. Gitcron is cron for AI agents:

1. Define schedules, tasks, and reminders in cron.yaml
2. Run gitcron generate to compile into GitHub Actions workflows
3. Commit and push — GitHub runs your agents automatically

Works with any agent framework via gitagent adapters:

| Agent / Framework | Adapter | How it works | |---|---|---| | gitclaw | gitclaw | Full runtime with tools, hooks, audit, compliance | | gitagent | claude / openai | Framework-agnostic agent standard | | Claude Code SDK | claude | Claude-powered code agents | | OpenAI | openai | GPT-powered agents | | Any LLM | system-prompt | Generic system prompt export | | Shell commands | command | Any CLI tool, script, or binary |

Install

npm install -g gitcron

Quick Start

# Scaffold a new gitcron configuration
gitcron init --template standard

# Validate your configuration
gitcron validate

# Generate GitHub Actions workflow files
gitcron generate

# Preview without writing
gitcron generate --dry-run

cron.yaml

spec_version: "0.1.0"
name: my-project-cron

schedules:
  - name: nightly-code-review
    cron: "0 2 * * *"
    agent: code-reviewer
    adapter: claude
    prompt: "Review all open PRs"
    branch:
      strategy: pr
      base: main

  - name: weekly-lint
    cron: "0 6 * * 1"
    command: "npm run lint -- --fix"
    branch:
      strategy: commit
      base: main

tasks:
  directory: ".gitcron/tasks"
  states: [pending, in_progress, review, done, cancelled]
  transitions:
    pending: [in_progress, cancelled]
    in_progress: [review, done, cancelled]
    review: [in_progress, done]
    done: []
    cancelled: []

reminders:
  - name: quarterly-review
    type: recurring
    cron: "0 9 1 */3 *"
    action:
      type: issue
      title: "Quarterly Review Due"

CLI Commands

gitcron init

Scaffold a new configuration.

gitcron init                        # Standard template
gitcron init --template minimal     # Minimal template
gitcron init --template full        # Full template with all options

gitcron generate

Compile cron.yaml into GitHub Actions workflow files.

gitcron generate              # Write workflow files
gitcron generate --dry-run    # Preview output
gitcron generate --diff       # Show changes
gitcron generate --force      # Overwrite manually-edited files

gitcron validate

Validate cron.yaml against the schema.

gitcron validate              # Validate
gitcron validate --strict     # Treat warnings as errors

gitcron list

List schedules, tasks, and reminders.

gitcron list                  # Show everything
gitcron list --schedules      # Schedules only
gitcron list --tasks          # Tasks only
gitcron list --reminders      # Reminders only

gitcron status

Show an overview of your gitcron configuration.

gitcron task

Git-native task management. Every mutation creates a git commit.

gitcron task create "Update docs" --priority high --assignee alice
gitcron task list
gitcron task list --state pending
gitcron task update TASK-001 --state in_progress
gitcron task show TASK-001

gitcron remind

Manage reminders.

gitcron remind create weekly-sync --cron "0 9 * * 1" --title "Weekly Sync"
gitcron remind list
gitcron remind fire weekly-sync     # Manually trigger
gitcron remind pause weekly-sync
gitcron remind resume weekly-sync

Compatible Agents

Gitcron is the scheduling layer for the entire AI agent ecosystem. Any agent that can run as a CLI command can be scheduled:

• gitclaw — Enterprise agent runtime with built-in tools, hooks, audit logging, and compliance. Best for regulated environments.
• gitagent — Open git-native agent standard. Adapters for Claude, OpenAI, and any LLM.
• Claude Code SDK — Build and schedule Claude-powered agents via the claude adapter.
• OpenAI agents — Schedule GPT-powered agents via the openai adapter.
• Custom agents — Use command to schedule any script, binary, or CLI tool.

Gitcron ships with skills that teach agents how to manage their own schedules, tasks, and reminders — enabling self-scheduling agents that can create follow-up jobs, track work items, and set compliance deadlines autonomously.

Branch Strategies

| Strategy | Behavior | |----------|----------| | pr | Create branch, run, commit, push, open PR | | create | Create branch, run, commit, push (no PR) | | commit | Run, commit, push directly to base branch | | none | Run only (no git operations) |

Schedule Types

Agent schedules

Run a gitagent agent on a schedule:

schedules:
  - name: code-review
    cron: "0 2 * * *"
    agent: code-reviewer
    adapter: claude
    prompt: "Review open PRs"

gitclaw agent schedules

Run an agent using the gitclaw runtime (full tools, hooks, audit, compliance):

schedules:
  - name: code-review
    cron: "0 2 * * *"
    agent: code-reviewer
    adapter: gitclaw
    prompt: "Review open PRs"
    agent_source:
      type: local
      path: "./agents/code-reviewer"
    secrets: [ANTHROPIC_API_KEY]

The generated workflow installs and runs gitclaw -d <dir> -p <prompt> instead of gitagent run.

Command schedules

Run any shell command on a schedule:

schedules:
  - name: lint-fix
    cron: "0 6 * * 1"
    command: "npm run lint -- --fix"

Adapters

| Adapter | Runtime | Install | Best for | |---------|---------|---------|----------| | claude | Claude Code via gitagent | gitagent | Code changes, PRs | | openai | OpenAI API via gitagent | gitagent | Analysis, reviews | | gitclaw | gitclaw runtime (pi-agent-core) | gitclaw | Full agent with tools, hooks, audit, compliance | | system-prompt | System prompt export via gitagent | gitagent | Generic LLM integration |

Part of the open-gitagent ecosystem

• gitagent — Git-native AI agent standard
• gitclaw — Universal git-native agent runtime
• gitcron — Git-native scheduling and task management

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

License

MIT