gitflash 0.6.0 → 0.7.0.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5a9dbc4a8ff348766f4e0a7911d451f372a4ab4b355e55d9f260d453a668948f
-  data.tar.gz: 687787d41cf614c244512ac27a105bc34cf1d75a169d6eec14f56c80a3ab1c88
+  metadata.gz: e8466fec203a9fdd7ac08e721fb0bb624fb8f486e68f9b369660e5d369e717ad
+  data.tar.gz: 53243a2e0dc1d5877bd5541999fec636e89ac882b9af78d84790ef32be3e12cb
 SHA512:
-  metadata.gz: d7f50c47a77e7efe0410f287dfe6c7a447187300c3974512aeb17a52806bc4e139148a45f9499118cc6286c7a636f4209f476eea8e3e0eb23cb13a5c75eac3a0
-  data.tar.gz: 271acb28eabeb2ffa6efb6e9bc9449d90dc02ab650c8d57f8f54b1330bc164f921f7bd18b9ebdc7db0094e07347e05a631708f42c4e9eff4b09d73607bf3d09f
+  metadata.gz: 27b78d4baac19b15a9f6bef731cc0ec3622ee5c51a2ee82ab9f20a63a5f50d6ecedb3c4f1651d0849eae970f5a66c20480272d0bf00b0284e8434f1893805901
+  data.tar.gz: 1c1f6e76de4e2f67fb7c1c591e9569d8578a96cad8cc9e58ff75fd9448abaa8ead4e7b96cef519d6a4a991e75299e07eaafcc8d060896b8742b9c7f4ec4b93f5

data/CHANGELOG.md

@@ -73,3 +73,17 @@ Security fixes for names and text that come from the repository:
 - 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

