claude-inbox 0.5.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 150bc4c5ae639139680ad48d476e0628faa82e89e77e783fb1ac9b2ac34ab25f
-  data.tar.gz: c40bbe7c0a955ba01edc66014b3b2ff9d8b80eb70d3b6ea4a9345495a69af011
+  metadata.gz: cea52c058efc847eede80d9633f507fb0bcc88352351d2e8df98d57d531cbd57
+  data.tar.gz: 73953113b090f01dfd646bbcb9295be96d2f6616ecccab116b9f75c2f43f69ed
 SHA512:
-  metadata.gz: 1168c17b14d49071580d1c8565eff838a8c5229e339de5cbbd3f90ed78274973cbe1b1b0f3d21b89c4734142029630a1cb9ea8b03932655d22d151a3447faaf8
-  data.tar.gz: 7a6fb8224d67ae2ff94136d9615bb1a5caf12b7430031c5d221fde12a46357aef6f7ffd223f2ab725fb15d3797458ddb7f6cd824d890a01b3b525c0dbc8e3f1b
+  metadata.gz: '080712923012ed2b164ce10dc6e4fbbf511319b7065ee54da07ffac2a6561deb62888f73012d8b7bf1ed3a78ae2d8fae078680fd4102a962bb4a05e345346c77'
+  data.tar.gz: dd9a7ca33067f30d0eb8cb98742bcc229cb981acfdfa0697966d59b43be9cf4c2451a6683378f6389b3226410261d615b9c5fb711df9c1019e659863ca76796c

data/README.md

@@ -18,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:
@@ -26,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
@@ -37,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`, `/` or `R`. `Enter`, or a click on a row, switches to the
+`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
@@ -88,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.
@@ -95,8 +99,9 @@ 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.

data/exe/claude-inbox

@@ -2,95 +2,6 @@
 # frozen_string_literal: true
 
 require "claude_inbox"
+require "claude_inbox/cli"
 
-if ARGV.include?("--version")
-  puts ClaudeInbox::VERSION
-  exit
-end
-
-require "claude_inbox/mod"
-
-# The stable path to the Claude Code pane, for CLAUDE_CODE_PLUGIN_DIRS.
-if ARGV.include?("--mod-dir")
-  puts ClaudeInbox::Mod.link(force: true)
-  exit
-end
-
-if ARGV.first == "install"
-  begin
-    installed = ClaudeInbox::Mod.install(force: ARGV.include?("--force"))
-  rescue JSON::ParserError
-    abort "claude-inbox: ~/.claude/settings.json is not valid JSON, so it was left alone"
-  end
-  installed.removed.each { |dir| puts "Removed #{dir} from ~/.claude/settings.json." }
-  puts "The pane now runs #{ClaudeInbox::Mod::COMMAND || "claude-inbox from your PATH"}." if installed.command_set
-  puts installed.added ? "Added the pane to ~/.claude/settings.json. New Claude Code sessions load it; /inbox opens it." :
-    "The pane is already in ~/.claude/settings.json."
-  exit
-end
-
-require "claude_inbox/app"
-require "claude_inbox/config"
-require "claude_inbox/writer_lock"
-require "tmpdir"
-
-fixture = ARGV.include?("--fixture")
-# A fixture run takes the listen flags, for trying the API with curl, but
-# not the environment or the config file, which are for the real inbox.
-begin
-  argv = fixture ? ARGV : ClaudeInbox::Config.argv(ARGV)
-  listen = ClaudeInbox::Remote::Listener.options(argv, fixture ? {} : ENV)
-rescue ArgumentError => e
-  abort "claude-inbox: #{e.message}"
-end
-
-# Crash traces go here instead of the alt screen when set.
-$stderr.reopen(ENV["CLAUDE_INBOX_STDERR"], "a") if ENV["CLAUDE_INBOX_STDERR"]
-
-opts = {}
-if fixture
-  agents = argv[argv.index("--fixture") + 1]
-  fixtures = File.dirname(agents)
-  opts[:client] = ClaudeInbox::FixtureClient.new(agents, logs: File.binread(File.join(fixtures, "logs_raw.txt")))
-  opts[:store] = ClaudeInbox::Store.new(path: nil)
-  opts[:pull_requests] = ClaudeInbox::PullRequests.new(cache_path: File.join(fixtures, "gh-pr-status-cache.json"), resolved_path: nil, gh: nil)
-  # Its own token, lock and images, so a test inbox can neither rotate the
-  # token phones are paired with nor hold the real inbox's lock.
-  dir = File.join(Dir.tmpdir, "claude-inbox-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, 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] = 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[:listen] = listen
-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)
-end
-
-# The first inbox you can see is the snapshot's writer: a headless one gives
-# way to it, and a second inbox reads along, writing and deleting nothing.
-# Held for the life of this process by this reference.
-writer_lock = fixture ? ClaudeInbox::WriterLock.disabled : ClaudeInbox::WriterLock.new
-unless writer_lock.take(role: "inbox")
-  opts[:store] = ClaudeInbox::Store.new(writable: false, relay: ClaudeInbox::Actions.new)
-  opts[:reaper] = ClaudeInbox::Reaper.disabled
-  opts[:snapshot] = ClaudeInbox::Snapshot.disabled
-  opts[:actions] = ClaudeInbox::Actions.disabled
-end
-# So the pane settings.json names is the installed version's, after a gem update too.
-ClaudeInbox::Mod.link unless fixture
-
-ClaudeInbox::App.new(**opts).run
+exit ClaudeInbox::CLI.new(ARGV).run

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.
@@ -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

