SkillOpt Sleep Cycle

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

SkillOpt-Sleep gives the user's agent a sleep cycle. On demand or on a nightly schedule, it reviews real past Claude Code sessions, re-runs recurring tasks through the selected backend, and consolidates what it learns into memory (CLAUDE.md) and skills (SKILL.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. It aims to improve this user's recurring work, while making each accepted proposal measurable on the run's held-out tasks, 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 are recorded in the run report for review.
• Claude Dreams — consolidation that reads past sessions and proposes changes inside protected learned blocks; the input is never mutated, and output is reviewed before adoption.
• Agent sleep — periodic background 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 through the selected backend under the current skill+memory → (hard, soft) scores.
4. Consolidate — reflect on failures → propose bounded edits → gate on a held-out slice; with the default gate enabled, accept only if it strictly improves.
5. Stage — write the accepted proposed_CLAUDE.md and/or proposed_SKILL.md, plus report.md, report.json, manifest.json, and diagnostics.json into <project>/.skillopt-sleep/staging/<timestamp>/. Nothing live changes. A rejected run still has a report but no proposed live-file replacement.
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)"    # no-staging 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 model-driven optimization. A held-out gain is run-specific evidence, not a guarantee of broader improvement; results depend on the tasks, model, and checks.
• Scope defaults to the invoked project; --scope all harvests every Claude project into the current run's configured targets.
• A real backend sends truncated transcript/task content to its provider. See the data-boundary rules below before using one with sensitive sessions.

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.

Common CLI flags

The CLI also has source/runtime path overrides (--claude-home, --codex-home, and --codex-path) and action-specific flags. Use python -m skillopt_sleep <action> --help as the authoritative surface.