claude-inbox 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b432b1272fd3e3b923eaefe34fa4e3c30cbd9dfcf57d4beacd761f1cef70785b
-  data.tar.gz: '090ff2d41f9701cc7476196af19e4604241b3b3079376a896b441ab9dbf0ce9d'
+  metadata.gz: 5f240b8de798a2fea0c318d9bd7882e2d05cf7bdcbdc48fea7698f2ac8e6dc82
+  data.tar.gz: a94912ebe0d438922d9f5bdc334e0be3465e7997fb9767bc1e2a6ef9f7ed55b4
 SHA512:
-  metadata.gz: a075eee59befc0de0e667d5b4325db8086a457040d544534f75b62d8a05b91a5e703b370bd1f3ce52fe89638cefa93403b1d6acd7170f143a86111a9d4c75277
-  data.tar.gz: 1d3dbb6ead15764e91834af2de5b8cfa9873493830e0cf2cee6080a4884fe3d74476b2a260b47565f6e70c99f5611d9c57bb422950435b80cc90b12eb55bc859
+  metadata.gz: da9407631ff4ec1f734e9e69baf306cace5042f50e473a9d98487629c59109df9bda5e511d15db5db575cebb9e7b95bf02bcc504b8a617a43602e7421a1f1418
+  data.tar.gz: 5d79b77a64ffde8d41933bfaa7946ee550b791f55b7131c6a7057a1caab476164591eb7f2baeaf5285e96f9a7a84b9f30aeeac891196b6d7baa8ac3bafe25b54

data/README.md

@@ -40,7 +40,7 @@ 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`, `/`, `R` or `U`. `Enter`, or a click on a row, switches to the
+`P`, `X`, `Ctrl-x`, `/`, `R`, `U` or `y`, and `s` has no `5`. `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
@@ -50,7 +50,8 @@ It opens when a session starts. To stop that, set
 ## Sections
 
 1. **Pinned.** Rows you pinned with `t`.
-2. **Needs you.** Blocked or failed sessions you haven't attached to yet.
+2. **Needs you.** Blocked or failed sessions, or ones whose pull request has
+   failing checks or changes requested, that you haven't attached to yet.
 3. **Active.** Everything else that's running or not yet settled, including
    interactive terminals.
 4. **Snoozed.** Sorted by wake time. Collapsed.
@@ -59,8 +60,11 @@ It opens when a session starts. To stop that, set
 
 Under each row is what the session is waiting on, what it produced, or its
 status line. A row with a pull request shows it as `#885 open`, `#885 merged`
-and so on. A steady `◌` with `idle · 1 shell` means the agent stopped and is
-waiting on a shell or sub-agent it started.
+and so on, with `✗ checks`, `changes requested` or `conflicts` after it when
+something is wrong. A steady `◌` with `idle · 1 shell` means the agent stopped
+and is waiting on a shell or sub-agent it started. A `●` marks a session you
+haven't attached to since it got blocked, in red, or finished, in blue; one
+you have attached to since is dimmed, unless `/color` tints it.
 
 ## Keys
 
@@ -78,12 +82,13 @@ Vim bindings. Arrows and the mouse work too.
 | `n` | new session |
 | `N` | pair a phone |
 | `t` | pin / unpin |
-| `s` | snooze: `1` 15m · `2` 1h · `3` tomorrow 9am · `4` until woken |
+| `s` | snooze: `1` 15m · `2` 1h · `3` tomorrow 9am · `4` until woken · `5` custom |
 | `u` | wake a snoozed session, or bring back a settled one |
 | `x` | settle by hand |
 | `a` | set a local alias |
 | `o` | open the pull request in the browser |
 | `w` | open the session at claude.ai/code |
+| `y` | copy the pull request url, or the session's address |
 | `P` | link a pull request by hand (empty clears) |
 | `X` | stop the session; `Enter` resumes it later |
 | `Ctrl-x` | delete the session, transcript and worktree for good |
@@ -112,8 +117,8 @@ lists them all.
 A snoozed session wakes when its timer runs out, when you press `u`, or when
 it becomes blocked or failed.
 
