SkillOpt-Sleep: offline self-evolution for a local Codex agent

SkillOpt-Sleep gives the user's Codex agent a sleep cycle. While the user is offline or on demand, it reviews past local sessions, re-runs recurring tasks on the user's own budget, and consolidates what it learns into memory and skills. It keeps only changes that pass a held-out validation gate, and live files change only after the user explicitly adopts a staged proposal. There is no model-weight training.

When to use

Trigger when the user wants any of:

• Codex to learn from past sessions or get better the more they use it;
• a nightly/scheduled or on-demand sleep/dream/offline self-improvement run;
• to review past sessions and distill recurring tasks;
• to consolidate feedback into memory or managed skills;
• to run status, harvest, dry-run, run, or adopt for SkillOpt-Sleep.

The cycle

1. Harvest - read local session transcripts according to the engine configuration and normalize them into session digests.
2. Mine - turn digests into recurring TaskRecords with outcomes and checkable references where possible.
3. Replay - re-run mined tasks offline under the current skill and memory.
4. Consolidate - reflect on failures and propose bounded edits.
5. Gate - accept edits only when the held-out validation score improves.
6. Stage - write the proposal under <project>/.skillopt-sleep/staging/<date>/; nothing live changes.
7. Adopt - only after explicit user approval, copy staged files over live files with backups.

How to drive it

Invoke the bundled runner via shell (Codex exec has shell access). The runner finds the engine and a Python >= 3.10 automatically.

# point at the repo if it isn't auto-detected from CWD:
export SKILLOPT_SLEEP_REPO=/path/to/SkillOpt-Sleep
bash "$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh" status --project "$(pwd)"
bash "$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh" harvest --project "$(pwd)"
bash "$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh" dry-run --project "$(pwd)" --backend mock
bash "$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh" run --project "$(pwd)" --backend codex
bash "$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh" run --project "$(pwd)" --source codex  # harvest from Codex Desktop
bash "$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh" adopt --project "$(pwd)"

Actions are status, harvest, dry-run, run, adopt, schedule, and unschedule.

• Default backend is mock, which is deterministic and spends no API budget.
• --backend codex uses the user's Codex budget for real improvement.
• --source codex reads Codex Desktop archived sessions from ~/.codex/archived_sessions; use --codex-home /path/to/.codex if the archive lives elsewhere.
• Keep dry-run --backend mock as the first smoke check unless the user explicitly asked for a real optimization run.

Scheduling

bash "$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh" schedule --project "$(pwd)" --hour 3 --minute 17
bash "$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh" unschedule --project "$(pwd)"

Installs a nightly cron entry. unschedule --all removes every managed entry.

All backends

• --backend mock — deterministic, no API spend (default)
• --backend claude — uses the Claude CLI
• --backend codex — uses the Codex CLI
• --backend copilot — uses the GitHub Copilot CLI

Additional flags

Config keys (~/.skillopt-sleep/config.json)

• preferences — free-text house rules for the optimizer
• gate_mode — on (validation-gated, default) or off (greedy)
• gate_metric — hard | soft | mixed (default)
• dream_rollouts — >1 for multi-rollout contrastive reflection
• recall_k — >0 recalls similar past tasks from the archive

Memory consolidation

The sleep cycle consolidates both memory (AGENTS.md / CLAUDE.md) and skills (SKILL.md) by default. Each is independently toggleable via evolve_memory / evolve_skill config keys. Both are gated by the same held-out validation score.

Steps

1. Run the requested action; capture stdout.
2. For dry-run and run, report the held-out baseline -> candidate score, gate action, task count, session count, and exact proposed edits.
3. If a staging directory is printed, read report.md before summarizing.
4. run only stages a proposal; nothing live changes until adopt.
5. Offer adoption only after the user has reviewed the staged proposal.
6. Never hand-edit the user's AGENTS.md, memory, or skills as a substitute for adopt; adoption is the safety boundary and writes backups first.

Hard rules

• Harvest is read-only. Do not edit archived sessions or raw transcripts.
• Keep raw secrets, credentials, private user data, and unsanitized transcript contents out of messages, logs, generated artifacts, and commits.
• Show validation evidence before recommending adoption.
• Treat generated edits as proposals, not as source of truth.
• Do not rely on deprecated custom prompts or /sleep slash commands for this Codex integration. This skill is the entrypoint.

Validate

python -m skillopt_sleep dry-run --project "$(pwd)" --backend mock --json
python -m skillopt_sleep.experiments.run_gbrain --backend codex \
  --seeds brief-writer --data-root /path/to/gbrain-evals/eval/data/skillopt-v1 \
  --nights 2 --limit-replay 3 --limit-holdout 3

A deficient skill goes 0.00 -> 1.00 on a held-out set; the optimizer's edits are gated on real-task performance.