How wakectl works

18 June 2026

wakectl is how you make Codex sessions talk again later without babysitting: after a timeout, when a goal ends, when a token/time milestone is reached, when a thread stops, or when a shell condition becomes true.

Imagine one main Codex thread starts several workers. Some may run for minutes, some for hours, some may compact, hit budget, stop, or need review after every few million tokens. Without extra tooling, the orchestrator either stays blocked polling/waiting, or you manually switch between panes and check what happened.

With wakectl, the orchestrator can set watches and then stop its own turn. Later, when a condition fires, wakectl sends a normal input message to the target Codex thread.

Examples:

Wake me in 30 minutes to reassess.
Wake me when this worker goal becomes complete, blocked, or budget-limited.
Wake me every 3M tokens used by this worker, up to 4 times.
Wake a reviewer when the worker stops.
Wake a peer when a file appears.

Low-level, it works like this:

You run Codex sessions through a shared app-server.
Your agent uses the skill and/or bare CLI to add a wake job.
The job stores a condition, a target thread, a message, and sometimes a watched thread.
A runner checks the queue, either manually or periodically through systemd.
When the condition is true, wakectl sends a normal app-server input turn to the target.
The target sees the message in its own transcript and continues from there.

15 August 2026 · Delivery update

wakectl switched to agent_message by default instead of user messages.

Current version

A normal wake now adds a short scheduled event to the agent’s context and starts a turn when the target is idle or stopped in an error state. Sending an ordinary instruction is a separate option. Scheduled events still remain in thread history.

wakectl setup & documentation ferrumctl · GitHub