-Attaching to a needs-you session moves it to Active until its state changes
-again.
+Attaching to a needs-you session moves it to Active until its state, or its
+pull request's health, changes 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.
@@ -149,6 +154,13 @@ covers ssh, the JSON API and an iOS Shortcut.
 Pull requests show up when a session's transcript links to them. Install
 `gh` to keep their state current. Use `P` to link one by hand.
 
+## Notifications
+
+`--notify` sends a macOS notification through
+[terminal-notifier](https://github.com/julienXX/terminal-notifier) when a
+session needs you or finishes. `brew install terminal-notifier` first;
+the first launch asks permission to notify.
+
 ## Usage bars
 
 The header can show your 5-hour and 7-day rate limit usage:

data/lib/claude_inbox/actions.rb

@@ -74,6 +74,13 @@ module ClaudeInbox
       at.positive? && Time.at(at) >= @clock.call - GRACE
     end
 
+    # A preset by name, or the wake time a typed snooze became, which the
+    # relay sends as the epoch's digits.
+    def snooze_choice(choice)
+      return choice.to_sym if SNOOZES.include?(choice)
+      choice.to_i if choice.is_a?(String) && choice.match?(/\A\d+\z/)
+    end
+
     def apply(store, request, keys)
       id = request["id"]
       return false unless keys.include?(id)
@@ -83,8 +90,9 @@ module ClaudeInbox
       when "pin" then store.toggle_pin(id)
       when "acknowledge" then store.acknowledge(id)
       when "snooze"
-        return false unless SNOOZES.include?(request["choice"])
-        store.snooze(id, request["choice"].to_sym)
+        choice = snooze_choice(request["choice"])
+        return false unless choice
+        store.snooze(id, choice)
       else
         return false
       end

data/lib/claude_inbox/agents_client.rb

@@ -179,7 +179,7 @@ module ClaudeInbox
     # merely flagged: attach lands on the session that asked for it, so there
     # is nothing useful to show or act on directly.
     def classify_origins(sessions)
-      pids = sessions.select { |s| s.interactive? && s.pid }.map(&:pid)
+      pids = sessions.filter_map { |s| s.pid if s.interactive? }
       return sessions if pids.empty?
       rows = ps_rows(pids)
       assign_origins(sessions, origins_from(rows), self.class.bridge_ids(rows))

data/lib/claude_inbox/app/browsing.rb

@@ -3,7 +3,8 @@
 module ClaudeInbox
   class App
     # o opens the selected session's pull request and w its claude.ai/code
-    # page, through whatever opens URLs on this platform.
+    # page, through whatever opens URLs on this platform; y copies the one
+    # of those the session has, or its id.
     module Browsing
       private
 
@@ -19,6 +20,24 @@ module ClaudeInbox
         open_in_browser(url, "claude.ai/code")
       end
 
+      def yank
+        session = selected_session
+        return notice("nothing to copy") unless session
+        text, what = yank_target(session)
+        in_background do
+          @queue << [:notice, @clipboard.call(text) ? "copied #{what}" : "no clipboard tool found"]
+        end
+      end
+
+      # A link set by hand wins over the scan, as it does once the poll lands.
+      def yank_target(session)
+        linked = @store.pr_for(session.key)
+        return [linked, "#" + linked[%r{/pull/(\d+)}, 1]] if linked
+        return [session.pr.url, session.pr.short] if session.pr
+        return [session.remote_url, session.remote_url] if session.remote_url
+        [session.key, session.key]
+      end
+
       def open_in_browser(url, what)
         opener = RUBY_PLATFORM.include?("darwin") ? "open" : "xdg-open"
         notice("opening #{what}")

data/lib/claude_inbox/app/navigating.rb

@@ -63,9 +63,13 @@ module ClaudeInbox
         name if Store::FOLDABLE_SECTIONS.include?(name)
       end
 
+      # Opening lands on the section's first row and closing on its fold
+      # line, rather than leaving the cursor on a stop that just vanished.
       def set_expanded(value)
         name = current_fold_section
-        @expanded[name] = value if name
+        return if name.nil? || !!@expanded[name] == value
+        @expanded[name] = value
+        select(value ? filtered.heads(@expanded).to_h.fetch(name, @selected) : Store::Selection.fold(name))
       end
 
       def toggle_expanded = set_expanded(!@expanded[current_fold_section])

data/lib/claude_inbox/app/triaging.rb

@@ -43,6 +43,7 @@ module ClaudeInbox
       end
 
       def snooze_chosen
+        return @modal = Dialog::Prompt.new(:snooze, @modal.id, "") if @modal.choice == :custom
         @store.snooze(@modal.id, @modal.choice)
         @modal = nil
       end
@@ -63,6 +64,10 @@ module ClaudeInbox
         value = @modal.value.strip
         if @modal.kind == :alias
           @store.set_alias(@modal.id, value)
+        elsif @modal.kind == :snooze
+          wake_at = SnoozeTime.parse(value, Time.now)
+          return notice("try 45m, 2h, 3d, 17:00, 5pm, fri, tomorrow or tonight") unless wake_at
+          @store.snooze(@modal.id, wake_at)
         elsif value.empty? || PullRequests.valid_url?(value)
           @store.set_pr(@modal.id, value)
           @poller.soon

data/lib/claude_inbox/app.rb

@@ -13,11 +13,14 @@ require_relative "remote/listener"
 require_relative "new_session_form"
 require_relative "pull_requests"
 require_relative "reaper"
+require_relative "notifier"
 require_relative "poller"
 require_relative "rate_limits"
 require_relative "session_request"
 require_relative "actions"
+require_relative "clipboard"
 require_relative "snapshot"
+require_relative "snooze_time"
 require_relative "switch"
 require_relative "trust"
 require_relative "mod"
@@ -46,9 +49,11 @@ 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, 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)
+      actions: Actions.disabled, notifier: Notifier.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,
+      clipboard: Clipboard.method(:copy))
       @client = client
