claude-inbox 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 76328d9652ac26483494547c0b26c4099a5c8996816743c9b88b21dfebff0def
-  data.tar.gz: 15d80ce8e007a533cf70fe35a6215d148fe9f48925fb9b51b50a9913f43ebc9c
+  metadata.gz: 7fc36460c912469438541ba91cd22f8c3635bb3fd80b60b695afe148f8230ee0
+  data.tar.gz: 105f161459cb30bd1d3751e2a3c926225e5087279b9056bafee46474542bca0f
 SHA512:
-  metadata.gz: 7cd8965adf8b34a34b8ee2fb412b8742d3457e2616cc3a0de549f4a9ee7b5fd9385635445e56bf6de37f3eef43da85ce5456df52da0319ac4a2312e223b872ed
-  data.tar.gz: 39c760a37be19c854d69c98b8e429fa5fcc48ab4bbfe03c00033e78bd217c161a29051074e70dbb98db234d1913f2320187eafcfabb68396a96a95c8eee1f0a3
+  metadata.gz: f31e385cff9fb60a06e7bcce8ba965398491ea65c2792ce9d609654a1d0fc5b417dcd147c0962145badf49da6bb0de734a4bcbae75c7055dbb57ec6090889087
+  data.tar.gz: 889b409820e77ec9d6b4a51de365f3524eac013b55131ac8de4d2b0eae9e573ab11c9a12c5240aea0ef40c74211893240adc22283a439f187668ce48949766ce

data/README.md

@@ -1,9 +1,9 @@
 # claude-inbox
 
-Inbox-style triage on top of Claude Code's background sessions. A companion to
-`claude agents`, not a replacement: it reads the same daemon state through
-`claude agents --json` and adds snooze, auto-settle and the session's pull
-request.
+Inbox-style triage for Claude Code's background sessions. It reads the same
+daemon state as `claude agents`, through `claude agents --json`, and adds
+snooze, auto-settle and each session's pull request. Use it next to
+`claude agents`, not instead of it.
 
 ![claude-inbox with one working session, one snoozed and the settled section folded](docs/screenshot.png)
 
@@ -18,51 +18,46 @@ Requires Ruby 3.2+ and a `claude` on PATH with the agents feature. Versions
 are published to rubygems and listed under GitHub Releases.
 `claude-inbox --version` prints the installed version.
 
+Put arguments you want on every launch in `~/.config/claude-inbox/config`.
+
 ## Sections
 
-1. **Pinned.** Parked at the top by hand, regardless of state. `t` toggles it.
-2. **Needs you.** `blocked` or `failed`, until you attach to it (see
-   Acknowledge below).
-3. **Active.** `working`, recently finished sessions that haven't settled yet,
-   interactive sessions, and a needs-you session you've attached to that
-   hasn't resolved. Interactive sessions report only `status`, so it gets
-   mapped: busy is working, idle is done, waiting needs you. The daemon calls
-   a terminal you opened yourself, a Remote Control worker, a sub-agent and a
-   headless `claude -p` run all "interactive"; the inbox tells them apart from
-   the process tree. Sub-agents and headless runs are dropped, since nobody is
-   sitting in them. Remote sessions settle and snooze like any other row,
-   and Enter pulls one into the daemon (see Remote Control below). A
-   terminal you are sitting in never settles and can't be attached, peeked
-   or stopped from outside; Enter tells you so.
-4. **Snoozed.** Sorted by wake time, parked ("until I wake it") entries last.
-   Collapsed; Enter expands.
-5. **Settled.** Parked with `x`, or whose pull request is merged or closed.
-   Collapsed; Enter expands.
-
-A row with a pull request shows it after the state: `#885 open`, `#885 draft`,
-`#885 merged`, `#885 closed`. `o` opens it in the browser.
-
-`working` from the daemon covers two situations, and the row says which. A
-spinner and `working` mean the agent is thinking. A steady `◌` and `idle · 1
-shell` mean the agent has stopped and is waiting on work it started, such as a
-`--watch` shell or a sub-agent. That is why a session with nothing left to do
-can sit there for an hour. The open work is named next to the state either
-way: `working · 2 agents`, `idle · 1 shell`.
-
-Under each row in Pinned, Needs You and Active is the line `claude agents`
-prints too: what it is waiting on while blocked (`↳ confirm: drop the top
-line?`), what it produced once done, otherwise its status line. A terminal you
-opened yourself has none and shows its directory instead.
-
-A session you gave a color to with `/color` wears it on the label. Nothing
-else is tinted, so a blocked session still looks blocked.
+1. **Pinned.** Parked at the top by hand, whatever its state. `t` toggles it.
+2. **Needs you.** `blocked` or `failed`, until you attach to it.
+3. **Active.** `working`, finished but not yet settled, interactive, or a
+   needs-you session you attached to that hasn't resolved. An interactive
+   session only reports busy, idle or waiting, which show as working, done
+   and needs you. A terminal you're sitting in never settles and can't be
+   attached, peeked or stopped from here. Sub-agents and headless `claude -p`
+   runs don't show up at all.
+4. **Snoozed.** Sorted by wake time, with "until I wake it" entries last.
+   Collapsed. Enter expands it.
+5. **Settled.** Settled with `x`, or every pull request is merged or closed.
+   Collapsed. Enter expands it.
+
+A row with a pull request shows it after the state, as `#885 open`,
+`#885 draft`, `#885 merged` or `#885 closed`. `o` opens it in the browser.
+
+The daemon's `working` covers two cases, and the row tells them apart. A
+spinner and `working` mean the agent is thinking. A steady `◌` and
+`idle · 1 shell` mean it stopped and is waiting on something it started, such
+as a `--watch` shell or a sub-agent. That's why a session with nothing left to
+do can sit there for an hour.
+
+Under each row in Pinned, Needs you and Active is the same line
+`claude agents` prints. While blocked it's what the session waits on
+(`↳ confirm: drop the top line?`), once done it's what it produced, and
+otherwise it's the status line. A terminal you opened yourself has none, so
+it shows its directory.
+
+A session you gave a color with `/color` wears it on the label. Nothing else
+is tinted, so a blocked session still looks blocked.
 
 ## Keys
 
