claude-inbox 0.2.0 → 0.4.0

data/lib/claude_inbox/agents_client.rb

@@ -3,6 +3,7 @@
 require "json"
 require_relative "debug"
 require_relative "job_state"
+require_relative "session"
 require_relative "subprocess"
 
 module ClaudeInbox
@@ -45,9 +46,11 @@ module ClaudeInbox
     # that exists disables attach too. So we watch the child's command line
     # and, the moment it becomes the agents view, terminate it. The user then
     # lands back in the inbox instead of native agent view.
-    def attach(id)
-      pid = Process.spawn(@bin, "attach", id)
-      watchdog = Thread.new { kill_when_agents_view(pid) }
+    # The block, polled with the command line, ends the attach early when it
+    # answers true: how a switch request from another front end is honoured.
+    def attach(id, &stop)
+      pid = Process.spawn(*Subprocess.command(@bin, "attach", id))
+      watchdog = Thread.new { kill_when_agents_view(pid, &stop) }
       _, status = Process.wait2(pid)
       status
     ensure
@@ -64,10 +67,7 @@ module ClaudeInbox
 
     # Start a background session. Returns its short id.
     def spawn(prompt:, cwd:, **opts)
-      argv = self.class.spawn_args(@bin, prompt: prompt, **opts)
-      r = Subprocess.capture(*argv, chdir: cwd)
-      raise Error, "claude --bg failed: #{(r.err + r.out).strip}" unless r.success?
-      r.out[/\b[0-9a-f]{8}\b/] || r.out.strip
+      start_bg(self.class.spawn_args(@bin, prompt: prompt, **opts), cwd, "claude --bg")
     end
 
     # How a prompt attaches a file: the same @ mention the CLI's own prompt
@@ -75,18 +75,19 @@ module ClaudeInbox
     # its path completion escapes them; a quoted path is not recognized.
     def self.mention(path) = "@" + path.gsub(" ", "\\ ")
 
-    # Pure so it can be tested: "default" means leave the flag off.
-    # --remote-control takes an optional name and eats whatever follows it,
-    # prompt included, so it goes last.
+    # Pure so it can be tested: a setting left nil leaves its flag off. The
+    # prompt goes after "--", where a leading dash is text rather than an
+    # unknown option, and --remote-control sits just before it: its optional
+    # name would otherwise eat the prompt (both checked on 2.1.282).
     def self.spawn_args(bin, prompt:, model: nil, effort: nil, permission_mode: nil, worktree: false, name: nil, remote: false)
-      argv = [bin, "--bg", prompt]
-      argv += ["--model", model] if model && model != "default"
-      argv += ["--effort", effort] if effort && effort != "default"
-      argv += ["--permission-mode", permission_mode] if permission_mode && permission_mode != "default"
+      argv = [bin, "--bg"]
+      {"--model" => model, "--effort" => effort, "--permission-mode" => permission_mode}.each do |flag, value|
+        argv += [flag, value] if value
+      end
       argv += ["--name", name] if name && !name.strip.empty?
       argv << "--worktree" if worktree
       argv << "--remote-control" if remote
-      argv
+      argv + ["--", prompt]
     end
 
     # Pull a conversation a `claude remote-control` server is serving into
@@ -98,9 +99,7 @@ module ClaudeInbox
       raise Error, "nothing to adopt yet — send it a message from your phone first" if transcript_empty?(cwd, session_id)
       Process.kill("TERM", pid)
       wait_gone(pid)
-      r = Subprocess.capture(*self.class.adopt_args(@bin, session_id), chdir: cwd)
-      raise Error, "claude --bg --resume failed: #{(r.err + r.out).strip}" unless r.success?
-      r.out[/\b[0-9a-f]{8}\b/] || r.out.strip
+      start_bg(self.class.adopt_args(@bin, session_id), cwd, "claude --bg --resume")
     end
 
     def self.adopt_args(bin, session_id) = [bin, "--bg", "--resume", session_id, "--remote-control"]
