gitflash 0.5.1 → 0.7.0.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 86ac16bd9cd3c64cd98305a6423e67c05187040d8caba798d132a4f985ee28df
-  data.tar.gz: 8da24e90611e20296f70ca3cadab5a77f697c97ff43cf535b9f51b1bd40a66be
+  metadata.gz: e8466fec203a9fdd7ac08e721fb0bb624fb8f486e68f9b369660e5d369e717ad
+  data.tar.gz: 53243a2e0dc1d5877bd5541999fec636e89ac882b9af78d84790ef32be3e12cb
 SHA512:
-  metadata.gz: c573a9265e4558a9d502840cb7b65b0c07c6e6f640c74bde499ed1b4ff160fd8aeb101a9ecd95b692a2170c812d0a6afd14d8abe8629d46b8e65732a7622384c
-  data.tar.gz: 53e55b8afcc5f32cd1b0fa238e0f7db356b4e919d57f606ebec37ee3a86539fff2dd0afaef3b5bf6f295f235e9f4452ec1b5bb3dee5dc7fd1df964cb3e6f3d85
+  metadata.gz: 27b78d4baac19b15a9f6bef731cc0ec3622ee5c51a2ee82ab9f20a63a5f50d6ecedb3c4f1651d0849eae970f5a66c20480272d0bf00b0284e8434f1893805901
+  data.tar.gz: 1c1f6e76de4e2f67fb7c1c591e9569d8578a96cad8cc9e58ff75fd9448abaa8ead4e7b96cef519d6a4a991e75299e07eaafcc8d060896b8742b9c7f4ec4b93f5

data/CHANGELOG.md

@@ -62,3 +62,28 @@ Security fixes for names and text that come from the repository:
 - Branch and default-branch detection use full ref names. A tag named like `origin/<default>` could change the short name of `origin/HEAD`, so the default branch lost its deletion protection and its merge status; `origin/HEAD` must now point inside `refs/remotes/origin/`
 - `delete` passes `--` before the branch name; `resolve_commit` refuses references that start with a dash
 - Text output shows terminal control characters of repository-controlled text (commit subjects, git errors) as escapes such as `\x1B`, so a crafted commit subject cannot move the cursor, rewrite output or set the clipboard (OSC 52). JSON output keeps the original text
+
+## [0.6.0] - 2026-10-05
+
+- Snapshots: gitflash saves branches, HEAD, tracked, staged and untracked files and stash entries before every change it makes, as git objects under `refs/gitflash/snapshots/` (the working tree is never touched; untracked files over 50 MB are skipped)
+- Add `undo [SNAPSHOT]`: restores the parts a snapshot saved (the latest by default), after saving the current state so the undo can be undone
+- Add `snapshot` (save on request, `--scope`, `--message`), `snapshots` (list) and `gc --older-than DAYS`
+- Every `done` result of `checkout`, `delete` and `reset` includes `undo` with the snapshot id; human output ends with `Undo with: gitflash undo ID`
+- Add `hook claude`: a Claude Code `PreToolUse` hook that saves a snapshot before destructive git commands an agent runs itself (`reset`, `checkout -- .`, `restore`, `clean -f`, `branch -D`, `stash drop`, `rebase`, `worktree remove --force`, ...). Modes: `snapshot` (default), `ask`, `deny`. It never blocks a command because of its own errors
+- Add `hook install [--scope local|project|user] [--mode ...]` to register the hook in Claude Code settings; it reports which sessions the file applies to, and the local scope uses the main checkout's root inside a worktree, as Claude Code does
+- Add `hook status` to show whether the hook protects Claude Code sessions in the current directory
+- JSON schema: new `undo` field, commands `undo`, `snapshots`, `snapshot`, `gc`, `hook`, error codes `unknown_snapshot`, `wrong_worktree`, `invalid_settings`
+
+## [0.7.0.beta1] - 2026-10-07
+
+Beta of the parallel agent work release. Install with `gem install gitflash --pre`. The JSON contract of the new commands may still change before 0.7.0. Needs git 2.36 or newer.
+
+- Settings: `.gitflash.yml` in the repository and `~/.config/gitflash.yml` (the repository file wins) with `protected` branch patterns, `stale_days` and `worktree_dir`. Unknown keys, wrong types, duplicate keys and unreadable files fail with the new error code `invalid_config`
+- Ownership marks: `branch.<name>.gitflash-owner` (`agent` or `human`) in git config, shown as `owner` in `branches` and `worktree list`. Add `mark [BRANCH...] [--owner agent|human] [--clear]` to set it
+- Add `worktree` (alias `wt`): `list`, `add`, `remove`, `clean`, `prune`, `lock`, `unlock` and `move`. `wt list --json` gives absolute paths, dirty state, ahead and behind, merge status, lock state and owner. `wt add` marks the branches it creates as agent work. `wt remove` and `wt clean` save a snapshot first and refuse the main checkout, the current worktree, and locked or dirty worktrees unless `--force`. `undo` adds a removed worktree back with its branch and uncommitted files. Ignored files are not saved: the plan lists them before they are deleted. A worktree with an untracked file over 50 MB is not removed
+- Add `clean`: deletes merged branches and branches whose upstream is gone, and with `--stale [DAYS]` and `--agent` stale and agent-created ones, with a snapshot first. Each chosen branch lists why. Unmerged branches need `--force`
+- `clean` and `delete` never touch the current and default branch, `main`, `master`, `protected` branches or branches checked out in a worktree
+- Add `pick SOURCE [SHA...]`: `--list` shows the commits of SOURCE that are not on the current branch (already applied patches are marked), `SHA...` applies them oldest first with `git cherry-pick -x` after a snapshot, and on a conflict it stops and lists the files. `pick --continue`, `--skip` and `--abort` wrap git's own controls
+- The Claude Code hook also runs after Bash commands (`PostToolUse`): branches created with plain git (`checkout -b`, `switch -c`, `branch NAME`, `worktree add`) are marked as agent work. `hook install` adds it, so run it again after upgrading; `hook status` reports whether marking is on. A gitflash hook under a matcher that does not cover Bash no longer counts as installed
+- JSON schema: new commands `clean`, `mark`, `pick` and `worktree ...`, error codes `invalid_config`, `unknown_worktree`, `protected_worktree` and `conflict`, the `owner` field, and `recreate_worktree` in the `undo` plan
+- Author names from other branches are shown with control characters escaped in `pick` output

