claude-inbox 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6c29f6bef2ba7ecc7f4d63161cfc064517e21f95a3a187313a1c5b882ae34786
-  data.tar.gz: 5195d163ef619f7f82a7224ca0a9b4dfe508fd23d8c1b3d87ab0a7b3b419cb28
+  metadata.gz: b325ed415502366088de4b6e9b7634835aea1fb0a6be708e211344dfeba8fa33
+  data.tar.gz: 53fbfbeac341e7f5643724911eb5feecb4165a6aaa367dad73c2a4002be9bee9
 SHA512:
-  metadata.gz: 9b051d9eeba2b19da5c9ced63f9dcd00030619cc4c7ac667f873da8db411ecf3c777352d2b373dfb7def00c9737c6d1ed0bc8edb0663b0a73d850c01e429d20d
-  data.tar.gz: cfe120a05f387965ba538ea48dbf726ad1bf379684b1515d213bead19d02803be8030b14abd938457671c6d80fe0d65ce1de1715632db8c304b768a5e6d46ae8
+  metadata.gz: 072a5ce3e44c1e5317d105fd49aea27fc5e1365c146c165e8ad87b61b50c24f0046bd659278a41b3848ec15523c1eaa255748f5f080a4e26b25476ba6f7e1218
+  data.tar.gz: 31715b40f83b6749d3064c323018c74f62e1176f248bcc00b3cf16769b81c202b49cb0e7228e3ca8bd3b5519c8d7ca99001c026868d29605b488430a6662f5eb

data/README.md

@@ -3,6 +3,10 @@
 An inbox for Claude Code's background sessions. It lists what `claude agents`
 lists and adds snooze, settle, pinning and each session's pull request.
 