@@ -111,6 +110,45 @@ module ClaudeInbox
       File.join(home, ".claude", "projects", cwd.gsub(%r{[/.]}, "-"), "#{session_id}.jsonl")
     end
 
+    # Flags that mark a claude process as one a program drives rather than one
+    # you type in: the headless print mode and the SDK's stream protocol.
+    HEADLESS_FLAGS = %w[-p --print --input-format --output-format].freeze
+
+    # pid => origin, given `ps` for the sessions and for their parents. Pure.
+    #
+    #   :remote    a Remote Control worker: --sdk-url, or a `claude rc` parent
+    #   :headless  `claude -p "..."` or an SDK stream run. Its parent is
+    #              whatever shell spawned it, not the claude that asked for
+    #              it, so only its own command line gives it away
+    #   :subagent  parented by another claude process
+    #   :terminal  everything else, which is a claude you are sitting in
+    def self.origins(rows, parent_cmd)
+      rows.to_h do |pid, ppid, cmd|
+        parent = parent_cmd[ppid].to_s
+        origin =
+          if cmd.include?("--sdk-url") || parent.match?(/\bclaude rc\b/) then :remote
+          elsif headless?(cmd) then :headless
+          elsif parent.match?(/(^|\/)claude\b/) then :subagent
+          else :terminal
+          end
+        [pid, origin]
+      end
+    end
+
+    # `ps` flattens quoting, so a prompt that mentions a flag reads the same
+    # as the flag itself. Nobody types `claude "what does -p do"` into a
+    # terminal often enough to matter; the false positive is accepted.
+    def self.headless?(cmd) = cmd.split.drop(1).any? { |arg| HEADLESS_FLAGS.include?(arg) }
+
+    # pid => bridge session id, for the workers a `claude remote-control`
+    # server spawned: each is started with `--session-id cse_…`, the same id
+    # a background session records as bridgeSessionId. Pure.
+    def self.bridge_ids(rows)
+      rows.filter_map { |pid, _, cmd| (m = cmd.match(/--session-id[= ](cse_\w+)/)) && [pid, m[1]] }.to_h
+    end
+
+    private
+
     # A worker nobody has messaged yet has an empty file, and the daemon
     # reports "source session not found" on resuming it.
     def transcript_empty?(cwd, session_id)
@@ -133,10 +171,6 @@ module ClaudeInbox
       JSON.parse(json).map { |h| Session.from_hash(h) }
     end
 
-    # Flags that mark a claude process as one a program drives rather than one
-    # you type in: the headless print mode and the SDK's stream protocol.
-    HEADLESS_FLAGS = %w[-p --print --input-format --output-format].freeze
-
     # The JSON reports Remote Control workers, local sub-agents and headless
     # runs as `interactive`, same as a terminal you opened yourself, each named
     # after its directory. The process tree tells them apart; see `origins`.
@@ -160,39 +194,6 @@ module ClaudeInbox
         .reject(&:unattended?)
     end
 
-    # pid => origin, given `ps` for the sessions and for their parents. Pure.
-    #
-    #   :remote    a Remote Control worker: --sdk-url, or a `claude rc` parent
-    #   :headless  `claude -p "..."` or an SDK stream run. Its parent is
-    #              whatever shell spawned it, not the claude that asked for
-    #              it, so only its own command line gives it away
-    #   :subagent  parented by another claude process
-    #   :terminal  everything else, which is a claude you are sitting in
-    def self.origins(rows, parent_cmd)
-      rows.to_h do |pid, ppid, cmd|
-        parent = parent_cmd[ppid].to_s
-        origin =
-          if cmd.include?("--sdk-url") || parent.match?(/\bclaude rc\b/) then :remote
-          elsif headless?(cmd) then :headless
-          elsif parent.match?(/(^|\/)claude\b/) then :subagent
-          else :terminal
-          end
-        [pid, origin]
-      end
-    end
-
-    # `ps` flattens quoting, so a prompt that mentions a flag reads the same
-    # as the flag itself. Nobody types `claude "what does -p do"` into a
-    # terminal often enough to matter; the false positive is accepted.
-    def self.headless?(cmd) = cmd.split.drop(1).any? { |arg| HEADLESS_FLAGS.include?(arg) }
-
-    # pid => bridge session id, for the workers a `claude remote-control`
-    # server spawned: each is started with `--session-id cse_…`, the same id
-    # a background session records as bridgeSessionId. Pure.
-    def self.bridge_ids(rows)
-      rows.filter_map { |pid, _, cmd| (m = cmd.match(/--session-id[= ](cse_\w+)/)) && [pid, m[1]] }.to_h
-    end
-
     def origins_from(rows)
       return {} if rows.empty?
       self.class.origins(rows, ps_commands(rows.map { |_, ppid, _| ppid }.uniq))