+      @clipboard = clipboard
       @store = store
       @snapshot = snapshot
       @switch = switch
@@ -63,7 +68,7 @@ module ClaudeInbox
       @input = Input.new(input, out)
       @queue = queue
       @poller = Poller.new(client: client, store: store, pull_requests: pull_requests,
-        reaper: reaper, queue: @queue, snapshot: snapshot, actions: actions)
+        reaper: reaper, queue: @queue, snapshot: snapshot, actions: actions, notifier: notifier)
       @listener = listen ? Remote::Listener.new(client: client, store: store, queue: @queue, **listen) : Remote::Listener.disabled
       @selected = nil
       @row_items = []
@@ -233,6 +238,7 @@ module ClaudeInbox
       when :link_pr then open_pr_editor
       when :open_pr then open_pr
       when :open_remote then open_remote
+      when :yank then yank
       when :stop then open_confirm(:stop)
       when :delete then open_confirm(:delete)
       when :refresh then @poller.soon

data/lib/claude_inbox/cli.rb

@@ -6,6 +6,7 @@ require_relative "app"
 require_relative "config"
 require_relative "headless"
 require_relative "mod"
+require_relative "notifier"
 require_relative "updater"
 require_relative "writer_lock"
 
@@ -56,9 +57,10 @@ module ClaudeInbox
     def app_options
       opts = options[:fixture] ? fixture_options : live_options
       opts[:color] = options[:color]
+      opts[:notifier] = notifier
       return opts if options[:fixture] || writer_lock.take(role: "inbox")
       opts.merge(store: Store.new(writable: false, relay: Actions.new), reaper: Reaper.disabled,
-        snapshot: Snapshot.disabled, actions: Actions.disabled, pane_offer: Mod::Offer.disabled)
+        snapshot: Snapshot.disabled, actions: Actions.disabled, pane_offer: Mod::Offer.disabled, notifier: Notifier.disabled)
     end
 
     private
@@ -111,7 +113,7 @@ module ClaudeInbox
 
     def headless
       abort "claude-inbox: --headless takes no --fixture" if options[:fixture]
-      Headless.new(client: AgentsClient.new, store: Store.new, updater: updater).run
+      Headless.new(client: AgentsClient.new, store: Store.new, updater: updater, notifier: notifier).run
     end
 
     # Only what a check within the day already found: a cold launch never waits
