overnight-run
Skill2 starsChanged 23 days agoMITView on GitHub
Leave an agent working alone on one task under a contract: trust checks first, a finish condition a script checks, an append-only log, reverts, an off switch and a morning audit by a fresh reviewer. Use when the user says 'run this overnight', 'keep going while I sleep', 'work on this while I am away', or wants a long unattended run. /loop only wakes; for one number, hillclimb fits.
- Deletes or force-pushes
1 other project uses a version of this.
Adopted by
Most recently taken up by
- 2233admin/reverse-skill-evolvertheir own version, first seen Oct 15, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- 2233admin/reverse-skill-evolver★ 26same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository38 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- arenaSkill
- codebase-oracleSkill
- geppettoSkill
- lean-subagent-devSkill
- methodologySkill
- parallel-worktreesSkill
- dependency-security-auditSkill
- dependency-upgradeSkill
- rule-to-hookSkill
- safe-mergeSkill
- agent-friendly-auditSkill
- architectSkill
- brainstormSkill
- engineering-principlesSkill
- grill-meSkill
- improve-codebase-architectureSkill
- sharpenSkill
- to-issuesSkill
- to-prdSkill
- handoffSkill
- instructions-auditSkill
- project-setupSkill
- retrospectiveSkill
- session-closeSkill
- which-skillSkill
- bug-fixSkill
- ci-cost-and-cadenceSkill
- evaluatorSkill
- flaky-test-huntSkill
- hillclimbSkill
- launch-readinessSkill
- migration-reviewSkill
- mutation-testSkill
- review-triageSkill
- skill-evalSkill
- tddSkill
- verify-appSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
19 rules. About 0 are common, 9 are distinctive, and 10 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈9
Distinctive · estimate
This author's own choices. Worth a look.
10
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 15
Leave an agent working on one task while the user is away, and give them a result they can check in the morning.
- Distinctive: line 21
If you started this skill on your own, without the user typing its name or asking for what it does, first say in one or two lines what it …
- Distinctive: line 55
If any item is missing and nobody can fix it now (a headless run, or the user has left), do not start the loop.
- Very specific: line 75
A stop, set now: Use the stop rules of methodology if it is installed (every unattended run has a dead end and a budget, set before it …
- Very specific: line 91
Read ${CLAUDE_SKILL_DIR}/PROTECTION.md now: the allow list in dontAsk mode is the protection, and the strong protection takes the means …
- Very specific: line 114
Read ${CLAUDE_SKILL_DIR}/CONTRACT.md now: fill in its RUN.md template, then log the contract as the first row.
- Distinctive: line 129
Run the test command in the worktree.
- Very specific: line 130
Run the predicate. It fails, with the remaining count you expect.
- Very specific: line 137
Read ${CLAUDE_SKILL_DIR}/LOOP.md now.
- Very specific: line 146
Off switch: Check <control>/STOP in a call of its own (ls <control>), and act on its answer before any edit: if it exists, go to step 6.
- Very specific: line 151
Check the predicate: run bash <control>/done.sh.
- Distinctive: line 157
Decide: Keep when the predicate moved (the remaining count fell, or it passes) and the tests pass.
- Distinctive: line 168
A plateau is not a stop: After three reverts in a row, change the approach (read the failure again, try a different hypothesis, take a …
- Very specific: line 175
Never edit or delete a row.
- Distinctive: line 179
Every stop starts the same way: finish the current step or back it out (never leave half a change), then:
- Very specific: line 188
Dead end (the escape hatch): when truly stuck, stop and write up why in resume.md: each approach tried, what each showed, and what would …
- Distinctive: line 200
After every stop, before the summary: a fresh reviewer that did not see the run reads the log against the transcript.
- Very specific: line 224
Write <state>/summary.md and reply with the same text:
- Distinctive: line 246
Leave the branch, the worktree and the run folder in place, and do not push or open a pull request: the user decides in the morning.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Overnight run
The task: $ARGUMENTS
Leave an agent working on one task while the user is away, and give them a result they can check in the morning. The run starts only once it has earned trust. It works in its own worktree, stops on a finish condition a script checks, logs every decision to an append-only log outside the repository, reverts what did not help, and stops and writes up why when it is stuck. It ends with an audit of its trail by a fresh reviewer and a summary whose last section, Attention, says what to look at first.
If you started this skill on your own, without the user typing its name or asking for what it does, first say in one or two lines what it will do and what it will cost, and wait for a yes. A remark or a question that only matches its description is not asking for it. If the user asked for it, or the brief you are working from does, go ahead.
How it differs from its neighbours:
- The built-in
/loopcommand and scheduled tasks are timers: they wake an agent. This skill is the contract and the audit around one run; step 4 picks the timer. - To make one number better (run time, size, a score), use
hillclimbif it is installed: it is this loop with measurement and noise rules. Without it, use this skill with the target number as the finish predicate. - The stop rules come from
methodologyif it is installed; step 1 has a short fallback.
Bundled files, open each when you reach its step:
${CLAUDE_SKILL_DIR}/log.mjs(Node 20+, no dependencies):appendadds one row to the decision log,showprints it with what supersedes what, andcallslists the tool calls in a transcript for the audit. Step 2 copies it into the control folder; from then onLOGstands fornode <control>/log.mjs, written exactly so, without quotes, because a permission rule matches the command as written (Bash(node <control>/log.mjs *)does not matchnode "<control>/log.mjs"). Write the full command each time: a shell variable does not survive from one Bash call to the next.${CLAUDE_SKILL_DIR}/LOOP.md: each way to wake a run and what it needs, the outer shell loop aroundclaude -pwith its permission rules, and where the log goes for a cloud scheduled task.${CLAUDE_SKILL_DIR}/AUDIT.md: the morning reviewer's prompt.${CLAUDE_SKILL_DIR}/PROTECTION.md: what protects the repository (step 1).${CLAUDE_SKILL_DIR}/CONTRACT.md: theRUN.mdtemplate and the first log row (step 2).${CLAUDE_SKILL_DIR}/WAKE.md: the ways to wake a run, in a table (step 4).
Make a task list with one entry per step (Trust, Contract, Worktree, Wake, Loop, Stop, Audit, Summary) before you start.
Step 1. Earn the trust, or do not start
A loop nobody trusts produces unchecked work faster. Check each item below and write a short table: the item, holds or missing, and the evidence. Ask the user (AskUserQuestion) for what is missing while they are still here.
If any item is missing and nobody can fix it now (a headless run, or the user has left), do not start the loop. Reply with the table, what each missing item needs, and an offer to run the task attended first. That reply is the whole run.
- The task has run attended at least once. The user watched an agent do this task, or one iteration of it, on this repository, in this session or one they point to, so both know what a good iteration looks like. "It should be easy" is not that. If not, run one iteration now with the user watching, then come back here.
- A finish predicate a script can check: a command that exits 0 when the task is done and non-zero before,
and prints on its last line how far there is to go (
remaining: 12: failing tests, old callers, lint errors). For example! grep -rn 'oldParse(' src/followed by the test command, or the test command alone when failing tests are the task (pytest -q,go test ./...,cargo test,mvn -q test,dotnet test,npm test). Name the files that define it (the test files, the test configuration, the package scripts it runs): they are frozen with it in step 2.- A duration is not a finish condition: "work on it for four hours" gives nothing to check, and the user wakes up to four hours of motion. A duration can be a budget (item 4).
- "Better", "cleaner" or "faster" is not a predicate until it is a count or a check.
- It fails now, for the reason the task names. If it passes already, there is nothing to run.
- The checks are fast and trusted. The predicate and the test command each finish in minutes, and give the same answer twice on unchanged code: run both twice now. A flaky check turns every keep and revert into a coin toss; fix it first, attended.
- A stop, set now. Use the stop rules of
methodologyif it is installed (every unattended run has a dead end and a budget, set before it starts). Without it: a dead end (3 different approaches with no progress on the predicate, or no untried idea left, whichever comes first) and a budget (iterations, default 20; money, as--max-budget-usdper headless turn; and a wall clock time, as a budget, never as the finish). Reaching either stops the run. The run never raises its own budget. - Permissions settled in advance, as an allow list. See "What protects the repository" below. The run gets
exactly the commands it needs and nothing else, in a mode that refuses the rest without asking. A run cannot read
the flags it was started with: take them from the user's message or the settings, and copy them into
RUN.md. - The work can be thrown away: a fresh worktree on its own branch (step 3) and nothing pushed, so a bad night costs one branch.
The predicate is never relaxed during the run: not a threshold, not a skipped or deleted test, not an excluded folder. A predicate that turns out wrong stops the run (step 6), and the user amends it.
What protects the repository
Read ${CLAUDE_SKILL_DIR}/PROTECTION.md now: the allow list in dontAsk mode is the protection, and the strong
protection takes the means away.
Step 2. Write the contract
Make a run folder outside the repository's work tree, where git reset --hard and git clean -fdx cannot reach
it and every wake can find it: from the repository root, print echo "$(cd .. && pwd)/<repo>-overnight/<label>",
where the label is the date and a short slug (2026-10-18-parser). It holds two folders, and every path below is
absolute:
<control>(<run>/control): written now, attended, and never by a turn. No turn gets an allow rule to write it, its folder is never passed with--add-dir, andEdit(/<control>/**)is denied. It holdsRUN.md(the contract, from the template inCONTRACT.md),done.sh(the predicate, starting withcd <worktree>),predicate.sha(the fingerprint below), and copies oflog.mjsandAUDIT.md(cp ${CLAUDE_SKILL_DIR}/log.mjs ${CLAUDE_SKILL_DIR}/AUDIT.md <control>/). The outer loop'sloop.shgoes here too, and the user's off switch,<control>/STOP.<state>(<run>/state): what the run writes.decisions.tsvonly throughLOG append, which creates it with the header, refuses a path inside a git work tree and never rewrites a row;resume.mdandsummary.md; and the outer loop's own output.
The fingerprint freezes the predicate: git hash-object <control>/done.sh <worktree>/<each file that defines the
predicate> (after step 3 makes the worktree), saved to <control>/predicate.sha. The loop compares it before every
check and stops when it changed. (A cloud scheduled task sees only its clone: see the end of LOOP.md.)
Read ${CLAUDE_SKILL_DIR}/CONTRACT.md now: fill in its RUN.md template, then log the contract as the first row.
The run column names the conversation that wrote each row, so the audit can find its transcript. In a Claude Code
session LOG takes it from $CLAUDE_CODE_SESSION_ID: never pass --run there. Pass --run <label> only where that
is not set, and say in RUN.md which transcript the label stands for.
Step 3. A fresh worktree
From the main checkout: git worktree add <worktree> -b overnight/<label> <base>, with the worktree outside the
main checkout (a sibling folder). For the setup a new worktree needs (dependencies, environment files, ports), use
parallel-worktrees if it is installed; without it, install dependencies the way the project's README or CI does.
A session keeps the folder it started in: one started in the main checkout runs a bare pytest there, not in the
worktree. So done.sh starts with cd <worktree>, git commands use git -C <worktree>, and the outer loop starts
each turn in the worktree. Then:
- Run the test command in the worktree. It passes at the base, or fails only where failing tests are the task.
- Run the predicate. It fails, with the remaining count you expect. Write
predicate.shanow. git -C <worktree> status --shortprints nothing. Files the build or the tests write go in the shared exclude file,$(git rev-parse --git-common-dir)/info/exclude, never in a committed.gitignorechange.- Log a row:
--phase setup, the worktree and branch, the test and predicate outputs as evidence.
Step 4. Pick how the run wakes
Read ${CLAUDE_SKILL_DIR}/LOOP.md now. For the short version, the table in ${CLAUDE_SKILL_DIR}/WAKE.md says which
way to wake fits the situation, and what it needs.
/loop and session scheduled jobs live inside this Claude process: they end when it exits, and never wake a
claude -p that has exited. Never assume a tool exists; look at the tool list. Write the choice into RUN.md.
Step 5. The loop
Each iteration:
- Off switch. Check
<control>/STOPin a call of its own (ls <control>), and act on its answer before any edit: if it exists, go to step 6. Never send the check and a change in one message. - Read the state, since a wake remembers nothing:
RUN.md,LOG show <state>/decisions.tsv --last 10,git -C <worktree> log --oneline -5andgit -C <worktree> status --short. After a context summary, read them again. - Check the predicate: run
bash <control>/done.sh. Exit 0 on a clean tree: go to step 6, finished. A pass on a tree with uncommitted changes does not count. - Check the budget: iterations logged, the time, the money spent. Spent: step 6.
- Make the smallest change the evidence justifies, for one idea. Name the idea first. Never edit the files that define the predicate.
- Verify: the test command, then the predicate.
- Decide. Keep when the predicate moved (the remaining count fell, or it passes) and the tests pass; when
failing tests are the task, "the tests pass" means no test that passed before fails now. Stage
only the files you changed and commit (
git -C <worktree> add <files>,git -C <worktree> commit -m "<change>"). Otherwise revert:git -C <worktree> restore -- <files>,git -C <worktree> clean -f -- <new file>for each file it created, and check thatgit -C <worktree> status --shortprints nothing. A change that "might help" is reverted, not left to ride. - Log one row:
--phase loop, the decision (what changed, or what was tried), the reason, the evidence (the commit, orreverted, and the predicate's last line) and the result (remaining 7,reverted: tests fail in test_parse).
Rules throughout:
- A plateau is not a stop. After three reverts in a row, change the approach (read the failure again, try a different hypothesis, take a smaller step), and count each approach toward the dead end.
- Mid-run discoveries (a related bug, a flaky test, broken tooling): log a row with
--phase discovery, and list it under Attention at the end. Fix it only when it blocks the predicate, in its own commit, with its own row. - Never take a forbidden action, and never work around a refused command. Log it, and if it blocks the predicate, stop (step 6).
- Correct the log, not the story. A wrong row gets a new row with
--supersedes <id>saying what is true. Never edit or delete a row; the run has no rule that could, andLOGonly appends.
Step 6. Stop: finished, stuck, out of budget, or switched off
Every stop starts the same way: finish the current step or back it out (never leave half a change), then:
- Make the work durable. Kept work is committed. A half-done change worth keeping goes in one
wip:commit on the run branch, with one line in its body if the tree does not build. Never push. - Write
<state>/resume.md, unless the predicate passed: the goal, where the loop is, what is verified, the predicate's last line, the next step, key files and gotchas. Point at the log rows instead of copying them. - Log a row:
--phase stop,--decision "stopped: <reason>", the resume note or the last commit as evidence.
The reasons, and what each adds:
- Finished: the predicate exits 0 on a clean tree. Run the tests once more and log both outputs.
- Dead end (the escape hatch): when truly stuck, stop and write up why in
resume.md: each approach tried, what each showed, and what would unblock it. This beats hours of reinterpreting the goal. - Budget spent: say which budget, and how far the predicate got.
- Off switch: the user made
<control>/STOP. "Keep going" or "don't stop" never pauses a run; only the off switch or the user saying to pause does. - The predicate looks wrong, or the next step needs a forbidden action: stop and say so. The user decides.
To resume later, a new session reads RUN.md, resume.md and the log, logs a row under its own session id, and
continues at step 5.
Step 7. The morning audit
After every stop, before the summary: a fresh reviewer that did not see the run reads the log against the transcript. It audits the trail (did the log tell the truth), not the code. In the outer loop this is the final turn, which does no work on the task.
- Find this run's transcripts, and only those. The outer loop keeps a
--output-format stream-json --verbosecapture of each turn in<state>; use those. Otherwise Claude Code keeps each session at~/.claude/projects/<folder>/<session id>.jsonl(under$CLAUDE_CONFIG_DIR/projectswhen that is set). Find it by the session id in theruncolumn:ls ~/.claude/projects/*/<session id>.jsonl. The folder name is the folder the session started in, with every character other than a letter or a digit replaced by-(a long path is cut at 200 characters and a hash is added), so a session started in the main checkout is filed under the main checkout, not the worktree. Open only the files theruncolumn names: the other folders hold the user's other conversations. - Start the reviewer with
<control>/AUDIT.md, filled in. Use a subagent (the Agent tool) given only that prompt: it starts without this conversation and with this session's permission rules, so it reads transcripts withLOG calls, which the log rule already allows. Where there is no Agent tool, run the headless form at the top of AUDIT.md. Where neither works, audit it yourself and say so on the first line of Attention. - Check what it reports: open the rows and transcript lines it names. It appends its findings to the log with
--phase audit, a gap as a new row and a wrong row as a row that supersedes it.
To grade the result itself against the goal, offer to run evaluator if it is installed. Without it, run the
predicate and the tests in the worktree yourself and paste their last lines into the summary.
Step 8. The summary
Write <state>/summary.md and reply with the same text:
## Overnight run: <goal>
Verdict: finished | stopped: dead end | budget spent (<which>) | off switch | predicate wrong | blocked
Predicate: bash <control>/done.sh -> <last line> (fingerprint unchanged | changed; tree clean | dirty)
Iterations: <n> (kept <k>, reverted <r>) Budget used: <iterations, money, time>
Kept: <sha> <subject> (one line each)
Reverted: <count>; the ideas that did not work, in a few words each
Discoveries: <row ids>, fixed (<sha>) or left open
Branch: overnight/<label> at <sha>, not pushed Worktree: <path>
Log: <state>/decisions.tsv (<n> rows, <m> superseded) Resume note: <path or none>
### Attention
reviewed by a fresh subagent that did not see the run
- <what to look at first> (rows <ids>, or <transcript file>:<line>)The Attention section is last, and lists each flag with the rows or the transcript lines it points at. "No flags" is a valid list. If no fresh reviewer read the trail, its first line says who did instead.
Leave the branch, the worktree and the run folder in place, and do not push or open a pull request: the user
decides in the morning. If they want the trail with the change, copy the log into the repository once at the end
(cp <state>/decisions.tsv <worktree>/docs/overnight/<label>.tsv) and commit it on the run branch.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

