Skillopt Sleep

SkillOpt-Sleep for Cursor

SkillOpt-Sleep reviews recent local Cursor sessions, mines recurring tasks,

replays those tasks, and proposes bounded improvements to a project Cursor

skill. With the default gate enabled, a proposal is accepted only when it

improves the held-out score. A normal run stages the proposal for review;

nothing live changes until explicit adoption. There is no model-weight training.

This plugin has no session-end hook and no MCP server. Run the cycle only when

the user asks, or install a schedule only when the user explicitly requests one.

Cursor target

Always use this project-relative target for Cursor-visible learning:

.cursor/skills/skillopt-sleep-learned/SKILL.md

Pass it through --target-skill-path on harvest, dry-run, and run.

Without an explicit target, the shared engine uses a Claude-managed skill under

~/.claude/skills, which is not the intended Cursor project skill.

The shared engine can also evolve project CLAUDE.md. If that secondary memory

target is unwanted, set "evolve_memory": false in

~/.skillopt-sleep/config.json before running.

Choose the runner

Use one of these supported command paths consistently:

• Source checkout on macOS/Linux:

bash "$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh" <action> ...

• Source checkout on Windows:

powershell -File "$env:SKILLOPT_SLEEP_REPO\plugins\run-sleep.ps1" <action> ...

• Installed engine on any platform:

skillopt-sleep <action> ...

If SKILLOPT_SLEEP_REPO is not set and skillopt-sleep is unavailable, stop

and explain that the engine must be installed or a SkillOpt checkout must be

selected. Do not substitute a hand-written edit for the engine workflow.

Core workflow

• Harvest local Cursor JSONL transcripts read-only.
• Mine recurring, checkable task records from session digests.
• Replay tasks under the current skill and memory through the selected

backend.

• Reflect on failures and propose bounded edits.
• Gate the candidate on held-out real tasks.
• Stage accepted proposals under

<project>/.skillopt-sleep/staging/<timestamp>/.

• Adopt only after review, backing up existing live targets first.

Commands

Use the installed-command form below, or replace skillopt-sleep with the

platform-specific source runner described above.

TARGET_SKILL=.cursor/skills/skillopt-sleep-learned/SKILL.md

# Inspect current state and the latest staged proposal.
skillopt-sleep status --project "$(pwd)"

# Inspect mined tasks without provider spend.
skillopt-sleep harvest --project "$(pwd)" --source cursor \
  --target-skill-path "$TARGET_SKILL" --max-sessions 5 --max-tasks 3

# First smoke check: deterministic and no provider calls.
skillopt-sleep dry-run --project "$(pwd)" --source cursor --backend mock \
  --target-skill-path "$TARGET_SKILL" --max-sessions 5 --max-tasks 3 --json

# Model-driven optimization through the authenticated Cursor Agent CLI.
skillopt-sleep run --project "$(pwd)" --source cursor --backend cursor \
  --target-skill-path "$TARGET_SKILL" \
  --max-sessions 5 --max-tasks 3 --progress

# Apply the latest accepted staged proposal after review.
skillopt-sleep adopt --project "$(pwd)"

Actions are status, harvest, dry-run, run, adopt, schedule, and

unschedule.

• Default backend is mock, which is deterministic and makes no provider calls.
• --backend cursor uses the user's authenticated Cursor Agent CLI budget for

model-driven mining, replay, judging, and reflection.

• --source cursor reads