-Vim bindings; arrows work as well as `j`/`k`. The mouse works too, in
-terminals that report it: clicking a row selects and attaches, and the wheel
-moves the selection. Apple Terminal reports neither, so there the wheel
-scrolls its own history and clicks do nothing.
+Vim bindings. Arrows work as well as `j`/`k`. In terminals that report the
+mouse, a click selects and attaches and the wheel moves the selection. Apple
+Terminal reports neither.
 
 | Key | Action |
 |---|---|
@@ -75,7 +70,8 @@ scrolls its own history and clicks do nothing.
 | `za` `zo` `zc` | toggle / open / close the Snoozed or Settled fold under the cursor |
 | `p` | toggle the read-only peek pane |
 | `J` `K` (`Ctrl-e` `Ctrl-y`) | scroll the peek pane |
-| `n` | new session (see below) |
+| `n` | new session |
+| `N` | pair a phone: whether the inbox is listening, and the URL to pair with |
 | `t` | pin / unpin |
 | `s` | snooze: `1` 15m · `2` 1h · `3` tomorrow 9am · `4` until woken |
 | `u` | wake a snoozed session now, or bring back one you settled |
@@ -90,129 +86,142 @@ scrolls its own history and clicks do nothing.
 | `R` | poll now |
 | `q` | quit |
 
-`X` and `Ctrl-x` both ask first, and both take `y`, but they are not the same
-thing. `X` runs `claude stop`: the process ends, the conversation is kept, and
-`Enter` resumes it later. `Ctrl-x` runs `claude rm`: the session, its
-transcript and its worktree all go. Nothing resumes afterwards, so read the
-box before answering.
+`X` and `Ctrl-x` both ask first and both take `y`, but they do different
+things. `X` runs `claude stop`, which ends the process and keeps the
+conversation, and `Enter` resumes it later. `Ctrl-x` runs `claude rm`, which
+deletes the session, its transcript and its worktree. Nothing resumes after
+that, so read the box before answering.
 
 ### New session
 
