简体中文 | English

Codex Thread Cron

Let your Codex CLI keep working on long-running tasks 24/7.

Persistent native cron scheduling for long-running Codex CLI agents.

Codex Thread Cron is an unofficial community companion for Codex CLI. It is built for one specific job: letting a cron-enabled Codex agent wake itself up later and continue work in the same thread.

If you want recurring work to stay thread-local instead of becoming a separate automation object, this is the layer that makes the experience clean.

Real terminal capture: doctor -> install -> create/list/delete a native cron job.

Why This Exists

Codex is strong inside a live session, but recurring work is still awkward:

• the stock experience tends to steer users toward automations
• recurring work can drift away from the original thread
• installing a custom scheduler path is easy to get wrong

This repo fixes the operator experience around native cron without turning the core implementation into a second pile of glue code.

What You Get

• Native thread-local cron, not app automation
• Conservative install and uninstall scripts
• A focused skill that pushes the model toward cron_create, cron_list, and cron_delete
• A doctor check that verifies your codex binary actually supports native cron
• A smoke test that verifies install, reinstall, and uninstall behavior in a temporary CODEX_HOME

What You Do Not Get

• This does not patch an unmodified upstream Codex binary
• This does not patch Codex Desktop
• This does not keep running after every Codex process exits
• This does not use automation as a hidden fallback

How It Works

flowchart LR
    U["User asks for recurring work"] --> P["Codex Thread Cron skill"]
    P --> T["Native cron_create / cron_list / cron_delete"]
    T --> D["Persisted jobs in Codex state DB"]
    D --> W["Next scheduled run"]
    W --> I["Prompt injected back into the same thread"]
    I --> A["Agent continues work in-thread"]

Loading

The plugin layer stays thin. The real scheduler remains inside your cron-enabled Codex build. This repo handles packaging, install UX, guardrails, and validation.

Good Fit

• Morning repo review at 9:00 on weekdays
• Hourly stale-task reminders inside one project thread
• Daily TODO or status sweeps
• Lightweight background follow-ups for an ongoing coding thread

Requirements

• A Codex CLI binary that already exposes native cron_create, cron_list, and cron_delete
• A shell environment where codex is on PATH
• A user who wants recurring work in the current thread, not a separate automation object

Quickstart

git clone https://github.com/PinkPig97/codex-thread-cron.git
cd codex-thread-cron
./scripts/doctor.sh
./scripts/install.sh

Then start a new Codex CLI session and ask it to create a native cron job.

Verify

Run:

./scripts/smoke.sh

This uses a temporary CODEX_HOME, installs the marketplace twice to confirm idempotency, validates the resulting config, and then uninstalls the plugin state again.

For release-quality checks, run:

./scripts/release-check.sh

Example Prompts

• Create a cron named weekday-review on schedule 0 9 * * 1-5 with prompt "Review open TODOs in this repo."
• List the native cron jobs for this thread.
• Delete the cron job that sends a stale reminder every hour.

You can also invoke the plugin explicitly:

Use [@codex-thread-cron](plugin://codex-thread-cron@codex-thread-cron) to create a weekday 9am review cron for this repo.

Install Surface

• scripts/install.sh: adds the local marketplace and enables the plugin conservatively
• scripts/uninstall.sh: removes only this plugin's managed config
• scripts/doctor.sh: validates metadata and verifies native cron support in the resolved codex binary
• scripts/smoke.sh: full install and uninstall smoke test
• scripts/release-check.sh: one-command pre-release validation
• scripts/generate_demo_gif.sh: regenerates the real terminal demo GIF with vhs
• scripts/demo_prompt.txt: prompt fed into codex exec for the demo

Repository Layout

• .agents/plugins/marketplace.json: local marketplace manifest
• plugins/codex-thread-cron/: plugin manifest and skill
• scripts/: install and validation tooling
• assets/: demo and social assets

This directory is already a complete local marketplace root. If you split it into its own GitHub repository, users can point codex marketplace add at the repository root directly.

Product Boundary

This project is intentionally narrow:

• Native cron execution stays in the Codex fork
• Plugin UX stays in this repository
• Installation follows the official marketplace path first
• Config mutation is minimal, conservative, and reversible

That constraint is the point. It keeps the project understandable, publishable, and maintainable.

Roadmap

• Better publish-time branding and screenshots
• A release artifact story for cron-enabled Codex builds
• Tighter CLI diagnostics around missing native cron support
• Optional desktop support once the app-side failure mode is understood cleanly

Publishing Notes

If you plan to launch this as a standalone repo, start with PUBLISHING.md. It includes:

• suggested repo description
• suggested GitHub topics
• a release checklist
• launch copy ideas

Contributing

See CONTRIBUTING.md.

License

Apache-2.0. See LICENSE.

Disclaimer

This is an unofficial community project. Codex and Codex CLI are products of OpenAI. This repository is a companion layer for users who want native recurring work in Codex CLI.