+Inspired by [T3 Code](https://github.com/pingdotgg/t3code)'s functionality and
+inbox-style UX, I wanted a better way to manage my Claude agents, so I built
+this.
+
 ![claude-inbox with one working session, one snoozed and the settled section folded](docs/screenshot.png)
 
 ## Install
@@ -14,6 +18,8 @@ gem install claude-inbox
 claude-inbox
 ```
 
+`claude-inbox update` installs the latest release.
+
 Put arguments you want on every launch in `~/.config/claude-inbox/config`.
 
 To add the pane to every Claude Code session:
@@ -22,6 +28,7 @@ To add the pane to every Claude Code session:
 claude-inbox install
 ```
 
+The inbox offers to do this once, the first time it starts without the pane.
 `claude-inbox install --force` also replaces any other copy of the pane.
 
 ## Claude Code pane
@@ -33,8 +40,8 @@ a fullscreen terminal.
 
 `/inbox` opens it, `ctrl+x tab` focuses it and `esc` leaves. The keys are the
 ones below, with `ge` for `G`, `n` `p` for `Tab` `Shift+Tab`, and no `a`,
-`P`, `X`, `Ctrl-x`, `/` or `R`. `Enter` switches to the session when you
-attached through `claude-inbox`.
+`P`, `X`, `Ctrl-x`, `/`, `R` or `U`. `Enter`, or a click on a row, switches to the
+session when you attached through `claude-inbox`.
 
 It opens when a session starts. To stop that, set
 `pluginConfigs.inbox-pane.options.openOnStart` to `false` in
@@ -84,6 +91,7 @@ Vim bindings. Arrows and the mouse work too.
 | `Ctrl-x` | delete the session, transcript and worktree for good |
 | `/` | filter; `Enter` keeps it, `Esc` clears |
 | `R` | poll now |
+| `U` | update claude-inbox when the header says a newer one is out |
 | `q` | quit |
 
 `X` and `Ctrl-x` both ask for `y` first.
@@ -91,12 +99,16 @@ Vim bindings. Arrows and the mouse work too.
 ### New session
 
 `n` opens a form for the prompt, name, directory, model, effort, permissions,
-worktree and Remote Control. `Tab` moves between fields, `Ctrl-S` starts the
-session and `Ctrl-O` starts it and attaches.
+worktree, Remote Control and color, which tints the row as `/color` would.
+`Tab` moves between fields, `Ctrl-S` starts the session and `Ctrl-O` starts
+it and attaches.
 
 Paste an image on macOS, or drop a file into the prompt, and refer to it as
 `[Image #1]`. Type `/` for a menu of your skills.
 
+Type in Directory to pick from recent and trusted directories; `Ctrl-U`
+lists them all.
+
 ## How sessions move
 
 A snoozed session wakes when its timer runs out, when you press `u`, or when
@@ -108,11 +120,10 @@ again.
 A session settles when you press `x` or when all its pull requests are merged
 or closed. A session without a pull request only settles by hand.
 
-The inbox deletes background sessions that have been idle for 14 days, with
-`claude rm`. Working, pinned and snoozed sessions are kept, and `claude rm`
-refuses a worktree with unpushed commits. Each deletion is logged to
-`~/.config/claude-inbox/reaped.log`. Set `CLAUDE_INBOX_NO_REAP=1` to turn it
-off.
+With `--reap`, the inbox deletes background sessions that have been idle for
+14 days, with `claude rm`. Working, pinned and snoozed sessions are kept, and
+`claude rm` refuses a worktree with unpushed commits. Each deletion is logged
+to `~/.config/claude-inbox/reaped.log`.
 
 ## Remote Control
 

data/exe/claude-inbox

@@ -29,8 +29,28 @@ if ARGV.first == "install"
   exit
 end
 
+if ARGV.first == "update"
+  require "claude_inbox/updater"
+  updater = ClaudeInbox::Updater.new
+  begin
+    update = updater.check(force: true)
+  rescue ClaudeInbox::Updater::Error => e
+    abort "claude-inbox: #{e.message}"
+  end
+  unless update
+    puts((updater.kind == :gem) ? "claude-inbox #{ClaudeInbox::VERSION} is the latest release." : "main is up to date.")
+    exit
+  end
+  puts update.installing
+  applied = updater.apply
+  abort "claude-inbox: #{applied.output.strip}" unless applied.success?
+  puts((update.kind == :gem) ? "Installed claude-inbox #{update.latest}." : "main is at #{update.latest}.")
+  exit
+end
+
 require "claude_inbox/app"
 require "claude_inbox/config"
+require "claude_inbox/updater"
 require "claude_inbox/writer_lock"
 require "tmpdir"
 
@@ -60,23 +80,37 @@ if fixture
   opts[:listen] = listen&.merge(fixture: true, pairing: ClaudeInbox::Remote::Pairing.new(path: File.join(dir, "listen.json")),
     lock_path: File.join(dir, "listen.lock"), images_dir: File.join(dir, "images"))
 else
-  # The only place the reaper is armed. Everything else — tests, --fixture,
-  # anything embedding App — gets one that deletes nothing. The listener,
-  # likewise, comes only from this file, and only when asked for.
+  # The only place the reaper is armed, and only with --reap: deleting
+  # sessions is opt-in. Everything else — tests, --fixture, anything
+  # embedding App — gets one that deletes nothing. The listener, likewise,
+  # comes only from this file, and only when asked for.
   opts[:client] = ClaudeInbox::AgentsClient.new
   opts[:store] = ClaudeInbox::Store.new
-  opts[:reaper] = ClaudeInbox::Reaper.new(opts[:client], opts[:store])
+  opts[:reaper] = argv.include?("--reap") ? ClaudeInbox::Reaper.new(opts[:client], opts[:store]) : ClaudeInbox::Reaper.disabled
   opts[:snapshot] = ClaudeInbox::Snapshot.new
   opts[:switch] = ClaudeInbox::Switch.new
   opts[:actions] = ClaudeInbox::Actions.new
+  opts[:pane_offer] = ClaudeInbox::Mod::Offer.new
   opts[:listen] = listen
+  opts[:updater] = ClaudeInbox::Updater.new unless argv.include?("--no-update-check")
+  # The typed arguments, not the config's: a relaunch reads the config again.
+  opts[:argv] = ARGV
 end
 opts[:color] = false if argv.include?("--no-color")
 
 if argv.include?("--headless")
   abort "claude-inbox: --headless takes no --fixture" if fixture
   require "claude_inbox/headless"
-  exit(ClaudeInbox::Headless.new(client: opts[:client], store: opts[:store]).run ? 0 : 1)
+  exit(ClaudeInbox::Headless.new(client: opts[:client], store: opts[:store], updater: opts[:updater]).run ? 0 : 1)
+end
+
+# Only what a check within the day already found: a cold launch never waits
+# on the network. The relaunch is the new version's launch; a failure leaves
+# this one to start as usual.
+if argv.include?("--auto-update") && (update = opts[:updater]&.cached)
+  puts update.installing
+  applied = opts[:updater].apply
+  applied.success? ? opts[:updater].relaunch(ARGV) : warn("claude-inbox: #{applied.output.strip}")
 end
 
 # The first inbox you can see is the snapshot's writer: a headless one gives
@@ -88,6 +122,7 @@ unless writer_lock.take(role: "inbox")
   opts[:reaper] = ClaudeInbox::Reaper.disabled
   opts[:snapshot] = ClaudeInbox::Snapshot.disabled
   opts[:actions] = ClaudeInbox::Actions.disabled
+  opts[:pane_offer] = ClaudeInbox::Mod::Offer.disabled
 end
 # So the pane settings.json names is the installed version's, after a gem update too.
 ClaudeInbox::Mod.link unless fixture

data/lib/claude_inbox/actions.rb

@@ -11,7 +11,6 @@ module ClaudeInbox
   # the store cannot honour after that, or a verb it lacks, is dropped.
   class Actions
     DEFAULT_DIR = File.join(Dir.home, ".config", "claude-inbox", "actions")
-    VERBS = %w[settle wake pin snooze acknowledge].freeze
     SNOOZES = %w[m15 h1 tomorrow_9am until_woken].freeze
     # A file still being written parses as nothing for milliseconds; a
     # session not yet polled appears within one poll.
@@ -25,16 +24,16 @@ module ClaudeInbox
       @sent = 0
     end
 
-    # Leaves one request for the writer, as the pane does; `from` names the
-    # asker, and a count keeps two requests in one millisecond apart.
-    def request(action, id, choice: nil, from: "inbox-#{Process.pid}")
+    # Leaves one request for the writer, as the pane does, named for this
+    # inbox; a count keeps two requests in one millisecond apart.
+    def request(action, id, choice: nil)
       return unless @dir
       FileUtils.mkdir_p(@dir)
       at = (@clock.call.to_f * 1000).to_i
       request = {"action" => action, "id" => id, "at" => at}
       request["choice"] = choice if choice
       @sent += 1
-      File.write(File.join(@dir, "#{from}-#{at}-#{@sent}.json"), JSON.generate(request))
+      File.write(File.join(@dir, "inbox-#{Process.pid}-#{at}-#{@sent}.json"), JSON.generate(request))
     end
 
     # Applies every request on disk to `store` and returns how many it took.
@@ -62,12 +61,14 @@ module ClaudeInbox
     def parse(path)
       request = JSON.parse(File.read(path))
       request = {} unless request.is_a?(Hash)
-      return request if File.mtime(path) < @clock.call - GRACE
+      return request if stale?(path)
       (request.key?("id") && request.key?("action")) ? request : nil
     rescue JSON::ParserError
-      (File.mtime(path) < @clock.call - GRACE) ? {} : nil
+      stale?(path) ? {} : nil
     end
 
+    def stale?(path) = File.mtime(path) < @clock.call - GRACE
+
     def young?(request)
       at = request["at"].to_i / 1000
       at.positive? && Time.at(at) >= @clock.call - GRACE
@@ -75,7 +76,7 @@ module ClaudeInbox
 
     def apply(store, request, keys)
       id = request["id"]
-      return false unless keys.include?(id) && VERBS.include?(request["action"])
+      return false unless keys.include?(id)
       case request["action"]
       when "settle" then store.settle(id)
       when "wake" then store.wake(id)
@@ -84,6 +85,8 @@ module ClaudeInbox
       when "snooze"
         return false unless SNOOZES.include?(request["choice"])
         store.snooze(id, request["choice"].to_sym)
+      else
+        return false
       end
       true
     end

data/lib/claude_inbox/agents_client.rb

@@ -39,6 +39,8 @@ module ClaudeInbox
 
     # Hands the terminal to the child; caller must have restored cooked mode.
     # Returns when the user detaches. Detaching never stops the session.
+    # False when the attach failed on its own, as a session that cannot be
+    # woken does: the CLI prints why and exits 1.
     #
     # Pressing ← inside an attached session detaches it and then `claude
     # attach` execs itself in place as `claude agents` (same pid). There is
@@ -52,22 +54,28 @@ module ClaudeInbox
       pid = Process.spawn(*Subprocess.command(@bin, "attach", id))
       watchdog = Thread.new { kill_when_agents_view(pid, &stop) }
       _, status = Process.wait2(pid)
-      status
+      status.success? || !status.exited?
     ensure
       watchdog&.kill
     end
 
-    def stop(id) = run(@bin, "stop", id)
+    def stop(id) = run("stop", id)
 
-    def rm(id) = run(@bin, "rm", id)
+    def rm(id) = run("rm", id)
 
     MODELS = %w[default fable opus sonnet haiku].freeze
     EFFORTS = %w[default low medium high xhigh max].freeze
     PERMISSION_MODES = %w[default acceptEdits auto plan bypassPermissions].freeze
-
-    # Start a background session. Returns its short id.
-    def spawn(prompt:, cwd:, **opts)
-      start_bg(self.class.spawn_args(@bin, prompt: prompt, **opts), cwd, "claude --bg")
+    # The colors `/color` offers, in its order.
+    COLORS = %w[default red blue green yellow purple orange pink cyan].freeze
+
+    # Start a background session. Returns its short id. `claude --bg` takes
+    # no color, and `/color` refuses a prompt after the color, so the color
+    # goes into the job file the way `/color` would put it there.
+    def spawn(prompt:, cwd:, color: nil, **opts)
+      id = start_bg(self.class.spawn_args(@bin, prompt: prompt, **opts), cwd, "claude --bg")
+      JobState.write_color(id, color, jobs_dir: @jobs_dir) if color
+      id
     end
 
     # How a prompt attaches a file: the same @ mention the CLI's own prompt
@@ -188,14 +196,13 @@ module ClaudeInbox
     # origin, terminal when unlisted) and the bridge a remote one is served
     # over, and drops the unattended ones, whose parent is the row worth
     # showing.
-    def assign_origins(sessions, origins, bridges = {})
+    def assign_origins(sessions, origins, bridges)
       sessions
         .map { |s| s.interactive? ? s.with(origin: origins.fetch(s.pid, :terminal), bridge_id: bridges[s.pid]) : s }
         .reject(&:unattended?)
     end
 
     def origins_from(rows)
-      return {} if rows.empty?
       self.class.origins(rows, ps_commands(rows.map { |_, ppid, _| ppid }.uniq))
     end
 
@@ -238,10 +245,9 @@ module ClaudeInbox
       nil
     end
 
-    def run(*argv)
-      r = Subprocess.capture(*argv)
-      raise Error, "#{argv[1]} failed: #{r.err.strip}" unless r.success?
-      true
+    def run(verb, id)
+      r = Subprocess.capture(@bin, verb, id)
+      raise Error, "#{verb} failed: #{r.err.strip}" unless r.success?
     end
 
     def start_bg(argv, cwd, what)
@@ -274,7 +280,7 @@ module ClaudeInbox
     # terminal round-trips through cooked mode and back.
     def attach(id) = system("sh", "-c", "printf 'fake attach to %s\\npress enter to detach: ' \"$1\"; read -r _", "attach", id)
 
-    def stop(_id) = true
+    def stop(_id) = nil
 
     def spawn(prompt:, cwd:, **)
       sleep 0.5
@@ -283,6 +289,6 @@ module ClaudeInbox
 
     def adopt(session_id:, cwd:, pid:) = "adop7ed0"
 
-    def rm(_id) = true
+    def rm(_id) = nil
   end
 end

data/lib/claude_inbox/app.rb

@@ -11,7 +11,7 @@ require_relative "terminal"
 require_relative "logs"
 require_relative "peek"
 require_relative "keymap"
-require_relative "remote"
+require_relative "remote/listener"
 require_relative "mouse"
 require_relative "new_session_form"
 require_relative "paste"
@@ -23,6 +23,9 @@ require_relative "session_request"
 require_relative "actions"
 require_relative "snapshot"
 require_relative "switch"
+require_relative "trust"
+require_relative "mod"
+require_relative "updater"
 
 module ClaudeInbox
   # Owns the terminal and the key loop. The only class allowed to spawn a
@@ -32,15 +35,19 @@ module ClaudeInbox
     # 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, 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)
+      actions: Actions.disabled, listen: nil, updater: nil, argv: [], out: $stdout, input: $stdin, color: true,
+      trust: Trust.method(:projects), terminal: Terminal.new(out, input), queue: Queue.new, pane_offer: Mod::Offer.disabled)
       @client = client
       @store = store
       @snapshot = snapshot
       @switch = switch
       @rate_limits = rate_limits
       @terminal = terminal