@@ -154,6 +156,8 @@ module ClaudeInbox
       @updater ||= Updater.new if options[:update_check] && !options[:fixture]
     end
 
+    def notifier = options[:notify] ? Notifier.new : Notifier.disabled
+
     # Held for the life of this process by this reference.
     def writer_lock = (@lock ||= WriterLock.new)
 
@@ -172,6 +176,7 @@ module ClaudeInbox
         p.on("--headless", "Keep the pane's snapshot fresh without a screen") { opts[:headless] = true }
         p.on("--reap", "Delete background sessions idle 14 days") { opts[:reap] = true }
         p.on("--no-color", "Draw without color") { opts[:color] = false }
+        p.on("--notify", "Send a desktop notification when a session needs you or finishes") { opts[:notify] = true }
         p.on("--auto-update", "Install a release found today before launching") { opts[:auto_update] = true }
         p.on("--no-update-check", "Never look for a newer release") { opts[:update_check] = false }
         # --listen-lan wins over --listen, whichever came last.

data/lib/claude_inbox/clipboard.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "subprocess"
+
+module ClaudeInbox
+  # Puts text on the system clipboard through the tool this platform has:
+  # pbcopy on macOS, wl-copy or xclip elsewhere.
+  module Clipboard
+    TOOLS = {"pbcopy" => [], "wl-copy" => [], "xclip" => %w[-selection clipboard]}.freeze
+
+    class Failed < StandardError; end
+
+    module_function
+
+    # True once a tool took the text, false when none is on PATH.
+    def copy(text, platform: RUBY_PLATFORM, path: ENV.fetch("PATH", ""), run: Subprocess.method(:capture))
+      argv = command(platform: platform, path: path)
+      return false unless argv
+      result = run.call(*argv, input: text)
+      raise Failed, "#{File.basename(argv.first)} failed: #{result.err.strip}" unless result.success?
+      true
+    end
+
+    # The argv that writes the clipboard here, or nil without a tool on PATH.
+    def command(platform: RUBY_PLATFORM, path: ENV.fetch("PATH", ""))
+      names = platform.include?("darwin") ? %w[pbcopy] : %w[wl-copy xclip]
+      dirs = path.split(File::PATH_SEPARATOR)
+      names.each do |name|
+        dir = dirs.find { |d| File.executable?(File.join(d, name)) }
+        return [File.join(dir, name), *TOOLS[name]] if dir
+      end
+      nil
+    end
+  end
+end

data/lib/claude_inbox/config.rb

@@ -8,7 +8,7 @@ module ClaudeInbox
   module Config
     PATH = File.join(Dir.home, ".config", "claude-inbox", "config")
 
-    def self.argv(typed, path: PATH)
+    def self.argv(typed, path:)
       args(path) + typed
     end
 

data/lib/claude_inbox/dialog.rb

@@ -32,7 +32,8 @@ module ClaudeInbox
         ["1", "15 minutes", :m15],
         ["2", "1 hour", :h1],
         ["3", "tomorrow 9am", :tomorrow_9am],
-        ["4", "until I wake it", :until_woken]
+        ["4", "until I wake it", :until_woken],
+        ["5", "custom", :custom]
       ].freeze
 
       attr_reader :choice
@@ -118,11 +119,12 @@ module ClaudeInbox
       end
     end
 
-    # `a` alias and `P` pull request: one line of text, read from `value`
-    # once :save comes back. Empty means clear.
+    # `a` alias, `P` pull request and `s` `5` snooze: one line of text, read
+    # from `value` once :save comes back. Empty means clear.
     class Prompt < Dialog
-      TITLES = {alias: " Alias ", pr: " Pull request "}.freeze
-      QUESTIONS = {alias: "  New alias:", pr: "  Pull request URL (empty clears):"}.freeze
+      TITLES = {alias: " Alias ", pr: " Pull request ", snooze: " Snooze "}.freeze
+      QUESTIONS = {alias: "  New alias:", pr: "  Pull request URL (empty clears):",
+                   snooze: "  Wake at (2h, 5pm, fri, tonight):"}.freeze
 
       def initialize(kind, id, value)
         super(kind, id)

