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.

skillopt-sleep — OpenClaw Adaptation of Microsoft SkillOpt-Sleep

A nightly self-improvement loop that reads our session transcripts, mines recurring workflow patterns, replays them with proposed skill edits, and gates the proposals against a held-out test set. Only improvements that beat baseline are staged for human adoption.

When To Use

• After Hermes's Weekly Skill Review (or as its replacement)
• When a skill is being used 10+ times/week and could be tighter
• Before promoting a new skill from skill-proposals/ to skills/
• When a skill regresses in observed quality

What It Does (One Cycle)

harvest session transcripts  ->  mine recurring task patterns
                              ->  replay each pattern (current skill vs proposed)
                              ->  GATE: must improve held-out score
                              ->  stage proposal
                              ->  Ethan adopts (manual)

Nothing live changes until Ethan adopts. Every adopt backs up first.

Architecture

skills/skillopt-sleep/
├── SKILL.md                          # this file
├── config.json                       # engine config (backend, budgets, etc.)
├── run_sleep.py                      # entry point
└── skillopt_sleep_openclaw.py        # DeepSeek/Ollama backend

The engine itself is at ~/.openclaw/workspace/SkillOpt/skillopt_sleep/ (cloned from microsoft/SkillOpt).

Usage

# Run one cycle with current config
cd ~/.openclaw/workspace/skills/skillopt-sleep
python3 run_sleep.py

# Dry run (report only, no staging)
python3 run_sleep.py --dry-run

# Use a pre-built task set (recommended for testing)
python3 run_sleep.py --tasks tests/research-cron-tasks.json

Scheduling

python3 slash_sleep.py schedule --hour 3 --minute 17
python3 slash_sleep.py unschedule
python3 slash_sleep.py unschedule --all

Installs a nightly cron entry using the shared SkillOpt-Sleep scheduler. This is an alternative to the external run_sleep_cron.sh script.

Alternative backends

While OpenClaw defaults to openclaw-deepseek (DeepSeek V4 Pro + Ollama), the shared engine also supports:

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

These can be used via the engine directly (python -m skillopt_sleep).

Shared-engine flags

When invoking the engine directly, all standard flags are available:

• --source codex / --source auto — harvest from Codex Desktop sessions
• --tasks-file PATH — use a pre-built task set
• --target-skill-path PATH — explicit SKILL.md target
• --max-tasks N / --max-sessions N — cap workload
• --progress — print phase progress
• --json — machine-readable output
• --auto-adopt — auto-adopt if gate passes

Config keys: preferences, gate_mode, gate_metric, dream_rollouts, recall_k, evolve_memory, evolve_skill.

Config (config.json)

Key knobs:

• backend: "openclaw-deepseek" — our custom backend
• model: "deepseek-v4-pro" — optimizer model
• edit_budget: 3 — max bounded edits per night
• gate_mode: "on" — validation-gated (rejects regressions)
• auto_adopt: false — require Ethan to adopt manually
• max_tasks_per_night: 12 — cap to control cost

Cost Estimate

Per night: 12 tasks × (1 attempt + 1 judge + 1 reflect) × ~$0.005/1K tokens × ~3K tokens/call ≈ $0.50-2.00/night.

Outputs

• Report: ~/.skillopt-sleep/state.json (running totals)
• Staging: ~/.skillopt-sleep/staging/<night>/
  • report.md — readable summary
  • best_skill.md — proposed skill
  • edits.json — bounded edit list
  • before.md / after.md — diffs

Held-Out Test Sets (Phase 2)

Located at tests/<category>-tasks.json. Each task has:

• prompt — the recurring task
• reference — exact-match gold answer
• rubric — soft score rubric (0-1)
• domain — research/devops/wiki/etc.

Currently building for 3 categories:

• research-cron-output
• devops-infrastructure-check
• wiki-canonical-guide

When NOT To Use

• For a one-off workflow (not a recurring pattern)
• During a crisis/incident (humans must lead)
• When session transcripts are < 24h old (not enough signal)
• For skills < 300 tokens (over-optimization risk)

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

SkillOpt-Sleep gives the user's agent a sleep cycle. While the user is offline (e.g. nightly), it reviews their real past Claude Code sessions, re-runs recurring tasks on their own API budget, and consolidates what it learns into memory (CLAUDE.md) and skills (SKILL.md) — but only keeps changes that pass a held-out validation gate, and only after the user adopts them. The agent gets measurably better at this user's recurring work, with no model-weight training. It is the deployment-time analogue of training: short-term experience → long-term competence.