+      @updater = updater
+      @argv = argv
+      @out = out
       @color = color
+      @trust = trust
       @renderer = Renderer.new(color: color)
       @input = input
       @reader = TTY::Reader.new(input: input, output: out, interrupt: :noop)
@@ -63,6 +70,8 @@ module ClaudeInbox
       @last_poll = nil
       @quit = false
       @resize = false
+      @pane_offer = pane_offer
+      @modal = Dialog::PaneOffer.new if pane_offer.take
     end
 
     def run
@@ -81,6 +90,7 @@ module ClaudeInbox
     end
 
     def step(input = nil)
+      check_for_update unless @update_status
       drain_queue
       @logs.tick
       if @resize
@@ -122,6 +132,7 @@ module ClaudeInbox
           @error = nil
         when :error then @error = rest[0]
         when :notice then notice(rest[0])
+        when :update then update_checked(*rest)
         when :select then @pending_select = rest[0]
         when :attach then attach(rest[0])
         when :form_started then @modal = nil if @modal.equal?(rest[0])
@@ -129,8 +140,6 @@ module ClaudeInbox
         when :remote_started then remote_started(*rest)
         end
       end
-    rescue ThreadError
-      nil
     end
 
     # ----- main loop --------------------------------------------------------
@@ -206,7 +215,49 @@ module ClaudeInbox
     def status_text(now)
       return @notice[0] if @notice && now < @notice[1]
       return "⚠ #{@error}" if @error
