Terminal
Terminal/Skill
Lets your Claude agent learn from past sessions by replaying recurring tasks and proposing CLAUDE.md or SKILL.md edits that you review before adopting.
By Microsoft
Works with
npx skills add microsoft/skillopt --skill skillopt-sleepSkillOpt-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:
Trigger when the user wants any of:
CLAUDE.md or a managed skill~/.claude/projects/*/<session>.jsonl + ~/.claude/history.jsonl (READ-ONLY) → session digests.TaskRecords (recurring intents + outcome labels + checkable refs where possible).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.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)
mock (deterministic, no API spend) — good for trying the plumbing.--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 all harvests every Claude
project into the current run's configured targets."${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.
| Flag | Default | Description |
|---|---|---|
--project PATH | cwd | Project directory to evolve |
--scope all|invoked | invoked | Harvest scope |
--backend mock|claude|codex|copilot|handoff|azure_openai | mock | Backend (mock = no provider calls) |
--model NAME | backend default | Override the model used for replay |
--source claude|codex|auto | claude | Transcript source |
--lookback-hours N | 72 | Harvest window |
--max-sessions N | derived | Cap harvested sessions; defaults to 3 × max tasks (120 with current defaults) |
--max-tasks N | 40 | Cap mined tasks |
--target-skill-path PATH | ~/.claude/skills/skillopt-sleep-learned/SKILL.md | Explicit SKILL.md to evolve |
--tasks-file PATH | — | Reviewed TaskRecord JSON (skip harvest) |
--progress | off | Print phase progress to stderr |
--auto-adopt | off | Auto-adopt if gate passes |
--edit-budget N | 4 | Max bounded edits per night |
--preferences TEXT | empty | Add house rules to the optimizer's reflection prior |
--json | off | Machine-readable JSON output |
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.
~/.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.gate_no_regression — false by default. Set to true to reject a candidate when any validation task's configured gate score decreases.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.The sleep cycle can consolidate both:
With the default gate enabled, both are evaluated by the same held-out score.
Set evolve_memory: false to consolidate only skills, or evolve_skill: false
for only memory.
CLAUDE.md / SKILL.md as part of this skill.
Let the engine's explicit adopt or user-requested --auto-adopt path apply
the staging manifest and back up existing live files first.mock replay has no side effects.mock or run harvest --output <file>, inspect/redact the JSON, set
"reviewed": true, and replay it with --tasks-file; real backends refuse an
unreviewed task file.python -m skillopt_sleep.experiments.run_experiment --persona researcher --json
— a deterministic synthetic demo of held-out lift and gate rejection. It
validates the mechanism, not effectiveness on the user's own tasks.# deterministic synthetic demo (no API): score rises and the gate blocks a regression
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 documentation for recorded results, limitations, and the supported integration surface.