scheduling-codex-window-starts

Files (3)

• README.md
• SKILL.md
• optimize_starts.py · scripts/

SKILL.md (first lines)

# Scheduling Codex Window Starts

## Overview

Calculate up to three scheduled start points whose rolling windows cover as much working time as possible, then ask the user to confirm the recommendation before creating automations.

## Gather Only Necessary Inputs

Ask for:

- daily working intervals, such as `10:00-12:00,15:00-18:00`
- recurrence: workdays, every day, or a custom weekly pattern

Infer the timezone from the current environment and state the inference. Ask only if it is unavailable or likely wrong. Ask about holiday behavior only when the chosen recurrence makes it relevant.

Do **not** ask how early to start; start times are outputs of the optimization.

## Window Length

Use a callable, account-level usage/reset tool when the current environment provides one. The interactive `/usage` TUI command is not itself an Agent tool and must not be assumed callable.

When no reliable tool is available, use `W = 300` minutes without blocking on user input. State this assumption when presenting the result. Accept a different window length when the user supplies one.

## Buffer Between Starts

Use a start-gap buffer `B` between consecutive scheduled starts.

- Default to `B = 5` minutes.
- Accept a different buffer when the user supplies one.
- Never use `B < 1`; clamp any smaller value up to `1` minute and say that you did so.

This buffer is **between starts**, not added to the usage window itself. The target gap between consecutive starts is `W + B`.

## Optimization Model

Treat working intervals and windows as half-open intervals `[start, end)` in minutes after midnight.

- A scheduled start must fall outside all working intervals.
- A start at `s` creates `[s, s + W)`.
- A later start should be scheduled at least `W + B` minutes after the previous start.
- Evaluate at most `K = 3` starts.
- Maximize working minutes covered by the union of effective windows.
- Among equal maximum-coverage solutions, use the fewest starts; among remaining ties, prefer later starts.

Run the bundled optimizer:

```bash
python3 scripts/optimize_starts.py \
  --interval 10:00-12:00 \
  --interval 15:00-18:00 \
  --window 300 \
  --buffer 5 \
  --max-starts 3
```

The script evaluates every non-working minute with dynamic programming, then applies the configured start-gap buffer. Do not replace the result with a fixed lead-time heuristic.

The script handles `B` directly:

1. It optimizes the base schedule with the true window length `W`.
2. It keeps the latest start fixed when possible.
3. It walks backward through earlier starts and ensures each consecutive pair is separated by at least `W + B`.
4. If a pair is too close, it moves the earlier start earlier first.
5. If that is impossible without entering working time, it moves the later start later and reports that tradeoff in the JSON output.
6. It re-checks coverage using the original window length `W`, not `W + B`.

For a custom weekly schedule, run the optimizer once per distinct daily interval pattern and group weekdays that produce the same start points.

For the example above, the base optimizer recommends `09:59` and `14:59`, covering all `300/300` working minutes. With the default `B = 5`, the final schedule becomes `09:54` and `14:59`. Show the adjusted result and coverage from the script output.

## Present Before Creating

Show:

- recommended start times and resulting windows
- covered minutes / total working minutes and percentage
- assumed or observed window length
- assumed or chosen buffer
- timezone and recurrence
- any uncovered working intervals

Ask the user to confirm or adjust the recommendation. Do not create an automation in the same turn that first collects the working intervals unless the user already authorized immediate creation.

## Create the Automation

Use the Codex automation tool and update a matching automation instead of duplicating it. Use one standalone automation containing all confirmed daily times when supported. Preserve default model and reasoning settings.

If the confirmed daily times do not share the same minute value, prefer one automation per time instead of trying to encode them in one RRULE that would create unwanted cross-product times.

Use this minimal prompt:

> This is a lightweight Codex window start. Do not inspect or modify project files, run commands, access the network, or perform follow-up work. Complete with nothing to report.

If no automation tool is available, provide the schedule and prompt without claiming they were saved.

## Limits

- A normal user request during an active window does not move its end time.
- A user request while no window is active may change the real schedule. Local thread activity cannot reliably reveal account window state.
- Checking account state from inside a Codex automation cannot avoid that run's usage; Codex has already been invoked.
- The optimizer maximizes guaranteed coverage from scheduled starts; it does not model quota consumption within a window.
- Each automation consumes agentic usage. Never describe it as free or as a guaranteed quota reset.

From Orchardxyz/agent-skills, MIT.

More from Orchardxyz/agent-skills