-      "polling…" unless @last_poll
+      return "polling…" unless @last_poll
+      "#{@update.notice} · U updates" if @update
+    end
+
+    # ----- updates ----------------------------------------------------------
+
+    # Once, on the first step: a stale cache means a network round trip, so
+    # it runs off the main thread. A laptop that is offline stays quiet
+    # rather than show an error at every launch; U says what went wrong.
+    def check_for_update
+      @update_status = @updater ? "checking for updates…" : "update check is off — claude-inbox update installs the latest"
+      return unless @updater
+      in_background do
+        @queue << [:update, @updater.check]
+      rescue Updater::Error => e
+        @queue << [:update, nil, e.message]
+      end
+    end
+
+    def update_checked(update, failure = nil)
+      @update = update
+      @snapshot.update = update&.notice
+      @update_status = failure ? "couldn't check for updates: #{failure}" : "up to date"
+    end
+
+    # The install prints on the real screen, and the relaunch replaces this
+    # process. A failed install relaunches this version instead, once its
+    # error has been read, rather than leave the shell showing.
+    def update_inbox
+      return notice(@update_status) unless @update
+      @terminal.release do
+        @out.puts @update.installing
+        applied = @updater.apply
+        @out.puts applied.output unless applied.output.empty?
+        @terminal.pause unless applied.success?
+        relaunch
+      end
+    end
+
+    def relaunch
+      @updater.relaunch(@argv)
+    rescue SystemCallError => e
+      @error = "relaunch failed: #{e.message}"
     end
 
     def filtered(sections = @store.sections) = sections.matching(@filter&.to_s)
