Codex Desktop Thread Cron

Let your Codex Desktop agent work on long-horizon tasks 24/7 with native thread-local cron, without touching the official app bundle.

中文说明

What It Is

Codex Desktop Thread Cron is a small companion repo for people who want recurring work to stay inside the current Codex thread instead of turning into a separate automation object.

It gives Codex Desktop a clean native-cron path while keeping the operator model simple:

• clone the official Codex app into a local sandbox
• replace only Contents/Resources/codex
• keep app.asar byte-for-byte identical
• re-sign the clone locally
• boot the clone with an isolated CODEX_HOME
• install a small skill/plugin layer that biases the agent toward native cron_create, cron_list, and cron_delete instead of app automation

If your workflow is "wake this thread up later and keep working here", this repo is built for that case.

What You Get

• A desktop-safe clone workflow for Codex Desktop
• A self-contained local plugin that prefers native cron over automation
• A strict doctor check for bundle, backend, and config integrity
• A smoke test that validates the full non-GUI setup path
• A repo that can be cloned and used on its own

Product Shape

This repo is intentionally narrow. It does not try to become a second desktop client.

flowchart LR
    A["Official Codex.app"] --> B["Local clone"]
    C["Cron-enabled codex binary"] --> B
    D["Isolated CODEX_HOME"] --> E["Desktop cron plugin + skill"]
    E --> B
    B --> F["Native cron_create / cron_list / cron_delete"]

Loading

The product goal is simple:

• preserve the official app
• keep the setup path obvious
• make native cron feel like a first-class Desktop workflow

Safety Promise

• The official /Applications/Codex.app is read-only input.
• app.asar is never unpacked or repacked.
• The clone is built under ./build/.
• State lives under ./state/.
• doctor.sh compares the clone app.asar hash against the official app.
• launch.sh refuses to start while another Codex process is already running.

Requirements

• macOS with Codex Desktop already installed at /Applications/Codex.app
• a cron-enabled Codex backend binary
• by default, the repo expects that binary at /opt/homebrew/bin/codex

If your cron-enabled binary lives elsewhere, set CODEX_BIN=/absolute/path/to/codex.

Quickstart

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

If you want a full validation pass first:

./scripts/release-check.sh

How To Use It

After the clone launches, open a fresh thread in the cloned Desktop app and ask for native cron explicitly:

• Set a native cron that says 你好 every minute in this thread. Do not use automation.
• List the native cron jobs for this thread.
• Delete the native cron job with id ...

The bundled skill is there to push the model toward native cron, but this is still a language interface. Clear prompting matters.

Scripts

• ./scripts/install.sh: install the local plugin into the isolated CODEX_HOME
• ./scripts/doctor.sh: validate the official app, clone, backend, and config state
• ./scripts/prepare.sh: rebuild the local app clone and re-sign it
• ./scripts/prepare_home.sh: prepare the isolated CODEX_HOME
• ./scripts/launch.sh: launch the cloned app with the isolated CODEX_HOME
• ./scripts/uninstall.sh: remove the clone and isolated state
• ./scripts/smoke.sh: non-GUI end-to-end validation in a temporary directory
• ./scripts/release-check.sh: doctor + smoke

Defaults

• Official app: /Applications/Codex.app
• Clone app: ./build/Codex Native Cron.app
• Isolated home: ./state/codex-home
• Logs: ./state/logs
• Backend binary: /opt/homebrew/bin/codex

All of these can be overridden with environment variables.

Limitations

• You should not run the official Codex app and the clone side-by-side.
• This repo does not replace the Desktop frontend. It wraps Desktop with a safer native-cron setup path.
• It assumes you already have a backend build that exposes native cron.
• The isolated CODEX_HOME is local to this repo by design.

Verification

./scripts/smoke.sh checks:

• native cron symbols exist in the selected backend binary
• the app clone can be rebuilt and re-signed
• the clone app.asar hash matches the official app
• the local plugin installs cleanly into the isolated CODEX_HOME

Who This Is For

• People using Codex Desktop with a custom cron-enabled backend
• People who want thread-local recurring work, not a separate automation object
• People who care more about a clean setup path than a pile of opaque patch scripts

Troubleshooting

• native cron support not found: your CODEX_BIN does not point to a cron-enabled build
• Another Codex process is already running: quit the official app first
• clone bundle: missing: run ./scripts/prepare.sh
• isolated CODEX_HOME: not prepared: run ./scripts/install.sh

License

Apache-2.0