@@ -205,8 +206,6 @@ module ClaudeInbox
         pid, ppid, *cmd = l.split
         [pid.to_i, ppid.to_i, cmd.join(" ")]
       }
-    rescue Errno::ENOENT
-      []
     end
 
     # pid => command, for the given parent pids.
@@ -220,17 +219,18 @@ module ClaudeInbox
       }
     end
 
-    private
-
-    def kill_when_agents_view(pid)
+    def kill_when_agents_view(pid, &stop)
       loop do
         sleep WATCH_INTERVAL
         cmd = Subprocess.capture("ps", "-o", "command=", "-p", pid.to_s).out
         break if cmd.empty?
-        next unless cmd.split[1] == "agents"
+        next unless cmd.split[1] == "agents" || stop&.call
         Debug.log("watchdog saw #{cmd.inspect}")
         Process.kill("TERM", pid)
-        sleep 1
+        10.times do
+          sleep 0.1
+          break if Subprocess.capture("ps", "-o", "pid=", "-p", pid.to_s).out.empty?
+        end
         Process.kill("KILL", pid)
         break
       end
@@ -243,6 +243,12 @@ module ClaudeInbox
       raise Error, "#{argv[1]} failed: #{r.err.strip}" unless r.success?
       true
     end
+
+    def start_bg(argv, cwd, what)
+      r = Subprocess.capture(*argv, chdir: cwd)
+      raise Error, "#{what} failed: #{(r.err + r.out).strip}" unless r.success?
+      r.out[/\b[0-9a-f]{8}\b/] || r.out.strip
+    end
   end
 
   # Reads a committed JSON fixture instead of the daemon.

data/lib/claude_inbox/app.rb

@@ -11,33 +11,43 @@ require_relative "terminal"
 require_relative "logs"
 require_relative "peek"
 require_relative "keymap"
+require_relative "remote"
 require_relative "mouse"
 require_relative "new_session_form"
 require_relative "paste"
 require_relative "pull_requests"
+require_relative "reaper"
 require_relative "poller"
 require_relative "rate_limits"
+require_relative "session_request"
+require_relative "actions"
+require_relative "snapshot"
+require_relative "switch"
 
 module ClaudeInbox
   # Owns the terminal and the key loop. The only class allowed to spawn a
   # child process that takes over the terminal.
   class App
-    # The reaper defaults to off. It is the only thing here that deletes a
-    # session, so switching it on is `bin/claude-inbox`'s job and nothing
-    # reaches it by forgetting an argument.
+    # The reaper deletes sessions and the listener lets other machines in,
+    # so both are off unless `bin/claude-inbox` switches them on.
     def initialize(client: AgentsClient.new, store: Store.new, pull_requests: PullRequests.new,
-      rate_limits: RateLimits.new, reaper: Reaper.disabled, out: $stdout, input: $stdin, color: true,
-      terminal: Terminal.new(out, input))
+      rate_limits: RateLimits.new, reaper: Reaper.disabled, snapshot: Snapshot.disabled, switch: Switch.disabled,
+      actions: Actions.disabled, listen: nil, out: $stdout, input: $stdin, color: true,
+      terminal: Terminal.new(out, input), queue: Queue.new)
       @client = client
       @store = store
+      @snapshot = snapshot
+      @switch = switch
       @rate_limits = rate_limits
       @terminal = terminal
       @color = color
       @renderer = Renderer.new(color: color)