@@ -225,7 +276,7 @@ module ClaudeInbox
 
     def select(selection)
       @selected = selection
-      @peek.select(selection, selected_session)
+      @peek.select(selected_session)
     end
 
     def session_for(key) = @store.sessions.find { |s| s.key == key }
@@ -305,7 +356,7 @@ module ClaudeInbox
       return if @list_width && col > @list_width
       item = row_item_at(row)
       return unless item
-      select(item.selection)
+      select(item)
       activate
     end
 
@@ -313,7 +364,7 @@ module ClaudeInbox
     # no item of its own; a click there resolves to the row above it.
     def row_item_at(row)
       idx = row - 1
-      @row_items[idx] || (@row_items[idx - 1] if idx > 0 && @row_items[idx - 1]&.kind == :row)
+      @row_items[idx] || (@row_items[idx - 1] if idx > 0 && @row_items[idx - 1]&.row?)
     end
 
     def perform(action)
@@ -347,6 +398,7 @@ module ClaudeInbox
       when :stop then open_confirm(:stop)
       when :delete then open_confirm(:delete)
       when :refresh then @poller.soon
+      when :update then update_inbox
       when :toggle_peek then toggle_peek
       when :new_session then open_new_session
       when :remote_pairing then @modal = @listener.pairing_dialog
