Plugin-declared monitors for periodic background tasks

What variant of Codex are you using?

Codex App and CLI plugin system. I verified this against the current openai/codex main branch (694edc23b22b4696400dc47663ecacd437623870).

What feature would you like to see?

Allow plugins to declare monitors: bounded, one-shot background tasks that the Codex host invokes periodically and manages as part of the plugin lifecycle, similar to Claude Code plugin monitors.

Problem

Codex plugins can currently bundle lifecycle hooks, but hooks only run in response to session or agent-loop events. They cannot wake up periodically when there is no active chat.

Codex also has user-owned Scheduled Tasks, and the remote plugin catalog can expose scheduled_tasks metadata in plugin/read responses (#32272). However, a local or marketplace plugin cannot declare a host-managed periodic task, and enabling the plugin does not establish one.

External cron / launchd / CI plus codex exec is possible, but it is not tied to plugin enable/disable/uninstall, is platform-specific, and unnecessarily invokes an agent for deterministic maintenance work.

Concrete use case

The open-source devloop plugin periodically reconciles local branches and managed worktrees with authoritative GitHub/GitLab PR state. Its task is idempotent and bounded: run one reconciliation pass, remove only safe worktrees whose PR has merged, report deferred actions, and exit.

Claude Code can discover a plugin monitor that repeats this task. In Codex, the same plugin and task are installed successfully, but the reconciliation never runs unless every user separately configures a Scheduled Task or an OS-level scheduler.

Other likely use cases include refreshing plugin-owned indexes, syncing caches, polling review state, and running lightweight diagnostics.

Suggested contract

A plugin could declare monitor metadata, for example:

{
  "monitors": [
    {
      "name": "pr-lifecycle-reconcile",
      "command": "...",
      "intervalSeconds": 120,
      "scope": "workspace",
      "timeoutSeconds": 30
    }
  ]
}

The exact schema is less important than the lifecycle contract:

• Installation or first enablement shows the monitor definition and requires explicit user trust/consent; plugins should not silently create background work.
• The plugin supplies a one-shot task; Codex owns repetition, singleton-per-scope execution, overlap prevention, jitter/backoff, and missed-tick coalescing.
• Codex provides PLUGIN_ROOT, PLUGIN_DATA, and the selected workspace/repository scope.
• Disabling or uninstalling the plugin stops its monitors and removes their registrations.
• Users can inspect status, last run/result, failures, and logs, and can invoke “Run now”.
• Deterministic command monitors should not require a model call. Prompt/agent-based recurring work can remain a Scheduled Task concern.

Why a separate monitor concept?

• Lifecycle hooks react to an existing session event; they are not a scheduler.
• Scheduled Tasks are user workflows that run an agent prompt and should remain user-owned.
• Plugin monitors are plugin-owned maintenance capabilities whose lifecycle should follow the plugin and whose execution may be fully deterministic.

This separation would let plugins offer reliable periodic capabilities without installing orphaned OS jobs or consuming model calls merely to invoke a script.

Additional information

Relevant current behavior:

• Codex hooks document lifecycle events but no timer/periodic event.
• codex exec supports external scheduled jobs, which is useful as an integration workaround but does not solve plugin lifecycle management.
• #32272 exposes scheduled-task summaries for remote plugin details, suggesting that schedule metadata is already becoming part of the plugin-facing surface.

Start by tracing the existing plugin lifecycle, lifecycle hooks, Scheduled Tasks, and plugin/read metadata surfaces described in the issue. Define the monitor lifecycle and consent, execution, scope, and status behavior, then verify that enabling, disabling, and uninstalling a plugin manage monitor registrations without requiring model calls for deterministic commands.