+      @input = input
       @reader = TTY::Reader.new(input: input, output: out, interrupt: :noop)
-      @queue = Queue.new
+      @queue = queue
       @poller = Poller.new(client: client, store: store, pull_requests: pull_requests,
-        reaper: reaper, queue: @queue)
+        reaper: reaper, queue: @queue, snapshot: snapshot, actions: actions)
+      @listener = listen ? Remote::Listener.new(client: client, store: store, queue: @queue, **listen) : Remote::Listener.disabled
       @logs = Logs.new(client)
       @peek = Peek.new(@logs)
       @selected = nil
@@ -60,12 +70,14 @@ module ClaudeInbox
       install_traps
       @terminal.enter
       @poller.start
+      @listener.start
       @logs.start
       main_loop
     ensure
       @poller.stop
       @logs.stop
       @terminal.restore
+      @listener.stop
     end
 
     def step(input = nil)
@@ -75,8 +87,10 @@ module ClaudeInbox
         @resize = false
         @terminal.resized
       end
-      render
       handle_input(input) if input
+      # A paste arrives a character per read and shows nothing until it
+      # closes, so a frame per character would only stall a long one.
+      render unless @paste.pasting?
     end
 
     private
@@ -104,7 +118,6 @@ module ClaudeInbox
         kind, *rest = @queue.pop(true)
         case kind
         when :sessions
-          @store.update(rest[0])
           @last_poll = Time.now
           @error = nil
         when :error then @error = rest[0]
@@ -113,6 +126,7 @@ module ClaudeInbox
         when :attach then attach(rest[0])
         when :form_started then @modal = nil if @modal.equal?(rest[0])
         when :form_failed then form_failed(*rest)
+        when :remote_started then remote_started(*rest)
         end
       end
     rescue ThreadError
@@ -122,7 +136,19 @@ module ClaudeInbox
     # ----- main loop --------------------------------------------------------
 
     def main_loop
-      step(@reader.read_keypress(echo: false, raw: false, nonblock: true)) until @quit
+      step(@paste.pasting? ? read_pasted : @reader.read_keypress(echo: false, raw: false, nonblock: true)) until @quit
+    end
+
+    # As much of an open paste as has arrived, read straight off the tty:
+    # the reader switches echo off and back on around every character, and
+    # on a long paste that is most of the wait.
+    def read_pasted
+      return nil unless @input.wait_readable(0.1)
+      out = +""
+      while out.size < 65_536 && @input.wait_readable(0) && (c = @input.getc)
+        out << c
+      end
+      out
     end
 
     def handle_input(raw)
@@ -135,24 +161,30 @@ module ClaudeInbox
     end
 
     # The form takes a paste whole, images included; the one-line editors
-    # take it as typing, so a pasted PR URL lands where it should.
+    # take it as typing, so a pasted PR URL lands where it should. Anywhere
+    # else a paste is dropped: typed out, its letters would be keys, and a
+    # "y" answers a confirm.
     def handle_paste(text)
       return @modal.paste(text) if @modal.is_a?(NewSessionForm)
-      text.each_char { |c| handle_key(c) }
+      typing = @modal ? @modal.is_a?(Dialog::Prompt) : @filter_editing
+      text.each_char { |c| handle_key(c) } if typing
     end
 
     def render
       t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
       now = Time.now
-      sections = filtered(@store.sections(now))
+      all = @store.sections(now)
+      @snapshot.write(all, now)
+      sections = filtered(all)
       width, height = @terminal.size
+      body_h = Renderer.body_height(height)
       ensure_selection(sections)
       @tick += 1
       view = Renderer::View.new(
         width: width, height: height, now: now, selected: @selected&.key, top: @top, expanded: @expanded,
-        peek: @peek.view(sections.row(@selected), height), modal: modal_lines(width), screen: screen_lines(width, height),
+        peek: @peek.view(sections.row(@selected), body_h), modal: modal_lines(width), screen: screen_lines(width, body_h),
         status: status_text(now), usage: @rate_limits.windows(now), filter: @filter, filter_editing: @filter_editing,
-        tick: @tick / 2, loading: loading_for
+        tick: @tick / 2, loading: loading_for, listening: @listener.snapshot
       )
       frame = @renderer.frame(sections, view)
       @row_items = frame.items