It synthesizes three ideas:

• SkillOpt — the skill/memory doc is trainable text; bounded add/delete/replace edits; accepted only through a held-out gate; rejected edits become negative feedback.
• Claude Dreams — offline consolidation that reads past sessions and rebuilds memory (dedup/merge/resolve); the input is never mutated; output is reviewed then adopted.
• Agent sleep — periodic offline replay turns episodes into durable skill.

When to use this skill

Trigger when the user wants any of:

• "make my agent learn from how I use it" / "get better the more I use it" / "remember my preferences across sessions"
• a nightly/scheduled or on-demand offline self-improvement / dream / sleep run
• to review past sessions/trajectories and distill recurring tasks
• to consolidate feedback into CLAUDE.md or a managed skill
• to schedule the cycle (cron) or adopt a staged proposal

The cycle (six stages)

1. Harvest — read ~/.claude/projects/*/<session>.jsonl + ~/.claude/history.jsonl (READ-ONLY) → session digests.
2. Mine — digests → TaskRecords (recurring intents + outcome labels + checkable refs where possible).
3. Replay — re-run tasks offline under the current skill+memory → (hard, soft) scores.
4. Consolidate — reflect on failures → propose bounded edits → gate on a held-out slice; accept only if it strictly improves.
5. Stage — write proposed_CLAUDE.md, proposed_SKILL.md, a diff, and report.md into <project>/.skillopt-sleep/staging/<date>/. Nothing live changes.
6. Adopt — explicit (or opt-in auto): copy staged files over live ones, backing up first.

How to drive it

Prefer the /skillopt-sleep command. Under the hood it calls the bundled runner:

"${CLAUDE_PLUGIN_ROOT}/scripts/sleep.sh" status                       # what's happened
"${CLAUDE_PLUGIN_ROOT}/scripts/sleep.sh" dry-run --project "$(pwd)"    # safe preview
"${CLAUDE_PLUGIN_ROOT}/scripts/sleep.sh" run --project "$(pwd)"        # full cycle, stages a proposal
"${CLAUDE_PLUGIN_ROOT}/scripts/sleep.sh" adopt --project "$(pwd)"      # apply staged proposal (with backup)

• Default backend is mock (deterministic, no API spend) — good for trying the plumbing.
• Add --backend claude or --backend codex to spend the user's real budget for genuine improvement.
• Scope defaults to the invoked project; --scope all harvests every project.

Scheduling

"${CLAUDE_PLUGIN_ROOT}/scripts/sleep.sh" schedule --project "$(pwd)" --hour 3 --minute 17
"${CLAUDE_PLUGIN_ROOT}/scripts/sleep.sh" unschedule --project "$(pwd)"

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

All CLI flags

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

Beyond the CLI flags, advanced behavior is controlled via config:

• preferences — free-text house rules injected into the optimizer's reflect step (e.g. "Always use async/await", "Answers in \boxed{}").
• gate_mode — on (default, validation-gated) or off (greedy, accept all edits).
• gate_metric — hard, soft, or mixed (default). Controls how the held-out gate scores.
• dream_rollouts — >1 enables multi-rollout contrastive reflection per task.
• recall_k — >0 recalls K similar past tasks into the dream (long-term memory).
• evolve_memory / evolve_skill — independently toggle CLAUDE.md vs SKILL.md consolidation.

Memory consolidation

The sleep cycle can consolidate both:

• SKILL.md — the managed skill file (bounded edits: add/delete/replace)
• CLAUDE.md — the project memory (same bounded edits)

Both are gated by the same held-out validation score. Set evolve_memory: false to consolidate only skills, or evolve_skill: false for only memory.

Hard rules

• Never hand-edit the user's CLAUDE.md / SKILL.md as part of this skill. Only the adopt action changes live files, and it backs them up first.
• Harvest is read-only. mock replay has no side effects.
• Always show the user the held-out baseline → candidate score and the exact proposed edits before suggesting adoption. Evidence before adoption.
• If asked whether it really helps, run python -m skillopt_sleep.experiments.run_experiment --persona researcher --json — a deterministic demo that proves held-out lift and that the gate blocks harmful edits.

Validate / demo

# deterministic proof (no API): held-out score rises, gate blocks regressions
python -m skillopt_sleep.experiments.run_experiment --persona researcher --assert-improves
python -m skillopt_sleep.experiments.run_experiment --persona programmer  --assert-improves

See the SkillOpt-Sleep guide section for recorded output and docs/superpowers/specs/2026-06-07-skillopt-sleep-claude-code-plugin-design.md for the full design.