SkillOpt-Sleep Self-Improvement Cycle

SkillOpt-Sleep: usage-driven self-evolution for a local Codex agent

SkillOpt-Sleep gives the user's Codex agent a sleep cycle. On demand or on a nightly schedule, it reviews past local sessions, re-runs recurring tasks through the selected backend, and proposes changes to a configured skill and to the project's CLAUDE.md. With the default validation gate enabled, it keeps only changes that improve a held-out score. Live files change only through explicit adoption or a user-requested --auto-adopt. There is no model-weight training.

The current shared engine does not write AGENTS.md. For a Codex-visible result, always select a Codex skill explicitly with --target-skill-path (for example .agents/skills/<name>/SKILL.md). If project CLAUDE.md is not a desired secondary target, set "evolve_memory": false in ~/.skillopt-sleep/config.json before running.

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 through the selected backend under the current skill and memory.
4. Consolidate - reflect on failures and propose bounded edits.
5. Gate - with the default gate enabled, 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 - explicitly, or through user-requested auto-adopt, copy staged files over live files with backups for existing targets.

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
TARGET_SKILL=.agents/skills/example/SKILL.md
bash "$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh" status --project "$(pwd)"
bash "$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh" harvest --project "$(pwd)" \
  --source codex --target-skill-path "$TARGET_SKILL"
bash "$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh" dry-run --project "$(pwd)" \
  --source codex --target-skill-path "$TARGET_SKILL" --backend mock
bash "$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh" run --project "$(pwd)" \
  --source codex --target-skill-path "$TARGET_SKILL" --backend codex \
  --max-sessions 5 --max-tasks 3 --progress
bash "$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh" status --project "$(pwd)"
bash "$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh" adopt --project "$(pwd)" --legacy

For a fan-out night, select reviewed proposals with repeatable --skill NAME or --all-skills; do not treat bare adopt as “adopt everything.”

On Windows (CMD / PowerShell):

:: CMD
set SKILLOPT_SLEEP_REPO=C:\path\to\SkillOpt-Sleep
"%SKILLOPT_SLEEP_REPO%\plugins\run-sleep.cmd" status --project "%CD%"

# PowerShell
$env:SKILLOPT_SLEEP_REPO = "C:\path\to\SkillOpt-Sleep"
powershell -File "$env:SKILLOPT_SLEEP_REPO\plugins\run-sleep.ps1" status --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 model-driven optimization. An accepted held-out gain is run-specific evidence, not a guarantee of broader improvement; results depend on the tasks, model, and checks.
• --source codex reads Codex Desktop archived sessions from ~/.codex/archived_sessions; use --codex-home /path/to/.codex if the archive lives elsewhere.
• --target-skill-path is required for a Codex skill target. Without it, the shared default is a Claude-managed skill under ~/.claude/skills/, not an .agents skill.
• 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)" \
  --backend codex --hour 3 --minute 17
bash "$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh" unschedule --project "$(pwd)"

The scheduler persists the project, backend, time, and optional auto-adopt flag; it does not persist --source or --target-skill-path from this command. Before scheduling a Codex-targeted run, set "transcript_source": "codex" and an absolute "target_skill_path" in ~/.skillopt-sleep/config.json. On systems without crontab, schedule prints a line for manual installation. 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
• --backend handoff — emits prompt/answer files for an interactive session
• --backend azure_openai — uses the configured Azure OpenAI endpoint

Additional flags