@@ -202,8 +234,9 @@ module ClaudeInbox
 
     # Guard for attach/stop: refuse politely on a terminal or remote row.
     def require_actionable
-      return true if selected_session&.actionable?
-      if (s = selected_session)&.interactive?
+      s = selected_session
+      return true if s&.actionable?
+      if s&.interactive?
         notice(s.remote? ? "that's a remote session — Enter adopts it, w opens it at claude.ai/code" : "that's your own terminal — switch to that window")
       end
       false
@@ -212,8 +245,16 @@ module ClaudeInbox
     # Guard for snooze/wake/alias: anything with a key, since those live in
     # our own store. A terminal you are sitting in is the one exception.
     def require_storable
-      return true if @selected&.row? && !selected_session&.terminal?
-      notice("you're in that terminal right now — nothing to snooze") if selected_session&.terminal?
+      s = selected_session
+      return true if @selected&.row? && !s&.terminal?
+      notice("you're in that terminal right now — nothing to snooze") if s&.terminal?
+      false
+    end
+
+    # The edits with no request form, which a second inbox cannot keep.
+    def require_writable(verb)
+      return true if @store.writable?
+      notice("another claude-inbox owns state.json — #{verb} there")
       false
     end
 
@@ -308,12 +349,13 @@ module ClaudeInbox
       when :refresh then @poller.soon
       when :toggle_peek then toggle_peek
       when :new_session then open_new_session
+      when :remote_pairing then @modal = @listener.pairing_dialog
       when :filter then start_filter
       when :escape then clear_filter
       end
     end
 
-    def page = [@terminal.size[1] - 2, 1].max
+    def page = [Renderer.body_height(@terminal.size[1]), 1].max
 
     def move(delta)
       stops = filtered.selections(@expanded)
@@ -338,7 +380,8 @@ module ClaudeInbox
       name if Store::FOLDABLE_SECTIONS.include?(name)
     end
 
-    def set_expanded(value, name: current_fold_section)
+    def set_expanded(value)
+      name = current_fold_section
       @expanded[name] = value if name
     end
 
@@ -375,12 +418,17 @@ module ClaudeInbox
       notice("settled — u brings it back")
     end
 
+    # The pane in the attached session may ask for a different one: the
+    # attach ends and the next starts without passing through the list. The
+    # poller keeps running meanwhile, so the pane's snapshot stays fresh.
     def attach(id)
-      @store.acknowledge(id)
-      @poller.pause
-      @terminal.release { @client.attach(id) }
-    ensure
-      @poller.resume
+      while id
+        @store.acknowledge(id)
+        @switch.clear
+        from = @store.sessions.find { |s| s.key == id }&.session_id
+        @terminal.release { @client.attach(id) { @switch.requested_for?(from) } }
+        id = @switch.take(@store.sessions.select(&:actionable?).map(&:key))
+      end
     end
 
     # ----- modals -----------------------------------------------------------
@@ -396,13 +444,13 @@ module ClaudeInbox
     end
 
     def open_alias_editor
-      return unless require_storable
+      return unless require_storable && require_writable("rename")
       current = @store.alias_for(@selected.key) || ""
       @modal = Dialog::Prompt.new(:alias, @selected.key, current)
     end
 
     def open_pr_editor
-      return unless require_storable
+      return unless require_storable && require_writable("link a pull request")
       current = @store.pr_for(@selected.key) || selected_session&.pr&.url || ""
       @modal = Dialog::Prompt.new(:pr, @selected.key, current)
     end
@@ -427,14 +475,7 @@ module ClaudeInbox
 
     def open_new_session
       cwd = selected_session&.cwd || Dir.pwd
