gitflash 0.6.0 → 0.7.0.beta2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5a9dbc4a8ff348766f4e0a7911d451f372a4ab4b355e55d9f260d453a668948f
-  data.tar.gz: 687787d41cf614c244512ac27a105bc34cf1d75a169d6eec14f56c80a3ab1c88
+  metadata.gz: d5d05aaa23c964d36999d266023460edddaaaf9b6298e02143de593b583d79f9
+  data.tar.gz: 5112665666f18a4a91a025765a33f3b5591a4d02adad72c1512624c66d245586
 SHA512:
-  metadata.gz: d7f50c47a77e7efe0410f287dfe6c7a447187300c3974512aeb17a52806bc4e139148a45f9499118cc6286c7a636f4209f476eea8e3e0eb23cb13a5c75eac3a0
-  data.tar.gz: 271acb28eabeb2ffa6efb6e9bc9449d90dc02ab650c8d57f8f54b1330bc164f921f7bd18b9ebdc7db0094e07347e05a631708f42c4e9eff4b09d73607bf3d09f
+  metadata.gz: ec5b291e0e0d4c1ed23c540356c9c5c6c2f1c65e5c1494e0afc38d7187ae0e05861e4c524fecb37552105e12d6182387b67e615afc8fe2a716538c235b039484
+  data.tar.gz: f34102849614fc40763142de8a3c85c0c59fdbadd2534306e7f6c8da507fa0c4f0851c6c3ec6aa1a96a7931b56e8407691c7a48ff54d10455abff6019f526f42

data/CHANGELOG.md

@@ -73,3 +73,39 @@ 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
+
+## [0.7.0.beta2] - 2026-10-08
+
+Second beta of the parallel agent work release: the `pick` branch list, a quieter `hook claude` and a round of security fixes on top of beta1. Install with `gem install gitflash --pre`. If you installed the hook before, run `gitflash hook install` again. Needs git 2.36 or newer.
+
+- `pick` without a source branch shows a list of the other local branches in a terminal, as `checkout` does; without a terminal the source is still required
+- `hook claude` is no longer listed in `gitflash hook` help (it is run by Claude Code, not by hand; `gitflash hook help claude` still describes it) and prints a short note instead of waiting for input when run in a terminal. The `hook` line in `gitflash help` now says it installs and checks the Claude Code hooks
+- Security hardening, from a CodeRabbit scan of the repository:
+  - Snapshots save untracked files whose names look like Git pathspec magic (`:(exclude)*`) or start or end with a space; before, such a name could drop other files from the snapshot. `Repo#toplevel` and the git readers keep whitespace at the end of a path
+  - Confirmation prompts show control characters in paths as escapes, as other output does
+  - `protected` branch patterns of the user file and the repository file add up; a repository can protect more branches but can no longer remove the ones the user protects
+  - `worktree_dir` may only use `%<repo>s` and `%<branch>s` and is limited to 512 characters (anything else is `invalid_config`); a format width such as `%<repo>999999999s` could exhaust memory
+  - `pick --continue --dry-run` only shows the plan
+  - `pick` reads `git log -z` with one field per line, so a commit message cannot forge entries in the list, and only commits found by `git rev-list` are offered
+  - The git runner never hands a lone string to a shell
+  - The Claude hook in `ask` mode asks also when no snapshot could be saved, notices bundled branch flags (`git branch -qD x`), `git clean -i`, and commands inside `bash -c`, `sh -c` and `eval`, and marks a branch as agent work only if it did not exist before the command
+  - `hook install` refuses to write `.claude` settings through a symbolic link in the repository (the user scope may be a link)
+  - `docs/map/_meta/check.rb` and `sync-twins.sh` do not follow links, read files over 2 MB, or print raw file names
+  - Output keeps a path from the repository on one line: a newline or tab in a worktree path is shown as an escape, so it cannot forge a row in the confirmation text, the list or the menus. `Repo#toplevel` and the git readers remove only git's final newline, not a carriage return that ends the path
+  - When a command touches several directories the hook tells Claude one `gitflash undo` command per snapshot; a failure to record branches never stops the snapshot; the record directory is refused unless it is a real directory only the user can use
+  - A literal backslash in a path is shown doubled, so a path with a newline and a path with the characters backslash and n stay two different choices in the `wt remove` menu
+  - The hook marks a branch the command deleted and created again (`git branch -D x && git switch -c x`) as agent work: the record keeps a branch's creation stamp, not only its name

data/README.md

@@ -24,9 +24,11 @@ Or install it yourself as:
 
     $ gem install gitflash
 