@@ -59,17 +59,23 @@ module ClaudeInbox
       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
@@ -239,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)
@@ -275,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
@@ -284,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

@@ -24,6 +24,8 @@ 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
@@ -33,14 +35,17 @@ 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, trust: Trust.method(:projects),
-      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)
@@ -65,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
@@ -83,6 +90,7 @@ module ClaudeInbox
     end
 
     def step(input = nil)
+      check_for_update unless @update_status
       drain_queue
       @logs.tick
       if @resize
@@ -124,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])
@@ -131,8 +140,6 @@ module ClaudeInbox
         when :remote_started then remote_started(*rest)
         end
       end
-    rescue ThreadError
-      nil
     end
 
     # ----- main loop --------------------------------------------------------
@@ -208,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)
@@ -227,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 }
@@ -349,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
@@ -538,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
@@ -576,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/cli.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "tmpdir"
+require_relative "app"
+require_relative "config"
+require_relative "headless"
+require_relative "mod"
+require_relative "updater"
+require_relative "writer_lock"
+
+module ClaudeInbox
+  # What `claude-inbox` does with its arguments: install the pane, update
+  # claude-inbox, or launch the inbox. `run` is true when it succeeded.
+  class CLI
+    USAGE = <<~USAGE
+      Usage: claude-inbox [options]
+             claude-inbox install [--force]
+             claude-inbox update
+    USAGE
+
+    # `lock` stands in for the writer lock a live launch takes.
+    def initialize(argv, env: ENV, config: Config::PATH, lock: nil, out: $stdout)
+      @argv = argv
+      @env = env
+      @config = config
+      @lock = lock
+      @out = out
+    end
+
+    def run
+      case @argv.first
+      when "install" then install
+      when "update" then update
+      else launch
+      end
+    end
+
+    # The launch flags, the config file's before the typed ones. A fixture
+    # run takes the listen flags, for trying the API with curl, but not the
+    # environment or the config file, which are for the real inbox.
+    def options
+      @options ||= begin
+        typed = parse(@argv)
+        options = typed[:fixture] ? typed : parse(Config.argv(@argv, path: @config))
+        env = typed[:fixture] ? {} : @env
+        options.merge(listen: Remote::Listener.options(env, flag: options[:listen], modes: options[:allow_modes]))
+      end
+    rescue OptionParser::ParseError, ArgumentError => e
+      abort "claude-inbox: #{e.message}"
+    end
+
+    # The keywords App is built with. A live launch takes the writer lock
+    # here: the first inbox you can see is the snapshot's writer, and a
+    # second one reads along, writing and deleting nothing.
+    def app_options
+      opts = options[:fixture] ? fixture_options : live_options
+      opts[:color] = options[:color]
+      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)
+    end
+
+    private
+
+    def install
+      force = false
+      subcommand("install") { |p| p.on("--force", "Replace any other copy of the pane") { force = true } }
+      begin
+        installed = Mod.install(force: force)
+      rescue JSON::ParserError
+        abort "claude-inbox: ~/.claude/settings.json is not valid JSON, so it was left alone"
+      end
+      installed.removed.each { |dir| @out.puts "Removed #{dir} from ~/.claude/settings.json." }
+      @out.puts "The pane now runs #{Mod::COMMAND || "claude-inbox from your PATH"}." if installed.command_set
+      @out.puts(installed.added ? "Added the pane to ~/.claude/settings.json. New Claude Code sessions load it; /inbox opens it." :
+        "The pane is already in ~/.claude/settings.json.")
+      true
+    end
+
+    def update
+      subcommand("update")
+      updater = Updater.new
+      begin
+        update = updater.check(force: true)
+      rescue Updater::Error => e
+        abort "claude-inbox: #{e.message}"
+      end
+      unless update
+        @out.puts((updater.kind == :gem) ? "claude-inbox #{VERSION} is the latest release." : "main is up to date.")
+        return true
+      end
+      @out.puts update.installing
+      applied = updater.apply
+      abort "claude-inbox: #{applied.output.strip}" unless applied.success?
+      @out.puts((update.kind == :gem) ? "Installed claude-inbox #{update.latest}." : "main is at #{update.latest}.")
+      true
+    end
+
+    def launch
+      options
+      # Crash traces go here instead of the alt screen when set.
+      $stderr.reopen(@env["CLAUDE_INBOX_STDERR"], "a") if @env["CLAUDE_INBOX_STDERR"]
+      return headless if options[:headless]
+      auto_update if options[:auto_update]
+      # So the pane settings.json names is the installed version's, after a gem update too.
+      Mod.link unless options[:fixture]
+      App.new(**app_options).run
+      true
+    end
+
+    def headless
+      abort "claude-inbox: --headless takes no --fixture" if options[:fixture]
+      Headless.new(client: AgentsClient.new, store: Store.new, updater: updater).run
+    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.
+    def auto_update
+      return unless (update = updater&.cached)
+      @out.puts update.installing
+      applied = updater.apply
+      applied.success? ? updater.relaunch(@argv) : warn("claude-inbox: #{applied.output.strip}")
+    end
+
+    def fixture_options
+      fixtures = File.dirname(options[:fixture])
+      # Its own token, lock and images, so a test inbox can neither rotate the
+      # token phones are paired with nor hold the real inbox's lock.
+      dir = File.join(Dir.tmpdir, "claude-inbox-fixture")
+      {client: FixtureClient.new(options[:fixture], logs: File.binread(File.join(fixtures, "logs_raw.txt"))),
+       store: Store.new(path: nil),
+       pull_requests: PullRequests.new(cache_path: File.join(fixtures, "gh-pr-status-cache.json"), resolved_path: nil, gh: nil),
+       listen: options[:listen]&.merge(fixture: true, pairing: Remote::Pairing.new(path: File.join(dir, "listen.json")),
+         lock_path: File.join(dir, "listen.lock"), images_dir: File.join(dir, "images"))}
+    end
+
+    # 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 here, and only when asked for.
+    def live_options
+      client = AgentsClient.new
+      store = Store.new
+      {client: client, store: store, reaper: options[:reap] ? Reaper.new(client, store) : Reaper.disabled,
+       snapshot: Snapshot.new, switch: Switch.new, actions: Actions.new, pane_offer: Mod::Offer.new,
+       listen: options[:listen], updater: updater,
+       # The typed arguments, not the config's: a relaunch reads the config again.
+       argv: @argv}
+    end
+
+    def updater
+      @updater ||= Updater.new if options[:update_check] && !options[:fixture]
+    end
+
+    # Held for the life of this process by this reference.
+    def writer_lock = (@lock ||= WriterLock.new)
+
+    def parse(argv)
+      opts = {color: true, update_check: true}
+      parser = OptionParser.new(USAGE) do |p|
+        p.on("--version", "Print the version") {
+          @out.puts VERSION
+          exit
+        }
+        p.on("--mod-dir", "Print the pane's directory, for CLAUDE_CODE_PLUGIN_DIRS") {
+          @out.puts Mod.link(force: true)
+          exit
+        }
+        p.on("--fixture PATH", "Read sessions from an agents.json instead of the daemon") { |path| opts[:fixture] = path }
+        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("--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.
+        p.on("--listen[=PORT]", "Let a phone on this Mac start sessions") { |port| opts[:listen] = {lan: false, port: port} unless opts.dig(:listen, :lan) }
+        p.on("--listen-lan[=PORT]", "Let a phone on your network start sessions") { |port| opts[:listen] = {lan: true, port: port} }
+        p.on("--listen-allow-modes=MODES", "The permission modes a phone may start in") { |modes| opts[:allow_modes] = modes }
+      end
+      strictly(parser, argv)
+      opts
+    end
+
+    def subcommand(name)
+      parser = OptionParser.new(USAGE)
+      yield parser if block_given?
+      strictly(parser, @argv.drop(1))
+    rescue OptionParser::ParseError => e
+      abort "claude-inbox #{name}: #{e.message}"
+    end
+
+    # Exact names only, so a typo is an error rather than the flag it abbreviates.
+    def strictly(parser, argv)
+      parser.require_exact = true
+      rest = parser.parse(argv)
+      raise OptionParser::InvalidArgument, rest.first if rest.any?
+    end
+  end
+end

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