@@ -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,15 +40,35 @@ 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 (see below) |
+| `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.
@@ -71,6 +93,8 @@ 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 |

data/command_descriptions.yml

@@ -69,3 +69,79 @@ snapshot:
     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)
 

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

@@ -43,6 +43,27 @@ module Gitflash
       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
     long_desc descriptions.reset.long
     option :hard, type: :boolean, default: false, desc: 'Discard all current changes'
@@ -81,6 +102,22 @@ module Gitflash
     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)

data/lib/gitflash/commands/base.rb

@@ -26,13 +26,19 @@ module Gitflash
         raise Error.new("git #{command} failed:\n#{result.output}", code: 'git_failed')
       end
 
+      def config
+        @config ||= Gitflash::Config.load(root: repo.main_root)
+      end
+
       def snapshots
         @snapshots ||= Gitflash::Snapshots.new
       end
 
-      # Saves the state a change is about to modify, so `gitflash undo` can restore it
-      def take_snapshot(reason, scope:, branches: nil)
-        snapshots.create(reason: reason, scope: scope, branches: branches)
+      # Saves the state a change is about to modify, so `gitflash undo` can restore it.
+      # `dir` saves the HEAD and files of another worktree instead of the current one.
+      def take_snapshot(reason, scope:, branches: nil, dir: nil)
+        store = dir ? Gitflash::Snapshots.new(bash: Git::InDirectory.new(dir)) : snapshots
+        store.create(reason: reason, scope: scope, branches: branches)
       end
 
       def planned(plan, text)

data/lib/gitflash/commands/branches.rb

@@ -52,6 +52,7 @@ module Gitflash
           'default' => branch.default?,
           'merged' => branch.merged && !branch.default?,
           'gone' => branch.upstream_gone?,
+          'agent' => branch.owner == 'agent',
           "ahead #{branch.ahead}" => branch.ahead.positive?,
           "behind #{branch.behind}" => branch.behind.positive?
         }.select { |_label, shown| shown }.keys.join(', ')

data/lib/gitflash/commands/clean.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Gitflash
+  module Commands
+    # Deletes the branches that are no longer needed: merged ones and ones whose upstream is
+    # gone by default, plus stale or agent-created ones when asked. Protected branches and
+    # branches checked out in a worktree are never selected. Unmerged branches are kept unless
+    # --force is given. Plan, confirmation, snapshot and result work as in `delete`; each chosen
+    # branch carries the reasons it was chosen.
+    class Clean < Delete
+      include CleanCriteria
+
+      def call
+        branches = repo.branches(merged_status: true)
+        select(branches)
+        return nothing_to_clean if @reasons.empty?
+
+        delete(@reasons.keys, branches.to_h { |branch| [branch.name, branch.sha] })
+      end
+
+      private
+
+      # Sets @reasons (chosen branch => why) and @skipped (matches kept for being unmerged)
+      def select(branches)
+        candidates = Cleanup.branches(branches, rules: rules, protection: protection)
+        chosen, kept = candidates.partition { |candidate| force? || candidate.item.merged }
+        @reasons = chosen.to_h { |candidate| [candidate.item.name, candidate.reasons] }
+        @skipped = kept.map { |candidate| skipped_row(candidate) }
+      end
+
+      def build_plan(names)
+        super.merge(reasons: @reasons.slice(*names), skipped: @skipped)
+      end
+
+      def skipped_row(candidate)
+        { branch: candidate.item.name, reason: 'has unmerged changes (use --force)' }
+      end
+
+      def nothing_to_clean
+        plan = { branches: [], force: force?, reasons: {}, skipped: @skipped }
+        ui.report(status: 'noop', plan: plan, result: { deleted: [], failed: [] },
+                  text: @skipped.empty? ? 'Nothing to clean' : skipped_text)
+      end
+
+      def skipped_text
+        lines = @skipped.map { |row| "Kept #{row[:branch]}: #{row[:reason]}" }
+        (['Nothing to clean.'] + lines).join("\n")
+      end
+    end
+  end
+end

data/lib/gitflash/commands/clean_criteria.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Gitflash
+  module Commands
+    # The selection options shared by `clean` and `wt clean`: --merged, --gone, --stale [DAYS]
+    # and --agent. Without any of them merged and gone branches are selected.
+    module CleanCriteria
+      FLAGS = %i[merged gone stale agent].freeze
+
+      private
+
+      def rules
+        given = FLAGS.select { |flag| options[flag] }
+        Cleanup::Rules.new(criteria: given.empty? ? Cleanup::DEFAULT_CRITERIA : given,
+                           stale_days: stale_days, now: Time.now)
+      end
+
+      def stale_days
+        value = options[:stale]
+        return config.stale_days if value.nil? || value.to_s.empty?
+
+        days = Integer(value, exception: false)
+        return days if days&.positive?
+
+        usage_error!('invalid_options', "--stale needs a positive number of days, got '#{value}'")
+      end
+    end
+  end
+end

data/lib/gitflash/commands/delete.rb

@@ -6,8 +6,6 @@ module Gitflash
     # Uses `git branch -d` (merged branches only) unless --force is given.
     # The result lists each deleted branch with its last commit, so it can be recreated.
     class Delete < Base
-      PROTECTED_NAMES = %w[main master].freeze
-
       def call(*names)
         branches = repo.branches
         candidates = branches.reject { |branch| protected?(branch) }.map(&:name)
@@ -34,8 +32,16 @@ module Gitflash
         options[:force] ? true : false
       end
 
+      def protection
+        @protection ||= Protection.new(config: config, checked_out: checked_out)
+      end
+
+      def checked_out
+        Worktrees.new(repo: repo).list.filter_map(&:branch)
+      end
+
       def protected?(branch)
-        branch.current? || branch.default? || PROTECTED_NAMES.include?(branch.name)
+        protection.protected?(branch)
       end
 
       def validate!(names, branches)
@@ -48,11 +54,12 @@ module Gitflash
 
         usage_error!('protected_branch',
                      "Refusing to delete protected branches: #{refused.join(', ')} " \
-                     '(current, default, main and master are protected)')
+                     '(current, default, main, master, `protected` in .gitflash.yml, ' \
+                     'checked out in a worktree)')
       end
 
       def delete(names, shas)
-        plan = { branches: names, force: force? }
+        plan = build_plan(names)
         return planned(plan, "Would delete:\n#{bullets(names)}") if ui.dry_run?
         return cancelled(plan) unless ui.confirm?(summary(names), plan: plan)
 
@@ -62,6 +69,11 @@ module Gitflash
         report_results(plan, outcomes, shas, snapshot)
       end
 
+      # The plan reported and returned in JSON; `clean` adds why each branch was chosen
+      def build_plan(names)
+        { branches: names, force: force? }
+      end
+
       def summary(names)
         mode = force? ? 'even if they have unmerged changes' : 'if they are fully merged'
         "You are about to delete the following branches #{mode}:\n\n#{bullets(names)}"