data/lib/claude_inbox/headless.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "actions"
+require_relative "notifier"
 require_relative "poller"
 require_relative "pull_requests"
 require_relative "reaper"
@@ -15,13 +16,13 @@ module ClaudeInbox
   # exits at once while an inbox holds the writer lock.
   class Headless
     def initialize(client:, store:, pull_requests: PullRequests.new, actions: Actions.new, snapshot: Snapshot.new,
-      lock: WriterLock.new, updater: nil)
+      lock: WriterLock.new, updater: nil, notifier: Notifier.disabled)
       @lock = lock
       @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, notifier: notifier)
     end
 
     # False when the lock is held, by an inbox or another headless process.

data/lib/claude_inbox/images.rb

@@ -53,7 +53,10 @@ module ClaudeInbox
     end
 
     # ".png", ".jpg", ".gif" or ".webp" by the magic number, or nil.
-    def self.extension(bytes) = MAGIC.find { |_, magic| magic.match?(bytes.b) }&.first
+    def self.extension(bytes)
+      data = bytes.b
+      MAGIC.find { |_, magic| magic.match?(data) }&.first
+    end
 
     CLIPBOARD_PNG = <<~APPLESCRIPT
       on run argv

data/lib/claude_inbox/keymap.rb

@@ -24,7 +24,7 @@ module ClaudeInbox
       "h" => :fold_close,
       "s" => :snooze, "u" => :wake, "a" => :alias, "x" => :settle, "X" => :stop,
       :ctrl_x => :delete,
-      "o" => :open_pr, "P" => :link_pr, "t" => :toggle_pin, "w" => :open_remote,
+      "o" => :open_pr, "P" => :link_pr, "t" => :toggle_pin, "w" => :open_remote, "y" => :yank,
       "R" => :refresh, "U" => :update, "n" => :new_session, "N" => :remote_pairing,
       :tab => :next_section, :back_tab => :prev_section,
       "/" => :filter, :escape => :escape,

data/lib/claude_inbox/mouse.rb

@@ -3,20 +3,20 @@
 module ClaudeInbox
   # Parses SGR mouse reports ("\e[<Cb;Cx;Cy(M|m)", emitted once App turns on
   # \e[?1000h\e[?1006h) into clicks and wheel ticks. Pure: no terminal, no