data/README.md

@@ -1,6 +1,6 @@
 # GitFlash
 
-[![Gem Version](https://badge.fury.io/rb/gitflash.svg)](https://badge.fury.io/rb/gitflash)
+[![GitHub version](https://badge.fury.io/gh/Kleanthismits%2Fgit_flash.svg)](https://badge.fury.io/gh/Kleanthismits%2Fgit_flash)
 
 ⚠️ **This project is still under development**: Use at your own risk!
 
@@ -24,9 +24,11 @@ Or install it yourself as:
 
     $ gem install gitflash
 
+Prerelease versions such as `0.7.0.beta1` are only installed when you ask for them: `gem install gitflash --pre`, or `gem 'gitflash', '0.7.0.beta1'` in a Gemfile.
+
 ## Requirements
 
-This gem requires Ruby 3.3+ and git.
+This gem requires Ruby 3.3+ and git 2.36+ (the worktree commands read `git worktree list -z`).
 
 ## Usage
 
@@ -38,9 +40,73 @@ Run `gitflash` inside a git repository to get a list with the available commands
 | `gitflash checkout [BRANCH]` | Check out a branch, or pick one from a list |
 | `gitflash delete [BRANCH...]` | Delete branches, or pick them from a list. The current, default, `main` and `master` branches are protected. Unmerged branches are kept unless you pass `--force` |
 | `gitflash reset [COMMIT]` | Reset to a commit, or pick one of the latest 100. Mixed by default; `--soft` keeps changes staged, `--hard` discards them after confirmation |
+| `gitflash mark [BRANCH...]` | Mark branches as agent (default) or human work, or `--clear` the mark. Without a branch it marks the current one. Use it for branches made with plain git so `clean --agent` can find them |
+| `gitflash clean` | Delete merged branches and branches whose upstream is gone, with a snapshot first. `--stale [DAYS]` and `--agent` add stale and agent-created branches; unmerged ones are kept unless `--force`. Protected: current, default, `main`, `master`, `protected` in `.gitflash.yml`, branches checked out in a worktree |
+| `gitflash worktree` (`wt`) `list`, `add`, `remove`, `clean`, `prune`, `lock`, `unlock`, `move` | Worktrees for parallel agent work, with absolute paths in `--json` (see below) |
+| `gitflash pick SOURCE [SHA...]` | Cherry-pick commits from another branch: `--list` shows what is missing here, `--continue`, `--skip` and `--abort` handle conflicts |
+| `gitflash undo [SNAPSHOT]` | Restore a snapshot, the latest by default: deleted branches, moved branches, HEAD, uncommitted and untracked files, dropped stashes |
+| `gitflash snapshot` | Save the current state on request (`--scope`, `--message`) |
+| `gitflash snapshots` | List snapshots, newest first |
+| `gitflash gc` | Delete snapshots older than 30 days (`--older-than DAYS`) |
+| `gitflash hook install` | Protect plain git commands run by Claude Code and mark the branches it creates (see below) |
+| `gitflash hook status` | Show whether the hook protects Claude Code sessions in the current directory |
 | `gitflash schema` | Print the JSON Schema of the `--json` output |
 | `gitflash version` | Print the installed version (also `--version`, `-v`) |
 
+### Parallel agent work
+
+`gitflash wt add feature` creates a worktree (default `../<repo>.worktrees/feature`) and marks a new branch as agent work. For a branch made with plain git, run `gitflash mark` on it (no argument marks the current branch). `gitflash wt list --json` gives every worktree's absolute path, branch, dirty state, ahead/behind, merge status, lock state and owner, so an agent never has to switch directories.
+
+`gitflash wt remove` and `gitflash wt clean` save a snapshot first, and `gitflash undo` adds the worktree back with its branch and uncommitted files. Ignored files (`.env`, `node_modules`) are not saved: the plan lists them before they are deleted. A worktree with an untracked file over 50 MB is not removed.
+
+`gitflash pick other-branch --list` lists the commits missing here (a commit whose patch is already here is marked `=`). `gitflash pick other-branch SHA... --yes` applies them oldest first with `-x`. On a conflict it stops and lists the files; resolve them and run `gitflash pick --continue`, or `--skip` / `--abort`.
+
+Settings live in `.gitflash.yml` in the repository and `~/.config/gitflash.yml` (the repository file wins):
+
+```yaml
+protected: ["release/*"]   # branch patterns clean and delete never touch
+stale_days: 30             # used by --stale without a number
+worktree_dir: "../%<repo>s.worktrees/%<branch>s"
+```
+
+### Undo
+
+Before every change it makes, gitflash saves a snapshot: branches, HEAD, tracked, staged and untracked files, and stash entries. Snapshots are plain git objects under `refs/gitflash/snapshots/`; the working tree is never touched while saving. Git's own `revert` and `reflog` cover committed work; snapshots also cover what git never recorded: uncommitted and untracked files, deleted branches (git deletes their reflog) and dropped stashes.
+
+```bash
+gitflash delete old-feature --yes
+```
+
+```bash
+gitflash undo --yes
+```
+
+`gitflash undo` restores only what the snapshot saved and what differs, and saves the current state first, so an undo can itself be undone.
+
+### Protect plain git commands run by AI agents
+
+Agents often run git directly. Claude Code's own checkpoints do not cover changes made by shell commands, so a `git reset --hard` or `git clean -fd` run by an agent cannot be rewound there. Install the gitflash hook once per repository:
+
+```bash
+gitflash hook install
+```
+
+Before Claude Code runs a command that can discard work git cannot restore (`reset`, `checkout -- .`, `restore`, `clean -f`, `branch -D`, `stash drop`, `rebase`, `worktree remove --force`, ...), the hook saves a snapshot and tells the agent how to undo it. Other commands pass through; the hook adds about 0.1 s to commands that do not mention git. `--mode ask` also asks you to approve such commands, `--mode deny` blocks them.
+
+The same install adds a second hook that runs after a command: when the agent creates a branch with plain git (`git checkout -b`, `git switch -c`, `git branch NAME`, `git worktree add`), gitflash marks it as agent work, so `gitflash clean --agent` can find it. Only new, unmarked branches are marked, and `gitflash mark BRANCH --owner human` changes it. If you installed the hook with an earlier version, run `gitflash hook install` again to add it; `gitflash hook status` says whether branch marking is on.
+
+Where the hook goes, following Claude Code's own rules:
+
+| Scope | File | Applies to |
+| --- | --- | --- |
+| `local` (default) | `.claude/settings.local.json` at the repository root (the main checkout's root inside a worktree) | Sessions anywhere in the repository and its worktrees |
+| `project` | `.claude/settings.json` at the repository top level, to share with your team | Sessions started in that directory |
+| `user` | `~/.claude/settings.json` | Every session |
+
+Claude Code reloads settings files, so running sessions pick the hook up without a restart. Run `gitflash hook status` in the directory where you start Claude Code to check which files apply and whether the `gitflash` executable is found.
+
+### Scripts
+
 Without an argument, a command shows an interactive list. With arguments it runs directly, which also works in scripts.
 
 Options for every command:
@@ -76,6 +142,7 @@ With `--json`, every command prints one object in the same envelope, defined in
 
 - `status`: `done`, `planned` (`--dry-run`), `noop`, `cancelled`, `failed`, `confirmation_required` or `error`. `ok` is true for the first four.
 - `result` includes what you need to revert: the SHA of each deleted branch (`git branch NAME SHA`), the previous branch after `checkout`, the previous commit after `reset`.
+- `undo` names the snapshot saved before the change and the command that restores it (`gitflash undo ID`).
 - `error.code` is a stable identifier such as `unknown_branch`, `protected_branch` or `confirmation_required`.
 
 ```bash

data/bin/gitflash

@@ -1,6 +1,16 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
+# Fast path for the agent hook, which runs before every shell command: when the command does
+# not mention git there is nothing to do, so exit before loading the rest of gitflash.
+if ARGV.first(2) == %w[hook claude]
+  input = $stdin.read
+  exit 0 unless input.include?('git')
+
+  require 'stringio'
+  $stdin = StringIO.new(input)
+end
+
 require 'gitflash'
 require 'gitflash/cli'
 

data/command_descriptions.yml

@@ -46,3 +46,102 @@ reset:
     By default performs a mixed reset: your changes are kept as unstaged changes.
     Pass --soft to keep them staged, or --hard to discard them. A hard reset asks for
     confirmation; pass --yes to skip it, which is required without a terminal.
+
+undo:
+  short: 'Restore a snapshot (the latest by default)'
+  long: |
+    Restores the parts of the repository a snapshot saved: deleted or moved branches,
+    HEAD, tracked, staged and untracked files, and dropped stash entries. Only parts that
+    differ are changed; branches and files created after the snapshot are left alone.
+
+    gitflash saves a snapshot before every change it makes, and the agent hook saves one
+    before destructive git commands. List them with `gitflash snapshots`.
+
+    The current state is saved as a new snapshot first, so an undo can itself be undone.
+    Asks for confirmation; pass --yes to skip it (required without a terminal) or
+    --dry-run to only show the plan.
+
+snapshot:
+  short: 'Save the current state so it can be restored with gitflash undo'
+  long: |
+    Saves branches, HEAD, tracked, staged and untracked files (not ignored ones) and stash
+    entries as git objects under refs/gitflash/snapshots/. The working tree is not changed.
+    Untracked files larger than 50 MB are skipped and listed.
+
+    Use --scope to save only some parts, for example --scope worktree.
+
+clean:
+  short: 'Delete merged, gone, stale or agent-created branches'
+  long: |
+    Deletes branches that are no longer needed, with a snapshot first so `gitflash undo`
+    brings them back.
+
+    Without options it selects branches merged into the default branch and branches whose
+    upstream was deleted. Add criteria to select more (a branch is chosen when it matches any):
+      --merged       merged into the default branch
+      --gone         upstream branch was deleted on the remote
+      --stale [DAYS] no commits for DAYS days (default: `stale_days` setting, 30)
+      --agent        created by an agent (marked by `gitflash wt add`)
+
+    Never selected: the current and default branch, main, master, `protected` branches from
+    .gitflash.yml, and branches checked out in any worktree. Unmerged branches are kept unless
+    --force is given. Every chosen branch lists why it was chosen.
+
+    Asks for confirmation; pass --yes to skip it (required without a terminal), or --dry-run.
+
+worktree_remove:
+  long: |
+    Removes the given worktrees, given as a path or the branch checked out in them. Without
+    arguments, shows a menu in a terminal. The main checkout and the current worktree are
+    never removed; locked worktrees and worktrees with uncommitted changes are refused
+    unless --force is given.
+
+    Each removal saves a snapshot first, including uncommitted and untracked files. Ignored
+    files (build output, dependencies, .env) are not saved: the plan and the confirmation list
+    them, since removal deletes them for good. A worktree with an untracked file over 50 MB
+    is not removed, because the snapshot cannot hold it. `gitflash undo ID` brings the
+    directory, its branch and the saved files back.
+
+    Asks for confirmation; pass --yes to skip it (required without a terminal), or --dry-run.
+    Accepts the global options after the subcommand: gitflash wt remove feature --yes --json
+
+pick:
+  short: 'Cherry-pick commits from another branch'
+  long: |
+    Moves fixes between branches, for example between agent branches.
+
+    `gitflash pick SOURCE --list` lists the commits of SOURCE that are not on the current branch
+    yet, oldest first, with SHA, subject, author, date and a diff summary. A commit whose change
+    is already here (the same patch under another SHA) is marked `=` (`applied` in JSON) and is
+    never picked. Merge commits are left out.
+
+    `gitflash pick SOURCE SHA...` applies the given commits, oldest first whatever the order
+    given, with `git cherry-pick -x` (the message records the origin). Without SHAs, a menu in a
+    terminal lets you choose. Add --no-commit to only stage the combined changes.
+
+    A snapshot is saved first and the plan asks for confirmation (pass --yes, required without a
+    terminal, or --dry-run). `gitflash undo` returns to the starting point.
+
+    On a conflict the pick stops and the result lists the conflicted files, the commits already
+    applied and the ones still waiting. Resolve the files and stage them, then run
+    `gitflash pick --continue`. `gitflash pick --skip` drops the commit that conflicts and
+    `gitflash pick --abort` returns to the state before the pick (both ask for confirmation and
+    save a snapshot first).
+
+    For agents: `gitflash pick SOURCE --list --json` and
+    `gitflash pick SOURCE SHA... --yes --json`.
+
+mark:
+  short: 'Mark branches as agent or human work'
+  long: |
+    Records who created a branch, so `gitflash clean --agent` only touches branches an agent
+    created. The mark is the git config key `branch.<name>.gitflash-owner` and disappears with
+    the branch.
+
+    Without BRANCH the current branch is marked. The owner is `agent` unless --owner human is
+    given; --clear removes the mark. A branch without a mark counts as human work.
+
+    `gitflash wt add` marks the branches it creates. Use `gitflash mark` for branches made with
+    plain git, for example at the start of an agent session: `gitflash mark`.
+
+    Needs no confirmation. Pass --dry-run to see what would change, --json for the result.

data/lib/gitflash/branch.rb

@@ -6,10 +6,15 @@ module Gitflash
   # A local branch as reported by `git for-each-ref`
   Branch = Data.define(
     :name, :sha, :current, :default, :upstream, :upstream_gone, :ahead, :behind,
-    :merged, :last_commit_at, :last_commit_author, :last_commit_subject
+    :merged, :last_commit_at, :last_commit_author, :last_commit_subject, :owner
   ) do
+    # Records are built without an owner; Ownership#annotate adds it
+    def initialize(owner: nil, **fields)
+      super
+    end
+
     # Parses one line produced with Repo::BRANCH_FORMAT.
-    # `merged_names` is nil when merge status is unknown.
+    # `merged_names` is nil when merge status is unknown. `owner` is set by the caller.
     def self.parse(line, default_branch: nil, merged_names: nil)
       name, sha, head, upstream, track, date, author, subject = fields(line)
 
@@ -29,6 +34,12 @@ module Gitflash
       )
     end
 
+    # { branch name => sha } from `git for-each-ref --format=TIPS_FORMAT refs/heads/`
+    def self.parse_tips(output)
+      output.to_s.each_line(chomp: true).to_h { |line| line.split(' ', 2) }
+            .transform_keys { |ref| ref.delete_prefix(Repo::HEADS) }
+    end
+
     # The record's fields; the full ref name is shortened by removing refs/heads/ only, because
     # `refname:short` gives another name when a tag has the same name.
     def self.fields(line)
@@ -50,4 +61,5 @@ module Gitflash
       super.merge(last_commit_at: last_commit_at.iso8601)
     end
   end
+  Branch::TIPS_FORMAT = '%(refname) %(objectname)'
 end

data/lib/gitflash/cherry_pick.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Gitflash
+  # Cherry-picking between branches: finds the commits of a source branch whose change is not on
+  # the current branch yet, applies them oldest first, and wraps git's own sequence controls.
+  # All git access for `gitflash pick` is here; it never prompts or prints.
+  class CherryPick
+    # `applied` is true when an equivalent change is already on the current branch
+    Candidate = Data.define(:sha, :subject, :author, :date, :applied, :files, :insertions,
+                            :deletions) do
+      def short_sha = sha[0, 7]
+
+      def to_h
+        super.merge(short_sha: short_sha, status: applied ? 'applied' : 'new')
+             .except(:applied)
+      end
+    end
+
+    # The state of an unfinished pick: files with conflicts and the commits still to apply
+    Progress = Data.define(:conflicted, :remaining, :current)
+
+    RECORD = "\x1e"
+    SEPARATOR = "\x1f"
+    FORMAT = ['%m', '%H', '%s', '%an', '%cI'].join(SEPARATOR)
+    ENV_NO_EDITOR = { 'GIT_EDITOR' => 'true', 'GIT_SEQUENCE_EDITOR' => 'true' }.freeze
+
+    def initialize(bash: Git::BashCommand)
+      @bash = bash
+    end
+
+    # The full ref of a local (or remote-tracking) branch, nil when there is none
+    def source_ref(name)
+      return nil if name.to_s.empty? || name.start_with?('-')
+
+      ["#{Repo::HEADS}#{name}", "refs/remotes/#{name}"].find { |ref| ref?(ref) }
+    end
+
+    # Commits of `source_ref` that are not merges, oldest first, each marked as applied when an
+    # equivalent change (same patch) is already on HEAD
+    def candidates(source_ref)
+      output = @bash.exec('git', 'log', '--left-right', '--cherry-mark', '--right-only',
+                          '--no-merges', '--reverse', '--shortstat', "--format=#{RECORD}#{FORMAT}",
+                          "HEAD...#{source_ref}", '--')
+      output.split(RECORD).reject { |record| record.strip.empty? }.map { |record| parse(record) }
+    end
+
+    # Applies the commits (full shas, in the given order) with `git cherry-pick`.
+    # `record_origin` adds "(cherry picked from ...)" to each message; `commit: false` only stages.
+    def apply(shas, record_origin: true, commit: true)
+      args = ['cherry-pick']
+      args << '-x' if record_origin
+      args << '--no-commit' unless commit
+      run(*args, *shas)
+    end
+
+    def continue = run('cherry-pick', '--continue')
+
+    def abort = run('cherry-pick', '--abort')
+
+    def skip = run('cherry-pick', '--skip')
+
+    # True while a cherry-pick waits for the user (conflicts or a stopped sequence)
+    def in_progress?
+      ref?('CHERRY_PICK_HEAD') || File.exist?(todo_path)
+    end
+
+    def progress
+      Progress.new(conflicted: conflicted_files, remaining: remaining, current: current)
+    end
+
+    private
+
+    def parse(record)
+      line, *rest = record.split("\n", 2)
+      mark, sha, subject, author, date = line.split(SEPARATOR, 5)
+      files, insertions, deletions = stat(rest.first.to_s)
+      Candidate.new(sha: sha, subject: subject.to_s, author: author, date: date,
+                    applied: mark == '=', files: files, insertions: insertions,
+                    deletions: deletions)
+    end
+
+    def stat(text)
+      [text[/(\d+) files? changed/, 1], text[/(\d+) insertions?\(\+\)/, 1],
+       text[/(\d+) deletions?\(-\)/, 1]].map(&:to_i)
+    end
+
+    def conflicted_files
+      stdout, _stderr, success = @bash.capture('git', 'diff', '--name-only', '--diff-filter=U',
+                                               '-z')
+      success ? stdout.split("\0") : []
+    end
+
+    # Commits still to apply after the one that stopped, as full shas
+    def remaining
+      return [] unless File.exist?(todo_path)
+
+      shas = File.readlines(todo_path, chomp: true).filter_map { |line| line[/\Apick (\h+)/, 1] }
+      shas.filter_map { |sha| full_sha(sha) }.reject { |sha| sha == current }
+    end
+
+    def current
+      full_sha('CHERRY_PICK_HEAD')
+    end
+
+    def full_sha(ref)
+      stdout, _stderr, success = @bash.capture('git', 'rev-parse', '--verify', '--quiet',
+                                               "#{ref}^{commit}")
+      success ? stdout.strip : nil
+    end
+
+    def ref?(ref)
+      _stdout, _stderr, success = @bash.capture('git', 'rev-parse', '--verify', '--quiet', ref)
+      success
+    end
+
+    def todo_path
+      stdout, _stderr, success = @bash.capture('git', 'rev-parse', '--path-format=absolute',
+                                               '--git-path', 'sequencer/todo')
+      success ? stdout.strip : ''
+    end
+
+    def run(*)
+      stdout, stderr, success = @bash.capture('git', *, env: ENV_NO_EDITOR)
+      Result.new(success: success,
+                 output: [stdout, stderr].map(&:strip).reject(&:empty?).join("\n"))
+    end
+  end
+end

data/lib/gitflash/cleanup.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Gitflash
+  # Decides what `clean` and `wt clean` would remove. Pure: it reads records and settings, runs
+  # no git command, so every rule can be tested without a repository.
+  module Cleanup
+    CRITERIA = %i[merged gone stale agent].freeze
+    DEFAULT_CRITERIA = %i[merged gone].freeze
+
+    # A record chosen for removal and why. `item` is a Branch or a Worktree.
+    Candidate = Data.define(:item, :reasons)
+
+    # Which criteria are active. `stale_days` applies to :stale.
+    Rules = Data.define(:criteria, :stale_days, :now) do
+      def reasons(branch)
+        criteria.filter_map { |criterion| label(criterion) if match?(criterion, branch) }
+      end
+
+      private
+
+      def match?(criterion, branch)
+        case criterion
+        when :merged then branch.merged && !branch.default?
+        when :gone then branch.upstream_gone?
+        when :stale then branch.stale?(stale_days, now: now)
+        when :agent then branch.owner == 'agent'
+        end
+      end
+
+      def label(criterion)
+        { merged: 'merged', gone: 'upstream gone', agent: 'agent-created',
+          stale: "no commits for #{stale_days} days" }.fetch(criterion)
+      end
+    end
+
+    module_function
+
+    # Branches that match at least one criterion and are not protected, each with its reasons
+    def branches(branches, rules:, protection:)
+      branches.reject { |branch| protection.protected?(branch) }.filter_map do |branch|
+        reasons = rules.reasons(branch)
+        Candidate.new(item: branch, reasons: reasons) if reasons.any?
+      end
+    end
+
+    # Worktrees whose unprotected branch matches, as [chosen, skipped]. `blocker` is called with
+    # a worktree and returns why it may not be removed, or nil. A blocked match is skipped with
+    # that reason instead of being chosen.
+    def worktrees(worktrees, branches:, rules:, protection:, blocker:)
+      matched = matching(worktrees, branches, rules, protection)
+      chosen, skipped = matched.partition { |candidate| blocker.call(candidate.item).nil? }
+      [chosen, skipped.map { |candidate| skip(candidate.item, blocker.call(candidate.item)) }]
+    end
+
+    def matching(worktrees, branches, rules, protection)
+      by_name = branches.to_h { |branch| [branch.name, branch] }
+      worktrees.filter_map do |worktree|
+        branch = by_name[worktree.branch]
+        next if branch.nil? || protection.protected?(branch)
+
+        reasons = rules.reasons(branch)
+        Candidate.new(item: worktree, reasons: reasons) if reasons.any?
+      end
+    end
+
+    def skip(worktree, reason)
+      { path: worktree.path, branch: worktree.branch, reason: reason }
+    end
+  end
+end

data/lib/gitflash/cli.rb

@@ -5,6 +5,7 @@ require 'thor'
 module Gitflash
   class Cli < Thor
     extend Configuration::Descriptions
+    include CommandRunner
 
     SCHEMA_PATH = File.expand_path('../../schema/v1.json', __dir__)
 
@@ -25,13 +26,13 @@ module Gitflash
     option :gone, type: :boolean, desc: 'Branches whose upstream branch was deleted'
     option :stale, type: :numeric, banner: 'DAYS', desc: 'Branches without commits for DAYS days'
     def branches
-      run_command(Commands::Branches)
+      run_command('branches', Commands::Branches)
     end
 
     desc 'checkout [BRANCH]', descriptions.checkout.short
     long_desc descriptions.checkout.long
     def checkout(branch = nil)
-      run_command(Commands::Checkout, *[branch].compact)
+      run_command('checkout', Commands::Checkout, *[branch].compact)
     end
 
     desc 'delete [BRANCH...]', descriptions.delete.short
@@ -39,7 +40,28 @@ module Gitflash
     option :force, type: :boolean, default: false,
                    desc: 'Delete branches even if they have unmerged changes'
     def delete(*branches)
-      run_command(Commands::Delete, *branches)
+      run_command('delete', Commands::Delete, *branches)
+    end
+
+    desc 'mark [BRANCH...]', descriptions.mark.short
+    long_desc descriptions.mark.long
+    option :owner, type: :string, enum: Ownership::OWNERS, desc: 'agent (default) or human'
+    option :clear, type: :boolean, default: false, desc: 'Remove the mark'
+    def mark(*branches)
+      run_command('mark', Commands::Mark, *branches)
+    end
+
+    desc 'clean', descriptions.clean.short
+    long_desc descriptions.clean.long
+    option :merged, type: :boolean, desc: 'Branches merged into the default branch'
+    option :gone, type: :boolean, desc: 'Branches whose upstream branch was deleted'
+    option :stale, type: :string, banner: 'DAYS', lazy_default: '',
+                   desc: 'Branches without commits for DAYS days (default: stale_days setting)'
+    option :agent, type: :boolean, desc: 'Branches created by an agent'
+    option :force, type: :boolean, default: false,
+                   desc: 'Also delete selected branches that have unmerged changes'
+    def clean
+      run_command('clean', Commands::Clean)
     end
 
     desc 'reset [COMMIT]', descriptions.reset.short
@@ -47,9 +69,55 @@ module Gitflash
     option :hard, type: :boolean, default: false, desc: 'Discard all current changes'
     option :soft, type: :boolean, default: false, desc: 'Keep changes staged'
     def reset(commit = nil)
-      run_command(Commands::Reset, *[commit].compact)
+      run_command('reset', Commands::Reset, *[commit].compact)
+    end
+
+    desc 'undo [SNAPSHOT]', descriptions.undo.short
+    long_desc descriptions.undo.long
+    def undo(snapshot = nil)
+      run_command('undo', Commands::Undo, *[snapshot].compact)
     end
 
+    desc 'snapshots', 'List snapshots, newest first'
+    def snapshots
+      run_command('snapshots', Commands::SnapshotList)
+    end
+
+    desc 'snapshot', descriptions.snapshot.short
+    long_desc descriptions.snapshot.long
+    option :message, type: :string, desc: 'Why the snapshot was taken'
+    option :scope, type: :array, banner: 'PARTS',
+                   desc: 'Parts to save: branches head worktree stashes (default: all)'
+    def snapshot
+      run_command('snapshot', Commands::SnapshotCreate)
+    end
+
+    desc 'gc', 'Delete old snapshots'
+    option :older_than, type: :numeric, banner: 'DAYS',
+                        desc: 'Delete snapshots older than DAYS days (default 30)'
+    def gc
+      run_command('gc', Commands::Gc)
+    end
+
+    desc 'hook SUBCOMMAND', 'Agent hooks: claude (run the hook), install (register it)'
+    subcommand 'hook', HookCli
+
+    desc 'pick [SOURCE] [SHA...]', descriptions.pick.short
+    long_desc descriptions.pick.long
+    option :list, type: :boolean, desc: 'List the commits of SOURCE that are not on this branch yet'
+    option :commit, type: :boolean, default: true,
+                    desc: 'Create a commit per pick; --no-commit only stages the changes'
+    option :continue, type: :boolean, desc: 'Continue after resolving conflicts'
+    option :skip, type: :boolean, desc: 'Skip the commit that conflicts'
+    option :abort, type: :boolean, desc: 'Give up and return to the state before the pick'
+    def pick(source = nil, *shas)
+      run_command('pick', Commands::Pick.command_for(options), *[source, *shas].compact)
+    end
+
+    desc 'worktree SUBCOMMAND', 'Worktrees for parallel agent work (alias: wt)'
+    subcommand 'worktree', WorktreeCli
+    map 'wt' => :worktree
+
     desc 'schema', 'Print the JSON Schema of the --json output'
     def schema
       puts File.read(SCHEMA_PATH)
@@ -61,22 +129,5 @@ module Gitflash
     def version
       puts VERSION
     end
-
-    private
-
-    def run_command(command_class, *)
-      ui = build_ui(command_class.name.split('::').last.downcase)
-      repo = Repo.new
-      repo.ensure_work_tree!
-      status = command_class.new(repo: repo, ui: ui, options: options).call(*)
-      exit(status) unless status.zero?
-    rescue Error => e
-      ui.error(e)
-      exit(e.exit_code)
-    end
-
-    def build_ui(command)
-      Ui.new(command: command, json: options[:json], yes: options[:yes], dry_run: options[:dry_run])
-    end
   end
 end

data/lib/gitflash/command_runner.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Gitflash
+  # Runs a command class with the parsed Thor options and turns errors into output and exit codes
+  module CommandRunner
+    private
+
+    def run_command(name, command_class, *, repo_required: true)
+      ui = build_ui(name)
+      repo = Repo.new
+      repo.ensure_work_tree! if repo_required
+      status = command_class.new(repo: repo, ui: ui, options: options).call(*)
+      exit(status) unless status.zero?
+    rescue Error => e
+      ui.error(e)
+      exit(e.exit_code)
+    end
+
+    def build_ui(name)
+      Ui.new(command: name, json: options[:json], yes: options[:yes], dry_run: options[:dry_run])
+    end
+  end
+end