-`n` opens a form: prompt, name, directory, model, effort, permissions,
-worktree, Remote Control. `Tab` / `Shift+Tab` move between fields, `Esc` cancels. Choice
-fields cycle with `h` `l` or the arrows; "default" shows what your settings
-resolve to. The directory defaults to the selected row's, and `Tab` completes
-it.
-
-`Ctrl-S` starts the session and drops you back in the inbox; `Ctrl-O` starts
-it and attaches. Either way the new row is selected once it shows up. It runs
-`claude --bg "<prompt>"` in that directory, with only the flags you changed.
-
-The prompt is multi-line; `Enter` breaks a line. Paste an image with `Cmd-V`
-(or `Ctrl-V`), or drop a file onto the window, and it lands at the cursor as
-an `[Image #1]` token the prompt can point at: "make the button look like
-[Image #1]". Pasted images are saved under `~/.config/claude-inbox/images/`
-for 14 days; a dropped file is referenced where it is. Reading the clipboard
-is macOS only.
-
-Remote Control set to yes starts the session with `--remote-control`, so it
-runs under the daemon like any other row and is also listed at claude.ai/code
-and in the Claude mobile app. See Remote Control below.
-
-Slash commands work as at Claude Code's own prompt. Type `/` at the start of a
-word for a menu of your skills and commands, plugin skills as `plugin:name`,
-claude.ai's synced skills as `anthropic-skills:name`. `↑` `↓` choose, `Tab` or
-`Enter` insert, `Esc` closes the menu. Built-ins such as `/init` aren't listed
-but still work.
+`n` opens a form with prompt, name, directory, model, effort, permissions,
+worktree and Remote Control. `Tab` and `Shift+Tab` move between fields and
+`Esc` cancels. Choice fields cycle with `h` `l` or the arrows, and "default"
+shows what your settings resolve to. The directory starts as the selected
+row's, and `Tab` completes it.
+
+`Ctrl-S` starts the session and drops you back in the inbox. `Ctrl-O` starts
+it and attaches. It runs `claude --bg "<prompt>"` in that directory with only
+the flags you changed, and the new row is selected once it shows up.
+
+The prompt is multi-line, and `Enter` breaks a line. Paste an image with
+`Cmd-V` (or `Ctrl-V`) or drop a file on the window, and an `[Image #1]` token
+lands at the cursor for the prompt to point at: "make the button look like
+[Image #1]". Pasted images are kept in `~/.config/claude-inbox/images/` for
+14 days. A dropped file is referenced where it is. Pasting images works on
+macOS only.
+
+Remote Control set to yes adds `--remote-control`, so the session also shows
+up at claude.ai/code and in the Claude mobile app. It defaults to yes when
+"Enable Remote Control for all sessions" is on in `/config`.
+
+Type `/` at the start of a word for a menu of your skills and commands.
+Plugin skills appear as `plugin:name` and claude.ai's synced skills as
+`anthropic-skills:name`. `↑` `↓` choose, `Tab` or `Enter` insert, `Esc`
+closes the menu. Built-ins such as `/init` aren't listed but still work.
 
 ## How sessions move
 
-**Wake.** A snoozed session returns when its timer elapses, when you press
-`u`, or when it becomes blocked or failed after being snoozed. A session that
-was already blocked when you snoozed it stays snoozed; that is the point of
-snoozing. `u` also brings back a settled row and puts it wherever its raw
-state belongs.
-
-**Acknowledge.** Attaching to a needs-you session marks its current state
-seen and moves it to Active. It comes back to Needs You when its state
-changes again. Still blocked with a new prompt doesn't count.
-
-**Settle.** Settled by hand with `x`, or because every pull request it has is
-merged or closed. A hand-settled session stays put when it finishes, and
-returns as soon as it changes state in any other way. `failed` never settles.
-A session with no pull request never settles on its own, however long it has
-been quiet. A session with one stays Active while any of its PRs is open or a
-draft.
-
-**Reap.** A background session quiet for 14 days is deleted on the next poll
-with `claude rm`, so the transcript and the worktree go with it, same as
-`Ctrl-x`. This is the one thing here that destroys anything without asking
-first. Reaping does not key on Settled: an open draft keeps a row in Active
-for ever, and those are precisely the rows that need reaping. Idle time is the
-only clock.
-
-Never reaped, whatever the clock says: a `working` session, one that still
-holds a process, a pin, and a snooze. `failed` is reaped, even though it never
-settles; after a fortnight of not looking at it you never will. A pin or a
-parked snooze is the way to keep a session indefinitely.
-
-Unpushed work is safe. `claude rm` refuses a worktree holding commits that
-aren't pushed, and nothing here ever overrides that refusal. Every reap
-appends a line to `~/.config/claude-inbox/reaped.log`, the last record a
-session existed once its transcript is gone. `CLAUDE_INBOX_NO_REAP=1` turns
-reaping off.
+**Wake.** A snoozed session comes back when its timer runs out, when you
+press `u`, or when it turns blocked or failed after you snoozed it. One that
+was already blocked when you snoozed it stays snoozed, which is the point of
+snoozing. `u` also brings back a settled row.
+
+**Acknowledge.** Attaching to a needs-you session marks its state seen and
+moves it to Active. It returns to Needs you when its state changes again. A
+new prompt while still blocked doesn't count.
+
+**Settle.** A session settles when you press `x` or when every pull request
+it has is merged or closed. A hand-settled session stays put when it
+finishes, and comes back on any other state change. `failed` never settles.
+A session with no pull request never settles on its own, and one with an
+open or draft PR stays Active.
+
+**Reap.** On the next poll, the inbox deletes a background session that has
+been quiet for 14 days with `claude rm`, transcript and worktree included.
+It's the one thing here that deletes without asking. Reaping ignores Settled,
+because an open draft keeps a row in Active for ever and those are exactly
+the rows that need reaping. Idle time is the only clock.
+
+The inbox never reaps a `working` session, one that still holds a process, a
+pinned one or a snoozed one. It does reap `failed`, even though failed never
+settles. After a fortnight of not looking at it, you won't. Pin or park a
+session to keep it.
+
+Unpushed work is safe, because `claude rm` refuses a worktree with unpushed
+commits and the inbox never overrides that. Every reap adds a line to
+`~/.config/claude-inbox/reaped.log`. `CLAUDE_INBOX_NO_REAP=1` turns reaping
+off.
 
 ## Remote Control
 
-Every background session has a page at claude.ai/code, where you can follow
-it from a browser or the Claude mobile app; `w` opens it. A session with
-Remote Control on can also be driven from there, the way `claude
---remote-control` and `/rc` allow in a terminal. Its row wears a `⇅` after
-the state. Two kinds of session have it:
-
-- A background session the `n` form started with Remote Control set to yes,
-  or one you ran as `claude --bg "…" --remote-control` yourself. It is a
-  daemon row like any other: `Enter` attaches, `X` stops, and it keeps its
-  Remote Control across a stop and a wake, since the daemon saves the flag.
-- A worker a `claude remote-control` server spawned for a request from your
-  phone. That is how a session started away from the desk lands on this
-  machine. The daemon calls it interactive and can't attach to it, so
-  `Enter` offers to adopt it instead: `y` ends the worker and resumes the
-  conversation as a background session under the same id, with Remote
-  Control on, and attaches. The phone session you were in ends there and a
-  new one takes its place, with the whole conversation; the server keeps
-  running for the next request. A worker nobody has messaged yet has
-  nothing to adopt, and Enter says so.
+A session with Remote Control on has a page at claude.ai/code, where you can
+follow and drive it from a browser or the Claude mobile app. `w` opens it,
+and the row shows `⇅` after the state. Two kinds of session have it.
+
+- A background session started with Remote Control on, from the `n` form or
+  as `claude --bg "…" --remote-control`. It behaves like any other row, and
+  keeps Remote Control across a stop and a resume.
+- A worker a `claude remote-control` server spawned when you started a
+  session from your phone. The daemon can't attach to it, so `Enter` offers
+  to adopt it. `y` ends the worker, resumes the conversation as a background
+  session under the same id with Remote Control on, and attaches. The phone
+  session you were in ends and a new one with the whole conversation takes
+  its place. The server keeps running. A worker nobody has messaged yet has
+  nothing to adopt.
+
+## Starting sessions from your phone
+
+With `--listen-lan`, a phone on your Wi-Fi or VPN can start sessions the way
+`n` does. It's off unless you ask for it.
+
+![The inbox beside the phone form, pairing and then starting a session](docs/remote-start.gif)
+
+1. Start the inbox with `claude-inbox --listen-lan`, or put `--listen-lan`
+   in `~/.config/claude-inbox/config` or `export CLAUDE_INBOX_LISTEN=lan` in
+   your shell rc.
+2. Press `N`, then `c` to copy the pairing URL. Universal Clipboard takes it
+   to the phone.
+3. Open it in Safari. To keep it, tap Share, then Add to Home Screen.
+4. Open the new Inbox icon. It has its own storage, apart from Safari's, so
+   paste the pairing URL once more and tap Pair.
+
+LAN mode is plain HTTP, so the token and every prompt cross the network
+readable by anyone on it. Use it only on a network you control. Anyone with
+the token can start sessions as you in your projects. If the URL leaks, press
+`r` in the `N` dialog to replace it.
+
+A remote start may use the `default`, `auto` and `plan` permission modes.
+[docs/remote-start.md](docs/remote-start.md) covers the rest, including ssh,
+the firewall prompt, the JSON API and an iOS Shortcut.
 
 ## Pull request state
 
 The daemon scans each background session's transcript for PR links, so a
-session that only reviews a PR gets it too. Interactive sessions aren't
-scanned; `P` sets the link by hand for those, or to correct a bad scan.
+session that only reviews a PR gets it too. It doesn't scan interactive
+sessions. Use `P` to link one by hand, or to fix a bad scan.
 
-State comes from whatever Claude Code last saw, then `gh pr view` on the
-poller thread, at most once a minute per PR. Without `gh` the cached state is
-all you get. The list goes up before gh is asked, so the inbox is up in under
-a second.
+The state comes from Claude Code's own cache, then from `gh pr view` at most
+once a minute per PR. Without `gh`, you only get the cached state.
 
-## Setup
+## Usage bars
 
-The right end of the header shows how much of your Claude subscription's
-5-hour and 7-day rate limit windows you have used, as a ten-cell bar per
-window that turns yellow at 70% and red at 90%, like the context bar many
-status lines draw:
+The right end of the header shows how much of your 5-hour and 7-day rate
+limit windows you've used. Each is a ten-cell bar that turns yellow at 70%
+and red at 90%.
 
 ```
 session ██░░░░░░░░ 24% · 3h left  week ████░░░░░░ 41% · 2d left
 ```
 
-`session` is the 5-hour window and `week` the 7-day one, as Claude's own
-`/usage` names them; `3h left` is how long until that window resets. It needs
-a Pro or Max account and a one-time setup.
+`session` is the 5-hour window and `week` the 7-day one, as `/usage` names
+them. `3h left` is the time until that window resets. The bars need a Pro or
+Max account and a one-time setup.
 
-Claude Code passes the numbers to your [status line](https://code.claude.com/docs/en/statusline)
-script every turn, and the inbox reads them from a file that script writes.
-Put these two lines in the script, just after it reads stdin:
+Claude Code passes the numbers to your
+[status line](https://code.claude.com/docs/en/statusline) script every turn,
+and the inbox reads them from a file that script writes. Put these lines in
+the script, just after it reads stdin:
 
 ```bash
 input=$(cat)
@@ -220,13 +229,12 @@ limits=$(echo "$input" | jq -c '.rate_limits // empty')
 [ -n "$limits" ] && echo "$limits" > ~/.claude/rate_limits.json.tmp && mv ~/.claude/rate_limits.json.tmp ~/.claude/rate_limits.json
 ```
 
-If you have no status line script, run `/statusline` in any session and it
-writes one for you, then add the lines to that. Keep the `-n` check: a
-session's first status line run has no numbers yet, and writing anyway would
-blank the file.
+With no status line script, run `/statusline` in any session to get one,
+then add the lines. Keep the `-n` check. A session's first status line run
+has no numbers yet, and writing anyway would blank the file.
 
-The bars stay off until the file exists, and goes off again once the file
-is more than fifteen minutes old.
+The bars stay hidden until the file exists, and hide again once it's more
+than fifteen minutes old.
 
 ## Contributing
 

data/exe/claude-inbox

@@ -9,24 +9,43 @@ if ARGV.include?("--version")
 end
 
 require "claude_inbox/app"
+require "claude_inbox/config"
+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 (i = ARGV.index("--fixture"))
-  agents = ARGV[i + 1]
+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. Everything else — tests, --fixture,
-  # anything embedding App — gets one that deletes nothing.
+  # 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[:listen] = listen
 end
-opts[:color] = false if ARGV.include?("--no-color")
+opts[:color] = false if argv.include?("--no-color")
 
 ClaudeInbox::App.new(**opts).run

data/lib/claude_inbox/agents_client.rb

@@ -46,7 +46,7 @@ module ClaudeInbox
     # 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)
+      pid = Process.spawn(*Subprocess.command(@bin, "attach", id))
       watchdog = Thread.new { kill_when_agents_view(pid) }
       _, status = Process.wait2(pid)
       status
@@ -64,10 +64,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 +72,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 +96,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 +107,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 +168,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 +191,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))
@@ -220,8 +218,6 @@ module ClaudeInbox
       }
     end
 
-    private
-
     def kill_when_agents_view(pid)
       loop do
         sleep WATCH_INTERVAL
@@ -243,6 +239,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.