-      @modal = NewSessionForm.new(cwd: strip_worktree(cwd), pastel: Pastel.new(enabled: @color))
-    end
-
-    # A session's cwd may sit inside a worktree another agent is using; carrying
-    # that into a new prompt would spawn the new agent there too, writing over
-    # the same files. Fall back to the repo the worktree was cut from.
-    def strip_worktree(cwd)
-      cwd.to_s.sub(%r{/\.claude/worktrees/[^/]+(?:/.*)?\z}, "")
+      @modal = NewSessionForm.new(cwd: SessionRequest.strip_worktree(cwd), pastel: Pastel.new(enabled: @color))
     end
 
     # `attach:` hands the terminal over as soon as the session starts. Without
@@ -454,6 +495,13 @@ module ClaudeInbox
       end
     end
 
+    # Someone at the desk may be mid-thought, so a start from another
+    # device never moves the cursor, attaches or closes what is open.
+    def remote_started(id, via)
+      notice("started #{id} from #{via}")
+      @poller.soon
+    end
+
     # A spawn failure hands the form back rather than just logging it, so
     # the composed prompt survives (see NewSessionForm#submission_failed).
     def form_failed(form, message)
@@ -461,9 +509,9 @@ module ClaudeInbox
     end
 
     # The new-session form takes the whole body; a Dialog is a box over it.
-    def screen_lines(width, height)
+    def screen_lines(width, body_h)
       return nil unless @modal.is_a?(NewSessionForm)
-      {lines: @modal.screen(width, height - 2), footer: @modal.footer}
+      {lines: @modal.screen(width, body_h), footer: @modal.footer}
     end
 
     def modal_lines(width)
@@ -486,6 +534,8 @@ module ClaudeInbox
         when :adopt then adopt_session(id)
         end
       when :save then save_prompt
+      when :copy then @listener.copy_pairing_url
+      when :rotate then @listener.rotate
       end
     end
 