~/.cursor/projects/<workspace>/agent-transcripts/*/*.jsonl.

• --cursor-home PATH overrides the Cursor home used for harvesting.
• --scope invoked selects the current workspace; --scope all includes every

Cursor workspace.

• --cursor-path PATH or SKILLOPT_SLEEP_CURSOR_PATH selects a non-default

cursor-agent executable.

• --model NAME or SKILLOPT_SLEEP_CURSOR_MODEL overrides the Cursor model.
• Check model identifiers with cursor-agent --list-models; when cost matters,

verify the billed variant in Cursor's usage reporting.

• Keep live runs bounded with --max-sessions, --max-tasks, and --progress.
• A held-out gain is evidence for that run, not a promise of general improvement.

The first harvest uses a 72-hour lookback. Use --lookback-hours N for a wider

initial window or --lookback-hours 0 for all available history. A stateful

run, including a no-task run, records a harvest checkpoint; later runs use the

checkpoint rather than the initial lookback. Inspect counts with harvest or

dry-run before the first real run because those actions do not advance state.

Available backends are:

• mock - deterministic, with no provider calls (default);
• cursor - the authenticated Cursor Agent CLI;
• claude - the authenticated Claude CLI;
• codex - the authenticated Codex CLI;
• copilot - the authenticated GitHub Copilot CLI;
• handoff - prompt/answer files for an interactive agent session;
• azure_openai - the configured Azure OpenAI endpoint.

SkillOpt reads the target skill and inserts its text into replay prompts; it does

not invoke the file as a native Cursor skill. Ordinary Cursor backend calls run

in a new empty temporary workspace in read-only Ask mode. File reads, file

writes, and MCP tools are denied. --project controls harvesting, target files,

state, and staging; it is not the Cursor Agent execution workspace.

Cursor tool-aware replay is temporarily disabled pending live Cursor

permission-boundary validation. A task containing a tool_called check fails

nonzero before Agent mode starts. The failed replay does not add a cache entry,

stage, adopt, persist state, or advance the harvest checkpoint. Use another

backend for those tasks. Do not claim that repository- or tool-dependent

behavior was validated. The current engine does not implement a fresh-worktree

replay for Cursor.

A real-backend dry-run still makes provider calls; it only suppresses staging.

Session and task limits are workload bounds, not hard limits on calls, tokens,

time, or money. Start with small limits.

Reviewable data path

Cursor harvesting retains user/assistant text, tool names, and explicit turn

errors while excluding raw tool arguments, tool outputs, and non-message

records. Known secret-shaped strings are redacted, but pattern-based redaction

cannot guarantee that a transcript is safe to send to a provider.

For sensitive sessions, export tasks before any real-backend replay:

TARGET_SKILL=.cursor/skills/skillopt-sleep-learned/SKILL.md
skillopt-sleep harvest --project "$(pwd)" --source cursor \
  --target-skill-path "$TARGET_SKILL" \
  --max-sessions 5 --max-tasks 3 --output reviewed-tasks.json

Inspect and redact the file, then set its top-level "reviewed" field to

true. Only then run:

skillopt-sleep dry-run --project "$(pwd)" --backend cursor \
  --tasks-file reviewed-tasks.json --progress --json

Real backends reject task files that remain unreviewed. Never include raw

transcripts, credentials, secrets, or sensitive task content in messages,

commits, or generated summaries.

Scheduling

Scheduling is opt-in. The scheduler persists project, backend, time, and the

optional auto-adopt flag, but not --source, Cursor path/home/model overrides,

or --target-skill-path. Before scheduling a Cursor cycle, set at least these values in

~/.skillopt-sleep/config.json:

{
  "transcript_source": "cursor",
  "target_skill_path": ".cursor/skills/skillopt-sleep-learned/SKILL.md",
  "backend": "cursor"
}

Then run:

skillopt-sleep schedule --project "$(pwd)" --backend cursor --hour 3 --minute 17
skillopt-sleep unschedule --project "$(pwd)"

The scheduler uses cron on Unix and Task Scheduler on Windows. Scheduled runs

stage proposals by default. Use --auto-adopt only when the user has explicitly

requested unattended adoption.

Report results

For dry-run and run, report:

• session and task counts;
• held-out baseline and candidate scores;
• gate action and accepted/rejected edit counts;
• exact proposed edits;
• staging directory, when one was created.

Read staged report.md before summarizing a run. Offer adoption only after the

user reviews an accepted proposal that is still staged. Never claim broad

improvement from one run.

Hard rules

• Harvest is read-only. Never edit Cursor transcript files.
• Never hand-edit the target skill or CLAUDE.md as a substitute for adoption.
• Do not run a real backend on sensitive content without confirming its data

boundary or using the reviewed-task workflow.

• Do not add a session-end hook or imply that installing this plugin schedules

anything.

• Show validation evidence before recommending adoption.
• Treat generated edits as proposals, not as source of truth.