codex-cli-schedule

Schedule prompts for your Codex sessions.

One-time reminders, recurring check-ins, and daily routines.Set up in one command. Manage schedules from Codex or your terminal.

English · 简体中文

Quick start · Use with Codex · CLI · FAQ · Star History

What you can do

• Send a prompt later — arrange a one-time follow-up for a specific session.

• Check in regularly — send prompts every few minutes or on a cron schedule.

• Plan project routines — create a new session for each scheduled delivery.

• Manage everything from Codex — create, inspect, pause, resume, and delete schedules through MCP.

Related MCP server: MCP Cron Server

Quick start

Have Node.js 24+ and an authenticated Codex CLI 0.154.0+ ready. The codex command should be available in your terminal.

1. Install and connect

npm install -g @bakapiano/codex-cli-schedule --registry=https://registry.npmjs.org/
codex-schedule setup

2. Open Codex

Start a new Codex CLI session and enter /mcp. Check that codex_schedule is connected.

3. Create your first schedule

Get the target session ID from /status, then ask Codex:

Create a schedule named progress-check for session <session-id>, every five minutes. The prompt should be “Check project progress and give me a short update.”

The local scheduling service starts when you use MCP or manage tasks. Scheduled prompts are delivered to the target session's queue and processed in its Codex terminal.

Use with Codex

Once connected, you can manage schedules in natural language:

List my schedules and show which ones are paused.

Pause the progress-check schedule.

Change progress-check to run every ten minutes.

Show the recent delivery records for progress-check.

You can also schedule a new session for a project:

Every day at 09:00 in Asia/Shanghai, create a new session for the current project and queue “Generate today's project summary.”

Find the new session ID in the delivery records, then open it with codex resume <session-id> to process the queued prompt.

Command line

Prefer the terminal? The same scheduling features are available through codex-schedule.

These examples use PowerShell. Replace <session-id> with the value from Codex's /status.

# Once, ten minutes from now
$when = (Get-Date).AddMinutes(10).ToString("o")
codex-schedule create --name follow-up --session "<session-id>" --at $when --prompt "Check project progress and report back"

# Every five minutes
codex-schedule create --name progress-check --session "<session-id>" --every 5m --prompt "Check project progress and report back"

# Every day at 09:00, in a new session for the current directory
codex-schedule create --name daily-summary --new --cwd "$PWD" --cron "0 9 * * *" --timezone Asia/Shanghai --prompt "Generate today's project summary"

Use the schedule ID returned by create or list to manage it:

codex-schedule list
codex-schedule get "<schedule-id>"
codex-schedule update "<schedule-id>" --pause
codex-schedule update "<schedule-id>" --enable
codex-schedule update "<schedule-id>" --every 10m
codex-schedule runs "<schedule-id>"
codex-schedule delete "<schedule-id>"

For longer prompts, use --prompt-file prompt.txt. Run codex-schedule --help or codex-schedule create --help to explore the options.

Configuration

The default setup registers an MCP server named codex_schedule. Repeat setup safely to check an existing matching registration.

# Preview the registration
codex-schedule setup --dry-run

# Choose an MCP name
codex-schedule setup --name my_scheduler

# Use a shared data directory for MCP and CLI commands
codex-schedule --home D:\codex-scheduler-data setup
codex-schedule --home D:\codex-scheduler-data list

# Choose the Codex executable used for registration
codex-schedule setup --codex C:\path\to\codex.exe

# Update registered paths after moving Node.js or the package
codex-schedule setup --force

# Inspect MCP registration and the local service
codex mcp list
codex-schedule status
codex-schedule start
codex-schedule stop

--force replaces the selected MCP registration. Choose --name to keep a different same-name configuration.

To change the executable used for scheduled deliveries, stop the service and start it with codex-schedule start --codex C:\path\to\codex.exe. Use the same --home for commands that should share schedules.

FAQ

What does queued mean?

The prompt has reached the target Codex session's queue. Open that session to view its progress and replies. Closed sessions keep their pending prompts for the next time they are opened.

Does the computer need to stay on?

Scheduling runs on your computer. The background service continues after MCP clients close; your computer and the service need to be running to process due schedules. After a restart or wake-up, overdue one-time tasks are delivered once and missed recurring deliveries are combined into one catch-up delivery.

Where are my schedules stored?

On Windows, the default directory is %LOCALAPPDATA%\codex-cli-schedule. On other systems, it is ~/.local/share/codex-cli-schedule. Choose --home or set CODEX_SCHEDULE_HOME to use another directory. Keep backups private: the directory contains prompts, session IDs, and credentials for the local service.

How do I update or troubleshoot the connection?

Use codex-schedule stop before an upgrade, then run the installation command again. Use codex-schedule setup to check registration, or setup --force to update changed paths. Start a new Codex session and check /mcp.

For startup problems, check codex-schedule status and daemon.log in the data directory. See the implementation notes for legacy lock recovery.

Documentation

• Implementation details — architecture, delivery behavior, storage, MCP schemas, and source development.

• Live Codex E2E checks (中文) — validate scheduling with an actual Codex session.

• Publishing guide — npm releases and GitHub Actions setup.

Star History

License

MIT