data/lib/claude_inbox/config.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "shellwords"
+
+module ClaudeInbox
+  # Arguments for every launch. They go before the typed ones, so a typed
+  # flag wins.
+  module Config
+    PATH = File.join(Dir.home, ".config", "claude-inbox", "config")
+
+    def self.argv(typed, path: PATH)
+      args(path) + typed
+    end
+
+    def self.args(path)
+      File.readlines(path).flat_map { |line| Shellwords.split(line.sub(/(\A|\s)#.*/, "")) }
+    rescue Errno::ENOENT
+      []
+    rescue ArgumentError => e
+      raise ArgumentError, "#{path}: #{e.message}"
+    end
+    private_class_method :args
+  end
+end

data/lib/claude_inbox/dialog.rb

@@ -10,6 +10,8 @@ module ClaudeInbox
   # the details read off the dialog afterwards. `frame(width)` is the box
   # Renderer overlays. Pure: nothing here touches the store or the client.
   class Dialog
+    WIDTH = 44
+
     attr_reader :kind, :id
 
     def initialize(kind, id)
@@ -18,7 +20,7 @@ module ClaudeInbox
     end
 
     def frame(width, caret = nil)
-      box = [width - 4, 44].min
+      box = [width - 4, self.class::WIDTH].min
       TTY::Box.frame(lines(box - 4, caret).join("\n"), title: {top_left: title}, padding: [0, 1], width: box)
         .split("\n")
     end

data/lib/claude_inbox/headless.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "actions"
+require_relative "poller"
+require_relative "pull_requests"
+require_relative "reaper"
+require_relative "snapshot"
+require_relative "writer_lock"
+
+module ClaudeInbox
+  # The poller with no terminal, for a front end that only reads the
+  # snapshot: it polls, writes the file and applies the requests. It never
+  # reaps, since deleting sessions stays with the inbox you can see, and it
+  # exits at once while an inbox holds the writer lock.
+  class Headless
+    def initialize(client:, store:, pull_requests: PullRequests.new, snapshot: Snapshot.new, actions: Actions.new,
+      lock: WriterLock.new, queue: Queue.new)
+      @lock = lock
+      @queue = queue
+      @poller = Poller.new(client: client, store: store, pull_requests: pull_requests, reaper: Reaper.disabled,
+        queue: queue, snapshot: snapshot, actions: actions)
+    end
+
+    # False when the lock is held, by an inbox or another headless process.
+    def run
+      return false unless @lock.take(role: "headless")
+      @poller.start
+      loop { @queue.pop }
+    end
+  end
+end

data/lib/claude_inbox/images.rb

@@ -1,11 +1,13 @@
 # frozen_string_literal: true
 
 require "fileutils"
+require "securerandom"
 require_relative "subprocess"
 
 module ClaudeInbox
-  # Images a prompt can carry: a dropped file, or whatever is on the
-  # clipboard. Both come back as a path for a TextBuffer chip to hold.
+  # Images a prompt can carry: a dropped file, whatever is on the
+  # clipboard, or the bytes a request sent. Each comes back as a path for
+  # the prompt to mention.
   module Images
     DEFAULT_DIR = File.join(Dir.home, ".config", "claude-inbox", "images")
     EXTENSIONS = %w[.png .jpg .jpeg .gif .webp .bmp .svg].freeze
@@ -14,9 +16,19 @@ module ClaudeInbox
 
     Clipboard = Struct.new(:image, :text)
 
-    # Saved images are pruned here, on the way in, because nothing else
-    # knows when a session stopped needing its image. macOS only: osascript
-    # ships with the OS, and PNG is the flavor a screenshot puts there.
+    class Unsupported < StandardError; end
+
+    # Bytes from a request carry no file name worth trusting, so the type
+    # comes from the magic number at the front.
+    MAGIC = {
+      ".png" => /\A\x89PNG/n,
+      ".jpg" => /\A\xFF\xD8\xFF/n,
+      ".gif" => /\AGIF8/n,
+      ".webp" => /\ARIFF.{4}WEBP/mn
+    }.freeze
+
+    # macOS only: osascript ships with the OS, and PNG is the flavor a
+    # screenshot puts there.
     def self.from_clipboard(dir: DEFAULT_DIR, now: Time.now, run: Subprocess.method(:capture))
       FileUtils.mkdir_p(dir)
       prune(dir, now)
@@ -26,6 +38,23 @@ module ClaudeInbox
       Clipboard.new(nil, (text.success? && !text.out.empty?) ? text.out : nil)
     end
 
+    # `index` orders the images one request brings; the random part keeps
+    # two requests saving in the same millisecond apart. Readable by the
+    # owner only: a photo can be anything.
+    def self.save(bytes, dir: DEFAULT_DIR, now: Time.now, index: 1)
+      data = bytes.b
+      ext = extension(data)
+      raise Unsupported, "not a PNG, JPEG, GIF or WebP image" unless ext
+      FileUtils.mkdir_p(dir)
+      prune(dir, now)
+      path = File.join(dir, "#{now.strftime("%Y%m%d-%H%M%S-%L")}-#{index}-#{SecureRandom.hex(3)}#{ext}")
+      File.open(path, File::WRONLY | File::CREAT | File::EXCL | File::BINARY, 0o600) { |f| f.write(data) }
+      path
+    end
+
+    # ".png", ".jpg", ".gif" or ".webp" by the magic number, or nil.
+    def self.extension(bytes) = MAGIC.find { |_, magic| magic.match?(bytes.b) }&.first
+
     CLIPBOARD_PNG = <<~APPLESCRIPT
       on run argv
         set png to the clipboard as «class PNGf»
@@ -46,8 +75,10 @@ module ClaudeInbox
       File.file?(path) ? path : nil
     end
 
+    # Pruned on the way in, because nothing else knows when a session
+    # stopped needing its image.
     def self.prune(dir, now)
-      Dir.glob(File.join(dir, "*.png")).each do |f|
+      Dir.glob(EXTENSIONS.map { |ext| File.join(dir, "*#{ext}") }).each do |f|
         File.delete(f) if now - File.mtime(f) > KEEP_FOR
       rescue SystemCallError
         nil