+Prerelease versions such as `0.7.0.beta2` are only installed when you ask for them: `gem install gitflash --pre`, or `gem 'gitflash', '0.7.0.beta2'` 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 (pick SOURCE from a list when you omit it): `--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; both files add up
+stale_days: 30             # used by --stale without a number
+worktree_dir: "../%<repo>s.worktrees/%<branch>s"   # only these two placeholders, up to 512 characters
+```
+
 ### 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,83 @@ 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.
+
+    Without SOURCE, a terminal shows a list of the other local branches to choose from (use the
+    arrow keys, type to search, `enter` to choose and `ctrl+c` to cancel). Without a terminal,
+    SOURCE is required.
+
+    `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/log_parser.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Gitflash
+  class CherryPick
+    # Reads the output of `git log -z --shortstat --format=FORMAT` into Candidate records.
+    #
+    # One field per line: a subject or an author name cannot hold a newline, and `-z` ends each
+    # commit with a NUL, which text cannot hold either, so the framing is unambiguous whatever a
+    # commit message says. Git prints the fields of a commit, a NUL, the stat of that commit and
+    # the fields of the next one. So chunk 0 holds the fields of commit 0, chunk i the stat of
+    # commit i-1 and the fields of commit i, and the last chunk only a stat.
+    module LogParser
+      FORMAT = '%m%n%H%n%s%n%an%n%cI'
+      FIELDS = 5
+
+      module_function
+
+      def parse(output)
+        chunks = output.split("\0", -1)
+        stats = stats_of(chunks)
+        fields = chunks[0...-1].map { |chunk| chunk.lines(chomp: true).last(FIELDS) }
+        fields.each_with_index.filter_map do |row, index|
+          candidate(row, stats[index + 1]) if row.size == FIELDS
+        end
+      end
+
+      def stats_of(chunks)
+        last = chunks.size - 1
+        chunks.each_with_index.map { |chunk, index| stat_part(chunk, index == last) }
+      end
+
+      # The part of a chunk before the fields of the next commit; the last chunk is all stat
+      def stat_part(chunk, last)
+        last ? chunk : chunk.lines(chomp: true)[0...-FIELDS].to_a.join("\n")
+      end
+
+      def candidate(row, stat_text)
+        mark, sha, subject, author, date = row
+        files, insertions, deletions = stat(stat_text)
+        Candidate.new(sha: sha, subject: subject, author: author, date: date,
+                      applied: mark == '=', files: files, insertions: insertions,
+                      deletions: deletions)
+      end
+
+      # [files, insertions, deletions] from a line such as
+      # " 2 files changed, 3 insertions(+), 1 deletion(-)". Split on commas and spaces, with no
+      # regular expression, so a long run of digits in the text costs only its own length.
+      def stat(text)
+        line = text.to_s.lines.map(&:strip).reject(&:empty?).last.to_s
+        counts = { 'file' => 0, 'insertion' => 0, 'deletion' => 0 }
+        line.split(',').each { |part| tally(counts, part) }
+        counts.values
+      end
+
+      def tally(counts, part)
+        count, label = part.strip.split(' ', 2)
+        number = Integer(count, 10, exception: false)
+        kind = counts.keys.find { |name| label.to_s.start_with?(name) }
+        counts[kind] = number if number && kind
+      end
+    end
+  end
+end

data/lib/gitflash/cherry_pick.rb

@@ -0,0 +1,120 @@
+# 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)
+
+    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', '-z', '--left-right', '--cherry-mark', '--right-only',
+                          '--no-merges', '--reverse', '--shortstat', "--format=#{LogParser::FORMAT}",
+                          "HEAD...#{source_ref}", '--')
+      eligible = eligible_shas(source_ref)
+      LogParser.parse(output).select { |candidate| eligible.include?(candidate.sha) }.uniq(&:sha)
+    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
+
+    # The commits of the source that are not merges and not on HEAD, listed by git without any
+    # text a commit author controls. A commit message holding the separators of the log format
+    # could forge extra records; only SHAs found here become candidates.
+    def eligible_shas(source_ref)
+      @bash.exec('git', 'rev-list', '--right-only', '--no-merges', "HEAD...#{source_ref}", '--')
+           .lines(chomp: true).to_set
+    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'
@@ -78,9 +99,25 @@ module Gitflash
       run_command('gc', Commands::Gc)
     end
 
-    desc 'hook SUBCOMMAND', 'Agent hooks: claude (run the hook), install (register it)'
+    desc 'hook SUBCOMMAND', 'Claude Code hooks: install them and check they are active'
     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

@@ -14,6 +14,9 @@ module Gitflash
 
       attr_reader :repo, :ui, :options
 
+      # A path from the repository, kept on one line of the output
+      def shown(path) = TerminalText.line(path)
+
       def require_interactive!(message)
         usage_error!('input_required', message) unless ui.interactive?
       end
@@ -26,13 +29,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