bedtime-device-guard

Bedtime Device Guard

Use the bundled UserPromptSubmit hook to reject Codex prompts during a configured local-time window. The hook evaluates the clock locally, prints nothing during allowed hours, and therefore adds no model context or token usage.

This guard applies only to Codex surfaces that load and trust user hooks. Treat it as one layer alongside operating-system restrictions, scheduled shutdown, router rules, and phone controls. Do not claim it blocks another app or prevents a determined administrator from removing it.

Device-level schedules

The optional native schedules are broader than the Codex hook and can discard unsaved work. Confirm that the user wants forced shutdown before installing them. Each scheduled action re-checks the live local window before acting, so a job released late after sleep or coalescing does nothing after the configured end time.

macOS installs three user LaunchAgents: a warning before the start, a shutdown request at the start, and a forced GUI logout two minutes later if the Mac is still running. Install or manage them with:

bash skills/bedtime-device-guard/scripts/install-device-macos.sh install \
  --start HH:MM --end HH:MM --timezone local --warning-minutes 10
bash skills/bedtime-device-guard/scripts/install-device-macos.sh verify
bash skills/bedtime-device-guard/scripts/install-device-macos.sh uninstall

The shutdown request uses macOS System Events and may require the user to approve Automation access once. The logout fallback is deliberately forceful and is independent of that approval.

Windows installs two per-user native Scheduled Tasks: a warning and shutdown.exe /s /f /t 0. Run from PowerShell:

& skills/bedtime-device-guard/scripts/install-device-windows.ps1 install `
  -Start HH:mm -End HH:mm -Timezone local -WarningMinutes 10
& skills/bedtime-device-guard/scripts/install-device-windows.ps1 verify
& skills/bedtime-device-guard/scripts/install-device-windows.ps1 uninstall

Keep emergency communication on a separately constrained device; these schedules intentionally do not provide an on-computer bypass.

Install

Choose the user's schedule and timezone at installation time. Never add personal values to this repository.

On macOS or Linux:

bash skills/bedtime-device-guard/scripts/install-macos.sh \
  --start HH:MM --end HH:MM --timezone local

On Windows PowerShell:

& skills/bedtime-device-guard/scripts/install-windows.ps1 `
  --start HH:MM --end HH:MM --timezone local

local uses the computer's configured timezone and avoids an external timezone-data dependency. An IANA timezone such as Etc/UTC is also accepted when Python's zoneinfo database contains it. The installer stores the schedule only under the user's Codex home, copies the hook there, and merges one managed handler into hooks.json without replacing unrelated keys, events, groups, or handlers.

After installation:

1. Enable Codex hooks if needed with codex features enable hooks.
2. Start Codex and review/trust the new hook when prompted, or use /hooks.
3. Restart open Codex sessions so they reload the hook configuration.

Codex deliberately does not let an installer silently approve its own executable hook. If hooks are disabled or untrusted, this layer does not run.

Verify

Run the non-mutating verifier for the current machine:

python3 skills/bedtime-device-guard/scripts/install_guard.py verify

On Windows, replace python3 with py -3.

For a behavior check without waiting for bedtime, invoke the installed hook with --now and a local ISO timestamp. The test-only time override changes no configuration:

python3 "$HOME/.codex/bedtime-device-guard/bedtime_guard.py" \
  --config "$HOME/.codex/bedtime-device-guard/config.json" \
  --now 2030-01-01T23:00:00

A blocked check prints a compact JSON decision. An allowed check prints nothing.

Update the schedule

Run the installer again with the new values. Installation is idempotent: it refreshes the managed script and configuration, then replaces only this skill's managed hook handler.

Uninstall

On either platform, use the common installer directly:

python3 skills/bedtime-device-guard/scripts/install_guard.py uninstall

On Windows, replace python3 with py -3. Uninstall removes only the managed handler and its now-empty matcher group, preserves all other hook configuration, and removes the skill-owned installed directory. It does not disable Codex hooks globally.

Safety and limitations

• Back up an existing hooks.json before changing it and use atomic writes.
• Reject malformed times and same start/end values instead of guessing.
• Use the direct clock check as the source of truth. Do not replace it with a scheduled marker that can become stale across sleep, reboot, or missed jobs.
• Do not add a phrase-based bypass to the hook. Recovery remains possible by editing the local configuration or uninstalling from a terminal.
• Current Codex releases fail open if a hook cannot start, crashes, times out, or is not trusted. Keep stronger device-level controls independent of this hook.

Read references/codex-hook-contract.md when changing the hook output or hooks.json structure.