Ops toolkit for Claude Code power users: auto-merge session worktrees back to
your main branch on SessionEnd, and auto-resume interrupted sessions after
usage-limit resets.
If you run Claude Code sessions in isolated git worktrees, two things go wrong on their own:
- Worktrees pile up unmerged. Each session's work sits on its own branch until someone manually commits and merges it back. Do this across a dozen sessions a day and you either remember every time, or you don't, and work quietly rots on stale branches.
- Long sessions hit the usage limit and just... stop. Claude subscriptions reset on a rolling window. When a session gets cut off mid-task, nothing brings it back -- you have to notice, come back, and manually resume it.
Both are automatable. This repo is the two scripts that automate them, generalized out of a real day-to-day setup so you can drop them into yours.
| Tool | Runs | Does |
|---|---|---|
scripts/merge_worktree_back.py |
Once, at session end (SessionEnd hook) |
Commits any loose changes in the session worktree, then merges its branch into your target branch. Aborts safely on conflict -- never leaves a half-merged state, never pushes. |
scripts/session_resume_watch.ps1 |
On a recurring schedule (e.g. every 30 min via Task Scheduler) | Checks a flag file for a usage-limit reset time; once it's passed, relaunches claude -c -p <prompt> to continue the interrupted session, one-shot (never double-fires). |
Both are standalone -- use either one without the other.
-
Copy
scripts/merge_worktree_back.pyinto your project (e.g. into its ownscripts/directory). -
Add a
SessionEndhook to your project's.claude/settings.json-- start fromexamples/settings.json.example:{ "hooks": { "SessionEnd": [ { "hooks": [ { "type": "command", "command": "PP=\"${CLAUDE_PROJECT_DIR:-$(pwd)}\"; python \"$PP/scripts/merge_worktree_back.py\" \"$PP\"", "timeout": 120, "statusMessage": "auto-merge session worktree -> target branch" } ] } ] } } -
(Optional) Configure it via flags or environment variables:
Flag Env var Default --branch-prefixCC_OPS_BRANCH_PREFIXclaude/--target-branchCC_OPS_TARGET_BRANCHauto-detected ( origin/HEAD, else localmaster, elsemain)--notify-cmdCC_OPS_NOTIFY_CMDnone (disabled) --log-dir-- none (disabled) --notify-cmd/CC_OPS_NOTIFY_CMDis invoked best-effort as<your-command> "<message>"on notable events (merge conflicts, deferred merges, a stale checkout). It never blocks or fails the merge. Seeexamples/notify_hook.example.pyfor a copy-paste starting point. -
Try it manually first:
python scripts/merge_worktree_back.py /path/to/a/session/worktree
-
Copy
scripts/session_resume_watch.ps1into this repo (or reference it directly from a clone ofcc-worktree-ops). -
Have your session write a flag file when it's about to hit its usage limit, at
<ProjectPath>\data\RESUME_AFTER.txtby default:2026-07-15T20:00:00|Resume from the last checkpoint and continue pending tasks.(
<ISO-8601 reset timestamp>|<resume prompt>-- the prompt half is optional; a generic default is used if omitted.) -
Register a Windows Scheduled Task to run the watcher every 15-30 minutes.
examples/register_resume_task.example.ps1is a copy-paste starting point:powershell -File examples\register_resume_task.example.ps1 ` -ProjectPath 'C:\code\my-repo' ` -RepoRoot 'C:\code\cc-worktree-ops' ` -NotifyCommand 'python C:\code\my-repo\scripts\notify_hook.example.py'
Or run
schtasks /Createyourself -- the example script is just a thin, readable wrapper around it. -
Parameters (see the script's own comment-based help,
-?, for full detail):Parameter Default -ProjectPathcurrent directory -ClaudeExeauto-detected ( Get-Command claude, then the per-user npm global path)-FlagFile<ProjectPath>\data\RESUME_AFTER.txt-NotifyCommandnone (disabled) -MaxSessionHours5
Short version: the merge script commits and merges with a safe-abort
guarantee on conflict, serialized by a self-healing lockfile; the watcher
polls a flag file and one-shot-consumes it before relaunching claude -c -p.
For the full flow -- including the sparse-checkout trick that keeps the
merge fast on large repos, and the resume watcher's state machine -- see
docs/how-it-works.md.
- The merge never force-anything's. A conflict always runs
git merge --abortand leaves your target branch exactly as it was. The session's work stays safely committed on its own branch for you to resolve by hand. - The merge never pushes. It's local-only, by design -- push on your own schedule, with your own review.
- It may commit loose changes on the target branch. If the target branch
is checked out and the merge is blocked by uncommitted local changes, the
script commits everything in the working tree once
(
chore: snapshot target branch before merge (...)) and retries. Those changes don't have to be session-related -- unrelated manual edits sitting in your working tree get swept into that snapshot commit. Nothing is lost and nothing is pushed, sogit reset --soft HEAD~1undoes it, but if you habitually keep work-in-progress uncommitted on your main branch, know this before you wire the hook up. - The watcher only runs
claude -c -pin the directory you configured (-ProjectPath), and only after the reset time in the flag file has passed. It never touches any other project. - Review before you wire either one up. Both scripts print/log what they
did; read
examples/settings.json.exampleandexamples/register_resume_task.example.ps1and adjust paths, branch names, and notification commands for your own setup before trusting them with your repo.
Issues and PRs welcome. If you're changing merge_worktree_back.py, run the
test suite first:
python -m pytest tests/ -v
The tests build real, throwaway git repos under tmp_path -- no network
access, no fixtures shared across runs.
MIT (c) 2026 luandv92