@@ -420,13 +472,16 @@ module ClaudeInbox
 
     # 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.
+    # poller keeps running meanwhile, so the pane's snapshot stays fresh. A
+    # failed attach leaves its reason on screen until a key is pressed.
     def attach(id)
       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) } }
+        from = session_for(id)&.session_id
+        @terminal.release do
+          @terminal.pause unless @client.attach(id) { @switch.requested_for?(from) }
+        end
         id = @switch.take(@store.sessions.select(&:actionable?).map(&:key))
       end
     end
@@ -475,7 +530,8 @@ module ClaudeInbox
 
     def open_new_session
       cwd = selected_session&.cwd || Dir.pwd
-      @modal = NewSessionForm.new(cwd: SessionRequest.strip_worktree(cwd), pastel: Pastel.new(enabled: @color))
+      dirs = SessionRequest.directories(@store.sessions, @trust.call)
+      @modal = NewSessionForm.new(cwd: SessionRequest.strip_worktree(cwd), color: @color, dirs: dirs)
     end
 
     # `attach:` hands the terminal over as soon as the session starts. Without
@@ -532,6 +588,7 @@ module ClaudeInbox
         when :stop then stop_session(id)
         when :delete then delete_session(id)
         when :adopt then adopt_session(id)
+        when :install then install_pane
         end
       when :save then save_prompt
       when :copy then @listener.copy_pairing_url
@@ -570,6 +627,13 @@ module ClaudeInbox
       end
     end
 
