Codex Cron is a terminal-native, zero-dependency plugin for the Codex development environment designed to provide scheduled execution of Codex prompts. Unlike standard Codex runs, which execute once, Codex Cron enables repeating tasks via a local daemon, utilizing an atomic locking mechanism to prevent race conditions and duplicate executions.

Core Functionality and Architecture

The tool provides two primary skill modules:

1. loop: Manages tasks based on fixed intervals (e.g., $10m$, $2h$, $1d$).
2. schedule: Manages tasks based on standard 5-field cron expressions or absolute ISO-8601 timestamps using the --at flag.

These skills are managed by a daemon that oversees a state root directory (e.g., .codex/loop/ or .codex/schedule/). The state is managed through an atomic read-write cycle where tasks are updated in a tasks.json file using a temporary-file-and-rename pattern, ensuring data integrity.

Technical Methodology

• Single-Runner Lock: To prevent concurrent execution (double-firing), the system implements an atomic lock using a mkdir acquisition strategy combined with a compare-and-swap mechanism. If a daemon crashes, the lock is recovered safely rather than being forcibly deleted, preventing orphaned processes.
• Execution Runners: When a prompt is due, the system routes the execution through three hierarchical modes:
  1. tmux-send: Injects the prompt directly into a specified tmux pane.
  2. resume-command: Executes a local hook with the prompt piped to stdin.
  3. codex-exec: Falls back to a standard Codex execution environment if the former methods are unavailable.
• Security: The plugin enforces a default-deny allowlist for all codex-arg passthroughs. Potentially dangerous flags (e.g., --sandbox danger-full-access or --full-auto) are explicitly stripped to prevent sandbox escalation or config-bypass attacks.
• Logging and Observability: Unlike basic logging, Codex Cron preserves full output logs in $runs/<taskId>/<ts>.jsonl$ files, ensuring that exit codes are preserved and preventing the $1\text{ MB}$ truncation often found in standard capture systems.

Management Commands

Users interact with the system through CLI commands:

• add / cancel / list: CRUD operations on scheduled tasks.
• daemon: The main process that polls for due tasks. The polling interval can be tuned via --poll-ms.
• doctor: A read-only diagnostic utility that validates the state root, lock status, and local environment configuration.

The implementation relies strictly on Node.js ESM and node:test, deliberately avoiding OS-level scheduling (like cron or launchd) to remain contained within the user's terminal session and shell environment. All execution states are local-only and are intended to be excluded from version control systems.