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, oradoptfor SkillOpt-Sleep.
The cycle
- Harvest - read local session transcripts according to the engine configuration and normalize them into session digests.
- Mine - turn digests into recurring
TaskRecords with outcomes and checkable references where possible. - Replay - re-run mined tasks through the selected backend under the current skill and memory.
- Consolidate - reflect on failures and propose bounded edits.
- Gate - with the default gate enabled, accept edits only when the held-out validation score improves.
- Stage - write the proposal under
<project>/.skillopt-sleep/staging/<date>/; nothing live changes. - 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.
bash# 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:: CMD set SKILLOPT_SLEEP_REPO=C:\path\to\SkillOpt-Sleep "%SKILLOPT_SLEEP_REPO%\plugins\run-sleep.cmd" status --project "%CD%"
powershell# 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 codexuses 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 codexreads Codex Desktop archived sessions from~/.codex/archived_sessions; use--codex-home /path/to/.codexif the archive lives elsewhere.--target-skill-pathis required for a Codex skill target. Without it, the shared default is a Claude-managed skill under~/.claude/skills/, not an.agentsskill.- Keep
dry-run --backend mockas the first smoke check unless the user explicitly asked for a real optimization run.
Scheduling
bashbash "$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
| Flag | Description |
|---|---|
--auto-adopt | Auto-adopt if the gate passes (default: stage only) |
--edit-budget N | Max bounded edits per night (default: 4) |
--lookback-hours N | Harvest window in hours (default: 72) |
--json | Machine-readable JSON output |
Config keys (~/.skillopt-sleep/config.json)
preferences— free-text house rules for the optimizergate_mode—on(validation-gated, default) oroff(greedy)gate_metric—hard|soft|mixed(default)gate_no_regression—falseby default; set it totrueto reject a candidate when any validation task's gate score decreasesdream_rollouts— >1 for multi-rollout contrastive reflectionrecall_k— >0 recalls similar past tasks from the archive
Memory consolidation
The shared sleep cycle consolidates project memory (CLAUDE.md) and the
selected skill (SKILL.md) by default. It does not update AGENTS.md.
Each target is independently toggleable through evolve_memory /
evolve_skill, and both are gated by the same held-out validation score.
Steps
- Run the requested action; capture stdout.
- For
dry-runandrun, report the held-out baseline -> candidate score, gate action, task count, session count, and exact proposed edits. - If a staging directory is printed, read
report.mdbefore summarizing. runstages by default; if--auto-adoptwas explicitly supplied, report the paths it updated instead of claiming nothing changed.- Offer adoption only after the user has reviewed a still-staged proposal.
- Never hand-edit the configured
CLAUDE.mdor target skill as a substitute for the engine's adopt path; adoption is the safety boundary and backs up existing targets first.
Hard rules
- Harvest is read-only. Do not edit archived sessions or raw transcripts.
- Codex transcript harvesting removes known secret-shaped strings, developer
instructions, and raw tool payloads, but pattern-based redaction is not a
guarantee. A real backend still sends truncated transcript/task content to
its provider. Review sensitive sessions and provider policy first; prefer a
reviewed
--tasks-fileworkflow when the data boundary matters. - Keep raw secrets, credentials, private user data, and 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
/sleepslash commands for this Codex integration. This skill is the entrypoint.
Validate
bashpython -m skillopt_sleep dry-run --project "$(pwd)" --source codex \ --target-skill-path .agents/skills/example/SKILL.md --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
In the recorded brief-writer gbrain run, the deliberately deficient fixture
went 0.00 -> 1.00 on that run's held-out set. Treat this as reproducible
benchmark evidence for that configuration, not a guarantee for other skills,
tasks, or models; see the
recorded results
for context and limitations.