+    def install_pane
+      @pane_offer.install
+      notice("added the pane — new Claude Code sessions load it; /inbox opens it")
+    rescue JSON::ParserError
+      notice("~/.claude/settings.json is not valid JSON, so it was left alone")
+    end
+
     def delete_session(id)
       notice("deleting #{id}…")
       in_background do

data/lib/claude_inbox/dialog.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "tty-box"
+require_relative "text"
 require_relative "text_buffer"
 
 module ClaudeInbox
@@ -78,6 +79,45 @@ module ClaudeInbox
       end
     end
 
+    # The first launch without the Claude Code pane asks once whether to add
+    # it, and has to say what the pane is to someone who has never seen it.
+    class PaneOffer < Confirm
+      WIDTH = 60
+      SKETCH = [
+        "  ┌──────────────────────────┬─────────────────────┐",
+        "  │ > fix the flaky spec     │ 📥 Inbox            │",
+        "  │                          │ ● needs you   docs  │",
+        "  │ Reading app.rb…          │ ⠋ working     api   │",
+        "  │                          │ ✓ done        auth  │",
+        "  └──────────────────────────┴─────────────────────┘"
+      ].freeze
+
+      def initialize = super(:install, nil)
+
+      def title = " ✨ The inbox, inside Claude Code "
+
+      # Drawn by hand: TTY::Box measures an emoji as one column, which
+      # pushes the right border out on every line that has one.
+      def frame(width, _caret = nil)
+        inner = [width - 4, WIDTH].min - 2
+        ["┌#{title}#{"─" * (inner - Text.width(title))}┐",
+          *lines(inner, nil).map { |l| "│#{Text.pad(Text.truncate(l, inner), inner)}│" },
+          "└#{"─" * inner}┘"]
+      end
+
+      def lines(_width, _caret)
+        ["", *SKETCH, "",
+          "  • Every session, docked beside the transcript",
+          "  • Switch sessions without leaving the one you're in",
+          "  • Snooze, pin and settle with the same keys",
+          "  • /inbox opens it, ctrl+x tab focuses it",
+          "",
+          "  You can install this later with claude-inbox install",
+          "",
+          "      y  add it to Claude Code      esc  not now"]
+      end
+    end
+
     # `a` alias and `P` pull request: one line of text, read from `value`
     # once :save comes back. Empty means clear.
     class Prompt < Dialog

data/lib/claude_inbox/headless.rb

@@ -5,6 +5,7 @@ require_relative "poller"
 require_relative "pull_requests"
 require_relative "reaper"
 require_relative "snapshot"
+require_relative "updater"
 require_relative "writer_lock"
 
 module ClaudeInbox
@@ -13,19 +14,34 @@ module ClaudeInbox
   # 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)
+    def initialize(client:, store:, pull_requests: PullRequests.new, actions: Actions.new, snapshot: Snapshot.new,
+      lock: WriterLock.new, updater: nil)
       @lock = lock
-      @queue = queue
+      @snapshot = snapshot
+      @updater = updater
+      @queue = Queue.new
       @poller = Poller.new(client: client, store: store, pull_requests: pull_requests, reaper: Reaper.disabled,
-        queue: queue, snapshot: snapshot, actions: actions)
+        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
+      check_for_update if @updater
       loop { @queue.pop }
     end
+
+    private
+
+    # After the poller is off, since the check may wait on the network. The
+    # pane cannot swap the process under Claude Code, so the snapshot only
+    # says a newer one is out, and a check that cannot tell says nothing.
+    def check_for_update
+      @snapshot.update = @updater.check&.notice
+      @poller.soon
+    rescue Updater::Error
+      nil
+    end
   end
 end

data/lib/claude_inbox/images.rb

@@ -41,7 +41,7 @@ module ClaudeInbox
     # `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)
+    def self.save(bytes, dir:, index:, now: Time.now)
       data = bytes.b
       ext = extension(data)
       raise Unsupported, "not a PNG, JPEG, GIF or WebP image" unless ext