-  # IO. Row/col are the terminal's own 1-based coordinates, so callers can
-  # index straight into what they just painted.
+  # IO. Row is the terminal's own 1-based row, so callers can index straight
+  # into what they just painted.
   module Mouse
     SEQUENCE = /\e\[<(\d+);(\d+);(\d+)([Mm])/
 
-    Event = Struct.new(:kind, :row, :col)
+    Event = Struct.new(:kind, :row)
 
     # A raw keypress can glue several reports together the same way a fast
     # "esc gg" glues onto one read (see Input#split_keys), so this scans
     # rather than matching once.
     def self.events(raw)
-      raw.scan(SEQUENCE).filter_map do |cb, col, row, type|
+      raw.scan(SEQUENCE).filter_map do |cb, _col, row, type|
         kind = kind_for(cb.to_i, type)
-        Event.new(kind, row.to_i, col.to_i) if kind
+        Event.new(kind, row.to_i) if kind
       end
     end
 

data/lib/claude_inbox/new_session_form.rb

@@ -303,7 +303,7 @@ module ClaudeInbox
 
     def field_label(f)
       on = f.equal?(focused)
-      (on ? @theme.cyan_bold("▶ ") : "  ") + (on ? @p.bold(Text.pad(f.label, 14)) : @p.dim(Text.pad(f.label, 14)))
+      (on ? @theme.yellow_bold("▶ ") : "  ") + (on ? @p.bold(Text.pad(f.label, 14)) : @p.dim(Text.pad(f.label, 14)))
     end
 
     # The cell the cursor sits on, drawn as a block by inverting it: a bar

data/lib/claude_inbox/notifier.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require_relative "notifier_app"
+require_relative "subprocess"
+
+module ClaudeInbox
+  # Desktop notifications for --notify: a row that came to need you or a
+  # background session that finished between one poll and the next, said
+  # through terminal-notifier. `diff` decides, `deliver` says it.
+  class Notifier
+    MISSING = "terminal-notifier not found"
+    # The sections a row is heard from: not snoozed, not settled.
+    WATCHED = %i[pinned needs_you active].freeze
+
+    # Marks the one that wants you, so it stands out from a finished one.
+    BADGE = {"needs you" => "🔴 "}.freeze
+
+    Notification = Data.define(:key, :kind, :label, :line) do
+      def message = "#{BADGE[kind]}#{line ? "#{kind}: #{line}" : kind}"
+    end
+
+    def self.disabled = new(enabled: false)
+
+    # The notifications `after` earns over `before`, two Sections of the same
+    # moment: one per row whose alert changed, with the row's own line. A row
+    # that only changed section has nothing new to say: the first gh refresh
+    # un-settles one whose open PR the cache did not know, and a snoozed
+    # row's timer runs out.
+    def self.diff(before, after)
+      was = alerts(before)
+      rows(after).filter_map do |row|
+        kind = alert(row)
+        Notification.new(key: row.key, kind: kind, label: row.label, line: row.session.summary) if kind && was[row.key] != kind
+      end
+    end
+
+    # key => "needs you", "finished" or nil, over every row, snoozed and settled too.
+    def self.alerts(sections) = sections.all.to_h { |row| [row.key, alert(row)] }
+
+    def self.rows(sections) = WATCHED.flat_map { |name| sections[name] }
+
+    # Interactive sessions stay quiet: you are in that terminal.
+    def self.alert(row)
+      return nil unless row.session.background?
+      if row.session.needs_you? then "needs you" unless row.acknowledged?
+      elsif row.session.effective_state == "done" then "finished"
+      end
+    end
+
+    def initialize(app: NotifierApp.new, run: Subprocess.method(:capture), enabled: true)
+      @app = app
+      @run = run
+      @enabled = enabled
+      @primed = false
+      @given_up = false
+    end
+
+    # Sends what `diff` finds, off the calling thread, and yields the one
+    # notice a binary that will not run earns. The first call only primes,
+    # and readies the app: every row already blocked at startup would
+    # otherwise fire at once.
+    def deliver(before, after, &notice)
+      return unless @enabled
+      return prime unless @primed
+      notifications = self.class.diff(before, after)
+      return if notifications.empty? || @given_up
+      Thread.new do
+        notifications.each do |n|
+          r = @run.call(*@app.command, "-title", n.label, "-message", n.message, "-group", n.key)
+          next if r.success?
+          @given_up = true
+          notice&.call((r.status.exitstatus == 127) ? MISSING : "terminal-notifier: #{r.err.lines.first.to_s.strip}")
+          break
+        end
+      end
+    end
+
+    private
+
+    def prime
+      @primed = true
+      Thread.new { @app.prepare }
+    end
+  end
+end

data/lib/claude_inbox/notifier_app.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require_relative "subprocess"
+
+module ClaudeInbox
+  # A copy of Homebrew's terminal-notifier.app under our own bundle id and
+  # the web app's icon, since macOS draws a notification's icon from the
+  # bundle that sends it and offers no way to override it.
+  class NotifierApp
+    DEFAULT_PATH = File.join(Dir.home, ".config", "claude-inbox", "notifier.app")
+    ID = "dev.claude-inbox.notifier"
+    # Both drawn from remote/icon.svg; the .icns through iconutil, from a
+    # 16-1024px iconset of rsvg-convert renders.
+    ICNS = File.join(__dir__, "remote", "icon.icns")
+    PNG = File.join(__dir__, "remote", "icon.png")
+    # Plain terminal-notifier carries the icon as a thumbnail instead.
+    FALLBACK = ["terminal-notifier", "-contentImage", PNG].freeze
+
+    def self.disabled = new(path: nil)
+
+    def initialize(path: DEFAULT_PATH, run: Subprocess.method(:capture))
+      @path = path
+      @run = run
+    end
+
+    # Builds the copy when terminal-notifier's own app is new to us, and
+    # sends one notification through `open`: macOS asks permission only of
+    # an app LaunchServices started, never of its binary run from a shell.
+    def prepare
+      return unless @path && (app = source) && !current?(app)
+      return unless build(app)
+      @run.call("open", "-n", @path, "--args", "-title", "claude-inbox", "-message", "Notifications active.")
+    end
+
+    # The argv that sends one notification, short of its own flags.
+    def command = (@path && current?(source)) ? [File.join(@path, "Contents", "MacOS", "terminal-notifier")] : FALLBACK
+
+    private
+
+    def source
+      return @source if defined?(@source)
+      r = @run.call("brew", "--prefix", "terminal-notifier")
+      app = File.join(r.out.strip, "terminal-notifier.app") if r.success?
+      @source = (app && File.directory?(app)) ? File.realpath(app) : nil
+    end
+
+    # The copy names the app it came from, whose Cellar path carries the
+    # version, so an upgrade rebuilds it.
+    def current?(app)
+      app && File.read(stamp(@path)) == app
+    rescue SystemCallError
+      false
+    end
+
+    def stamp(bundle) = File.join(bundle, "Contents", "Resources", "source")
+
+    # Built aside and moved into place, so `command` never sees half a copy.
+    def build(app)
+      tmp = "#{@path}.tmp"
+      FileUtils.rm_rf(tmp)
+      FileUtils.mkdir_p(File.dirname(tmp))
+      FileUtils.cp_r(app, tmp)
+      FileUtils.cp(ICNS, File.join(tmp, "Contents", "Resources", "claude-inbox.icns"))
+      File.write(stamp(tmp), app)
+      plist = File.join(tmp, "Contents", "Info.plist")
+      steps = [
+        ["plutil", "-replace", "CFBundleIdentifier", "-string", ID, plist],
+        ["plutil", "-replace", "CFBundleName", "-string", "claude-inbox", plist],
+        ["plutil", "-replace", "CFBundleIconFile", "-string", "claude-inbox", plist],
+        ["codesign", "--force", "--sign", "-", tmp]
+      ]
+      unless steps.all? { |argv| @run.call(*argv).success? }
+        FileUtils.rm_rf(tmp)
+        return false
+      end
+      FileUtils.rm_rf(@path)
+      File.rename(tmp, @path)
+      true
+    end
+  end
+end

data/lib/claude_inbox/poller.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "notifier"
 require_relative "sessions"
 
 module ClaudeInbox
@@ -7,16 +8,16 @@ module ClaudeInbox
   # seconds and on demand, puts what it finds in the store and the snapshot,
   # and tells App over the shared queue: [:sessions] after each
   # hand-over, [:error, msg] when a poll fails, [:notice, text] when the
-  # reaper took something. Between polls it applies what another front end
-  # asked for. Nothing here touches App's state directly; the queue is the
-  # whole of the interface. One worker runs every poll, so two can never
-  # overlap and publish the list out of order.
+  # reaper took something or terminal-notifier is missing. Between polls it
+  # applies what another front end asked for. Nothing here touches App's
+  # state directly; the queue is the whole of the interface. One worker runs
+  # every poll, so two can never overlap and publish the list out of order.
   class Poller
     INTERVAL = 4
     ACTIONS_INTERVAL = 0.5
 
     def initialize(client:, store:, pull_requests:, reaper:, queue:, snapshot:, actions:,
-      interval: INTERVAL, clock: -> { Time.now })
+      notifier: Notifier.disabled, interval: INTERVAL, clock: -> { Time.now })
       @client = client
       @clock = clock
       @store = store
@@ -25,6 +26,7 @@ module ClaudeInbox
       @queue = queue
       @snapshot = snapshot
       @actions = actions
+      @notifier = notifier
       @interval = interval
       @wake = Queue.new
     end
@@ -77,9 +79,15 @@ module ClaudeInbox
 
     private
 
+    # The notifier compares the sections from just before the hand-over, so
+    # a row you woke or unpinned yourself since the last poll says nothing.
     def publish(sessions)
+      now = @clock.call
+      before = @store.sections(now)
       @store.update(sessions)
-      write_snapshot
+      after = @store.sections(now)
+      @snapshot.write(after, now)
+      @notifier.deliver(before, after) { |msg| @queue << [:notice, msg] }
       @queue << [:sessions]
     end