Skip to content

About

Ops toolkit for Claude Code power users: auto-merge session worktrees on SessionEnd + auto-resume sessions after usage-limit resets.

Topics

Resources

Stars

3 stars

Watchers

0 watching

Forks

Latest commit

 

History

2 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

cc-worktree-ops

License: MIT

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.

The problem

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.

What's inside

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.

Install / Setup

1. merge_worktree_back.py (SessionEnd hook)

  1. Copy scripts/merge_worktree_back.py into your project (e.g. into its own scripts/ directory).

  2. Add a SessionEnd hook to your project's .claude/settings.json -- start from examples/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"
              }
            ]
          }
        ]
      }
    }
  3. (Optional) Configure it via flags or environment variables:

    Flag Env var Default
    --branch-prefix CC_OPS_BRANCH_PREFIX claude/
    --target-branch CC_OPS_TARGET_BRANCH auto-detected (origin/HEAD, else local master, else main)
    --notify-cmd CC_OPS_NOTIFY_CMD none (disabled)
    --log-dir -- none (disabled)

    --notify-cmd / CC_OPS_NOTIFY_CMD is invoked best-effort as <your-command> "<message>" on notable events (merge conflicts, deferred merges, a stale checkout). It never blocks or fails the merge. See examples/notify_hook.example.py for a copy-paste starting point.

  4. Try it manually first:

    python scripts/merge_worktree_back.py /path/to/a/session/worktree
    

2. session_resume_watch.ps1 (scheduled watcher)

  1. Copy scripts/session_resume_watch.ps1 into this repo (or reference it directly from a clone of cc-worktree-ops).

  2. Have your session write a flag file when it's about to hit its usage limit, at <ProjectPath>\data\RESUME_AFTER.txt by 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.)

  3. Register a Windows Scheduled Task to run the watcher every 15-30 minutes. examples/register_resume_task.example.ps1 is 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 /Create yourself -- the example script is just a thin, readable wrapper around it.

  4. Parameters (see the script's own comment-based help, -?, for full detail):

    Parameter Default
    -ProjectPath current directory
    -ClaudeExe auto-detected (Get-Command claude, then the per-user npm global path)
    -FlagFile <ProjectPath>\data\RESUME_AFTER.txt
    -NotifyCommand none (disabled)
    -MaxSessionHours 5

How it works

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.

Safety notes

  • The merge never force-anything's. A conflict always runs git merge --abort and 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, so git reset --soft HEAD~1 undoes 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 -p in 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.example and examples/register_resume_task.example.ps1 and adjust paths, branch names, and notification commands for your own setup before trusting them with your repo.

Contributing

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.

License

MIT (c) 2026 luandv92

About

Ops toolkit for Claude Code power users: auto-merge session worktrees on SessionEnd + auto-resume sessions after usage-limit resets.

Topics

Resources

Stars

3 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages