monitoring-jobs

Jobs

Jobs is an Out of loop scheduled task system that enables AI to execute tasks continuously and automatically outside the Agent Loop.

中文版本

Core Concepts

In loop vs Out of loop

Type	Trigger	Lifecycle	Automation
Skills	Agent decision / Manual /slash	Bound to current Agent Loop	Semi-automated
Jobs	Cron schedule + Condition check	System-level, Out of loop	Fully automated

Problems Jobs Solve

• Want AI to keep consuming tokens and working for you while you sleep?
• Want AI to periodically check things and execute automatically?
• Want to achieve true automation and autonomous evolution?

Jobs = Cron Scheduled Tasks + Conditional Execution + Skills Composition

Repository Structure

jobs/
├── README.md                 # This document
├── README.zh.md              # Chinese version
├── spec/
│   └── jobs-spec.md          # Jobs specification
├── template/
│   └── JOB.md                # Job template
├── jobs/                     # Example Jobs
│   ├── npm-global-update/
│   ├── claude-news-collect/
│   └── todo-night-executor/
└── .claude-plugin/
    └── marketplace.json      # Claude Code plugin configuration

Quick Start

1. Initialize CLI

npx openjob@latest init

This creates the global registry at ~/.agents/jobs.json and the jobs directory at ~/.agents/jobs/.

The published package uses both the npm name and installed binary name openjob, avoiding collisions with the shell builtin jobs in shells like zsh. The recommended invocation is npx openjob@latest <command>.

2. Create a Job

Option A: Use job-creator Skill (Recommended)

The easiest way is to use the built-in job-creator skill. Simply tell Claude:

"Create a job to check npm global updates every Monday at 9 AM"

The skill will:

1. Generate an appropriate job name and cron schedule
2. Create ~/.agents/jobs/<name>/JOB.md with proper structure
3. Validate and register the job automatically

Option B: Manual Creation

Create a global Job under ~/.agents/jobs/<job-name>/JOB.md:

---
name: my-first-job
cron: 0 9 * * *
description: Example job that runs daily at 9 AM
---

# My First Job

Write your instructions here that Claude will follow when this job triggers.

Then register it:

npx openjob@latest add ~/.agents/jobs/my-first-job

npx openjob@latest add stores Jobs in the global registry at ~/.agents/jobs.json, keeps the executable JOB.md under ~/.agents/jobs/<name>/JOB.md, and syncs enabled Jobs to Claude scheduled tasks.

Repository examples under jobs/ are marketplace/source templates. Installing one copies it into the global Jobs directory:

npx openjob@latest add jobs/todo-night-executor

3. Start the Daemon

npx openjob@latest daemon start

The daemon will periodically check and execute due jobs.

CLI Commands

Command	Description
openjob init	Initialize the global jobs registry
openjob add <path>	Install a job from a JOB.md file or directory
openjob remove <name>	Remove a job by name
openjob list	List all registered jobs
openjob status	Show daemon status and job runtime info
openjob enable <name>	Enable a job
openjob disable <name>	Disable a job
openjob run <name>	Execute a job immediately (manual test)
openjob sync	Sync enabled jobs to Claude scheduled_tasks.json
openjob daemon start	Start local jobs daemon
openjob daemon stop	Stop local jobs daemon
openjob daemon status	Show daemon status
openjob dashboard	Open local web dashboard

Job Definition Format

A Job is a Markdown file with YAML frontmatter:

---
name: job-name                  # Required: Unique identifier (lowercase, hyphen-separated)
cron: 0 9 * * *                # Required: Cron expression (5 fields)
description: What this job does # Required: Description
condition: ./check.sh          # Optional: Execution condition script
allowedSkills: [skill1, skill2] # Optional: Allowed skills for this job
timeout: 60                    # Optional: Timeout in minutes (default: 60)
retry: 1                       # Optional: Retry count on failure (default: 0)
tags: [automation, maintenance] # Optional: Tags for categorization
---

# Job Title

## Objective
Describe what this job accomplishes.

## Execution Steps

1. Step one
   ```bash
   echo "Command to execute"

2. Step two

   another-command
   

Output Requirements

Expected output or results.

### Core Fields