songyb111-gachon/codex-auto-resume-windows/codex-auto-resume

Codex Auto Resume

Controls a small local watcher that resumes the exact Codex conversation a usage limit interrupted, once the limit resets. This skill is a front end: every command below calls the project's own command-line interface, which owns all detection and safety logic.

Windows only.

Prefer the tools when they are available

This plugin also provides tools (open_settings, get_status, list_pending, update_settings, restore_default_settings, pause_auto_recovery, resume_auto_recovery, cancel_recovery, disable_conversation_recovery, enable_conversation_recovery, reset_recovery_budget, start_watcher, retry_now, postpone_recovery, release_hold, get_recovery_statistics, get_recovery_timeline, clear_recovery_history, preview_recovery_message, turn_off_power_action). When they are available, use them instead of the commands below: they are typed, they refuse an invalid value instead of writing it, and open_settings shows the user a panel they can read and change directly.

preview_recovery_message shows the exact words the watcher would send for one kind of interruption, under the current language and style. It saves nothing and sends nothing. The user's own Custom message text cannot be written from Codex - not through update_settings and not through the preview. If the user wants to change it, tell them it is edited in the Dashboard, under Settings > Continuation message.

turn_off_power_action turns off the power action after usage-limit recoveries (sleep, hibernate or shut down once they finish), so this PC stays on. Nothing in Codex turns it on: only the Dashboard does, and if the user asks for it, send them there.

resume_auto_recovery, enable_conversation_recovery, update_settings, restore_default_settings, cancel_recovery, reset_recovery_budget, start_watcher, clear_recovery_history and release_hold carry MCP's destructiveHint annotation to request approval. Codex and its approval settings decide whether to show a prompt; actual host approval behavior has not been observed for v0.6.0. The annotation is not an authorization lock. If the user declines one, do not run the matching command below instead.

Use the commands below when the tools are not available - the plugin's server has not started, or the user is asking to install, repair or remove the product, which the tools deliberately cannot do.

Installing it

This plugin is not the product. It carries the skills, the tools and this file; the parts that do the work are a Windows runtime, a settings window and a background watcher, which are not in the plugin and cannot be. So the first step is always the setup script, which downloads the matching release, verifies it and installs it.

Run the plugin's own setup script by its absolute path. This file is <plugin root>\skills\codex-auto-resume\SKILL.md, so the script is <plugin root>\scripts\bootstrap.ps1 - two directories up from this file, then scripts. Before running it, check that <plugin root>\.codex-plugin\plugin.json exists and names codex-auto-resume; if it does not, stop and say the plugin files could not be found.

powershell -NoProfile -ExecutionPolicy Bypass -File '<plugin root>\scripts\bootstrap.ps1'

Never run it as a relative scripts/bootstrap.ps1. The working directory is usually the user's project, and a project can contain a script of the same name - running that one with -ExecutionPolicy Bypass would run someone else's code in the user's name.

It needs nothing installed first: no Python, no administrator rights, no manual download. It is safe to run again - that is also the repair path and the upgrade path. Add -NoStartup if the user does not want it to run at Windows sign-in.

The product comes in two editions, standard and advanced, and an installation stays in its own: the script repairs and updates standard as standard and advanced as advanced. Change the edition only when the user asks for the other one by name, and say first what changes. Then add -Edition Advanced -Force, or -Edition Standard -Force to go back; the script says what the change means before it downloads anything, keeps their settings and pending recoveries, and starts every advanced capability off. Never add -Edition on your own, and never together with -Update, which refuses it. Never pass -Version either: it installs a pre-release, and a pre-release is installed only when the user says yes to it in the Dashboard's Check for updates. Never run -Versions or -Pick: they are the Dashboard's Install another version..., which shows the user every version, asks them and passes on only what they confirmed. If the user wants another version or edition, point them to it on the Diagnostics page.

Tell the user plainly what it is about to do before running it: it downloads this version's release archive from the project's GitHub releases over HTTPS, checks its SHA-256, checks the contents are this product at this version, and only then installs, for their Windows user only and without administrator rights. Besides the files in %USERPROFILE%\.codex-auto-resume it registers the watcher to start at sign-in (unless -NoStartup), a Start Menu entry and a notification sender, an entry in Windows' Apps list and a link handler for its notification buttons, and this plugin with Codex.

Nothing this project builds is code-signed, so Smart App Control may block its two small programs, and SmartScreen may warn about a downloaded Install.cmd. Say so plainly if it happens, and do not suggest turning either off.

If they would rather do it themselves, the same archive is on the project's GitHub releases page and the ZIP contains Install.cmd. Install.cmd does not check the archive it came in, so tell them to verify the ZIP before extracting it, as described in https://github.com/songyb111-gachon/codex-auto-resume-windows/blob/main/docs/VERIFY.md. Never state a digest yourself.

If it reports that it could not download, say so and stop. Do not look for another source for the archive, do not offer a different URL, and do not try to assemble an installation by hand.

Running commands

Everything below needs the product to be installed, because it runs through the interpreter the installer deploys:

%USERPROFILE%\.codex-auto-resume\runtime\python.exe %USERPROFILE%\.codex-auto-resume\app\scripts\plugin_setup.py <command>

If that interpreter is not there, the product is not installed: run the setup script above instead of looking for another Python. A system Python can run these files, but it would configure a second, lesser installation - a different interpreter, no settings window, no panel - which is why setup refuses to do it.

Commands:

Cancelling one task

Two kinds of id, and they are not interchangeable. cancel_recovery, reset_recovery_budget, retry_now and get_recovery_timeline take an interruption_id: one interruption's own 64-character hex id, as list_pending returns it. disable_conversation_recovery and enable_conversation_recovery take a thread_id, the conversation's UUID, and so does the cancel command. Never guess either, and never pass one where the other belongs: the wrong shape is refused outright, and the right shape would act on something the user did not ask about. postpone_recovery and release_hold take both, the interruption_id and the thread_id from the same list_pending entry, and are refused if the two do not belong together. The pending command prints the conversation UUID in full but only the first 16 characters of the interruption id, so take the whole interruption id from list_pending. Never pass --last, and never pick "the most recent thread".

1. Run list_pending, or pending, and read the entries.
2. If the user means "this conversation" and the environment variable CODEX_SESSION_ID

is set and exactly equals one of the listed thread IDs, use that one.

1. Otherwise show the pending entries and ask which one to cancel.

cancel_recovery stops one interruption and every continuation of it, and nothing else: the conversation stays switched on, so a later interruption in it is still recovered. disable_conversation_recovery is what switches a whole conversation off and cancels what it has waiting, and the cancel <thread-uuid> command does the same from the command line. Only enable_conversation_recovery switches one conversation back on again; the enable command here is the global one. In every case a recovery that was never sent is cancelled outright, a continuation already in Codex's queue is withdrawn when the watcher next checks it, if it is still queued, and a turn already running in Codex is not stopped. What a cancel stopped stays stopped. None of this turns off auto resume globally.

Reporting results

Report what the command actually printed. Useful fields from status and pending: