claude-inbox 0.1.0 → 0.3.0

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,281 +18,210 @@ 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. `P` toggles it.
-2. **Needs you.** `blocked` or `failed`, unless you've attached to it since (see
-   Acknowledge below).
-3. **Active.** `working`, plus recently finished sessions that have not settled
-   yet, plus interactive sessions, plus a needs-you session you've attached to
-   but that hasn't resolved. Interactive sessions report only `status`, so it
-   gets mapped: busy is working, idle is done, waiting needs you. The JSON calls
-   a terminal you opened yourself, a Remote Control worker, a sub-agent and a
-   headless `claude -p` run all "interactive", each named after its directory;
-   the client tells them apart from the process tree (a remote worker runs with
-   `--sdk-url` under a `claude rc` parent, a sub-agent has a `claude` for a
-   parent, and a headless run gives itself away with `-p` or the SDK's stream
-   flags, since the shell that spawned it hides the session behind it).
-   Sub-agents and headless runs are dropped: nobody is sitting in them and
-   attach lands on whatever asked for them. Remote sessions settle and snooze
-   like any other row. A terminal you are sitting in never settles. Neither
-   can be attached, peeked or stopped from outside; you can land on them, and
-   Enter tells you why nothing happens.
-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 only 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. Whatever the agent is up to, the open work is named
-next to the state: `working · 2 agents`, `idle · 1 shell`. The count comes from
-the session's own job file, which `claude agents --json` does not expose; the
-inbox still takes the state itself from the daemon, the only thing that knows
-whether a session is alive.
-
-Under each row in Pinned, Needs You and Active is the session's own line,
-the one `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. It comes from the job file, like the open work above, so 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 — see
-[Colors](#colors).
+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
 
-Keyboard-first, vim flavoured, but the mouse works too. Arrows work as well
-as `j`/`k`. Clicking a row does what landing on it and pressing `Enter`
-would: selects it and attaches (or expands a fold, or refuses on a terminal
-row you can't be attached to from here). The wheel moves the selection
-rather than uncovering the scrollback behind us, in terminals that report
-mouse events (`\e[?1000h` + `\e[?1006h`, the same mode clicks use) or that at
-least support alternate scroll mode (`\e[?1007h`, wheel-as-arrows only, no
-clicks). Apple Terminal supports neither escape, so there the wheel scrolls
-its own history and clicking a row does 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 |
 |---|---|
 | `j` `k` | move down / up |
 | `gg` `G` | first / last row |
 | `Ctrl-d` `Ctrl-u` | half page down / up (`Ctrl-f` `Ctrl-b` full page) |
-| `Enter` `l` | attach (full-screen handoff; `←` or `Ctrl+Z` return here), or expand Snoozed / Settled |
+| `Enter` `l` | attach (full-screen handoff; `←` or `Ctrl+Z` return here), adopt a remote session, or expand Snoozed / Settled |
 | `Tab` `Shift+Tab` | jump to the next / previous section |
 | `h` | close the peek pane, else collapse the current Snoozed / Settled fold |
 | `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 (full screen): multi-line prompt (`Enter` breaks a line, `Cmd-V` or `Ctrl-V` pastes an image, `Ctrl-S` starts it, `Ctrl-O` starts and opens it), name, directory (`Tab` completes), model, effort, permissions, worktree; "default" choices show what your settings resolve to |
-| `t` | pin / unpin (parks it in Pinned at the top, regardless of state) |
+| `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 |
 | `x` | settle a working or needs-you session by hand (returns when it changes state, unless it just finished) |
 | `a` | set a local alias (never touches the real session name) |
 | `o` | open the session's pull request in the browser |
+| `w` | open the session at claude.ai/code |
 | `P` | link a pull request by hand (empty clears; the scanned links return) |
 | `X` | stop the session (`y` to confirm) |
 | `Ctrl-x` | delete the session for good, conversation and worktree with it (`y` to confirm) |
-| `/` | filter by name or cwd; `Enter` keeps it, `Esc` clears |
+| `/` | filter by name, cwd, the prompt it started from, or what it is doing now; `Enter` keeps it, `Esc` clears |
 | `R` | poll now |
 | `q` | quit |
 
-Bindings live in `ClaudeInbox::Keymap`, a pure resolver with chord support
-that is unit tested on its own. A fast `Esc` followed by a chord key is split
-back into two keys, since tty-reader would otherwise glue them together.
-
-`X` and `Ctrl-x` both ask before they act, 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, and so does our own state entry for
-it, rather than sitting out the seven-day prune. 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. `Tab` / `Shift+Tab` move between fields, `Enter` moves on
-(inside the prompt it breaks a line), `Esc` cancels. Choice fields cycle with
-`h` `l` or the arrows. Text fields are a real editor: `←` `→` move the cursor,
-`Ctrl-A` / `Ctrl-E` jump to the ends, `Backspace` and `Delete` cut either side
-of it, `Ctrl-W` takes the word before it and `Ctrl-U` / `Ctrl-K` everything
-before / after it. The `/` filter, `:` command and alias / PR prompt lines
-are the same editor.
-
-`Ctrl-S` starts the session and drops you back in the inbox; `Ctrl-O` starts it
-and hands the terminal straight over. Either way the new row is selected once
-it shows up. Terminals send the same byte for `Ctrl-S` and `Ctrl-Shift-S`, so
-the second start needs a letter of its own.
-
-The directory defaults to the selected row's. It runs `claude --bg "<prompt>"`
-with only the flags you changed from default, in that directory.
-
-Images work as they do at Claude Code's own prompt. Paste one with `Cmd-V`
-(or `Ctrl-V` in a terminal that doesn't do bracketed paste), or drop a file
-onto the window, and it lands at the cursor as an `[Image #1]` token that
-moves and deletes as one character, so the prompt can point at it: "make the
-button look like [Image #1]". On macOS, `Cmd-Ctrl-Shift-4` copies a region of
-the screen; `n` and `Cmd-V` put it in the prompt. A pasted image is saved
-under `~/.config/claude-inbox/images/` (cleared after 14 days, as sessions
-are); a dropped file is referenced where it is. When the session starts, each
-token becomes an `@path` mention, which `claude` reads as an image the way it
-does at its own prompt. A dropped file that isn't an image, and pasted text,
-stay text, newlines included.
-
-Why the terminal can paste an image at all: with bracketed paste on, a paste
-arrives fenced between `\e[200~` and `\e[201~`, and an image, having no text
-form, arrives as an empty fence. That empty fence is the signal to read the
-clipboard, which is how Claude Code does it too. A dropped file arrives the
-same way, as its shell-escaped path. Reading the clipboard goes through
-`osascript`, so it is macOS only; elsewhere the paste is reported empty.
-
-Slash commands work as they do at Claude Code's own prompt: a prompt that
-starts with one, `/unslop README.md`, is expanded by `claude` into the skill
-with its arguments before the session starts; one further into the text is
-left for the agent to read and act on. Typing `/` at the start of any word
-opens a menu of what the CLI would offer — project and personal skills and
-commands, plugin skills as `plugin:name`, claude.ai's synced skills as
-`anthropic-skills:name` — narrowed as you type, each with the description
-from its front matter. `↑` `↓` choose, `Tab` or `Enter` drop the command in
-with a space after it, `Esc` closes the menu (a second `Esc` cancels the
-form). A `/` inside a word, as in `a/b`, opens nothing, and the menu only
-appears while something matches, so a path like `/Users/…` is left alone
-after its first letters. Built-ins such as `/init` live inside the CLI and
-are not listed; typing one still works. Project commands follow the
-Directory field.
-
-### Why `←` comes back here and not to native agent view
-
-Inside an attached session, `←` on an empty prompt detaches. `claude attach`
-then execs itself in place as `claude agents`, so you would land in the native
-view and only get back to the inbox after quitting that. No flag or setting
-suppresses just that relaunch: the one switch that exists disables `attach`
-too. So the inbox watches its child's command line and, the moment it turns
-into the agents view, terminates it. Measured round trip is about 0.4s and the
-agents view never draws a frame. `Ctrl+Z` is handled locally by the attach
-client and returns directly with no trick needed.
-
-## Rules
-
-All four rules are pure methods on `ClaudeInbox::Store::Row`, a session paired
-with its entry, and are the only place triage logic lives.
-
-**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, whether it settled by hand or because its
-pull request resolved, and puts it wherever its raw state belongs — Active or
-Needs You. It stays there until the state actually changes again.
-
-**Acknowledge.** Attaching to a needs-you session (`Enter`) marks its current
-state seen, moving it to Active instead of leaving it in Needs You. It comes
-back to Needs You the moment its state changes again. Still blocked with a
-new prompt doesn't count, only an actual state change does, same as hand-settle.
-
-**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: working again, blocked,
-or failed. `failed` never settles. A session with no pull request at all
-never settles on its own, however long it has been quiet — `x` is the only
-way in.
-
-A session with a pull request follows the PR instead: it stays Active while
-any of its PRs is open or a draft, however long it has been quiet, and
-settles the moment every one is merged or closed. A PR whose state is not
-known yet (no `gh`, offline) is ignored, so the session stays Active too.
-
-**Reap.** A background session quiet for `REAP_AFTER` (14 days) is deleted
-outright on the next poll: `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, so read the rest of this before you leave it running.
-
-Reaping does *not* key on Settled, deliberately. Settling answers "should I
-still be looking at this?", and the PR rule keeps a row in Active for as long
-as a pull request stays open, so an abandoned draft parks a session there for
-ever and the deadest rows in the list are precisely the ones Settled never
-reaches. Idle time, measured from `state_since`, is the only clock.
-
-Four things are 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. It earns a permanent row because you ought to see it,
-and after a fortnight of not seeing it you never will. A pin or a parked
-snooze ("until I wake it") is the way to keep a session indefinitely; both are
-deliberate gestures, so both outrank the reaper.
-
-Unpushed work is safe without us doing anything. `claude rm` refuses a worktree
-holding commits that aren't pushed and offers a `--discard-unpushed` token to
-override it; nothing here ever passes that token, so a refusal is the end of
-it. Refusals are logged and retried at most once a day.
-
-A session that `claude rm` has taken, by the reaper or by `Ctrl-x`, stays
-hidden for as long as the daemon still lists it; the store drops it from each list in between.
-
-Every reap appends a line to `~/.config/claude-inbox/reaped.log`, which is the
-last record a session existed once its transcript is gone. If that file can't
-be opened the sweep raises and nothing is deleted. `CLAUDE_INBOX_NO_REAP=1`
-turns the whole thing off, and `--fixture` runs never reap.
-
-## Pull requests
-
-Claude Code already links sessions to PRs. The daemon scans each background
-session's transcript for links and writes them to
-`~/.claude/jobs/<id>/state.json` as `children` (`kind: "pr"`); `claude agents
---json` does not expose that, so `JobState` reads the file. It is a link
-scan, so a session that only *reviews* a PR gets it too. Interactive sessions
-have no job file, so for them (or to correct a bad scan) `P` sets the link by
-hand; that lives in our own state file as `pr` and replaces the scanned list.
-
-State is seeded from `~/.claude/gh-pr-status-cache.json`, whatever Claude Code
-last saw, then refreshed with `gh pr view` on the poller thread, at most once a
-minute per PR and never for one already merged or closed. Without `gh` the
-cached state is all you get.
-
-`gh pr view` is a network round trip, so each poll publishes the list first,
-with whatever states are already known, and asks gh afterwards; the rows come
-round again only if an answer moved one. That is why the inbox is up in well
-under a second rather than after a dozen serial `gh` calls. Once gh has said a
-PR is merged or closed the answer is kept in `~/.config/claude-inbox/prs.json`,
-in the same shape as Claude Code's cache, because that cache only covers PRs
-its own sessions opened and a link scan picks up plenty of others — without
-the file every launch would ask about every merged PR again.
-
-Until the first poll lands the body is blank rather than claiming "nothing
-running"; past a second and a half it gets a spinner and a rotating excuse
-with the elapsed time, and past ten seconds a hint to check the daemon.
-
-## Colors
-
-`/color` inside a session is the only way to set one; there is no key for it
-here, and nothing is stored on our side. The daemon writes it to the job file
-as `color`, `claude agents --json` leaves it out, so `JobState` reads it on
-every poll and a color you change shows up on the next one.
-
-It lands on the label and nowhere else. The glyph, the state badge and the PR
-badge keep the colors their own state gives them, so no color you pick can
-stop a blocked session looking blocked. Settled rows stay dim — that section is
-meant to be quiet, and a color shouting out of a collapsed fold would undo it.
-
-The eight colors `/color` offers are mapped the way Claude Code's own tmux
-code maps them when it tints a teammate pane: `red`, `blue`, `green`, `yellow`,
-`purple` and `cyan` go to the terminal's own ansi colors, so they follow your
-theme; `orange` and `pink` have no ansi name and go through 256-color indexes
-208 and 205. Anything else is left unpainted. Colors close with SGR 39
-(default foreground) rather than 0, so a label that is already bold or italic
-stays that way.
-
-## Usage
-
-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 `usage 5h 24% · 7d 41%`.
-It needs 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:
+`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 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
+
+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. It doesn't scan interactive
+sessions. Use `P` to link one by hand, or to fix a bad scan.
+
+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.
+
+## Usage bars
+
+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 `/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 lines in
+the script, just after it reads stdin:
 
 ```bash
 input=$(cat)
@@ -300,143 +229,13 @@ 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.
-
-The label stays off until the file exists, and goes off again once the file
-is more than fifteen minutes old.
+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.
 
-## State
+The bars stay hidden until the file exists, and hide again once it's more
+than fifteen minutes old.
 
-`~/.config/claude-inbox/state.json`, keyed by session id, atomic writes.
-Holds `wake_at`, `snoozed_at`, `alias`, `pr`, `pinned`, `pinned_at`, `settled_at`, `acknowledged_at`, `revived_at`, `last_state`, `state_since`, `last_seen`,
-and `reap_failed_at` / `reap_error` for a session `claude rm` has refused.
-`Store::Entry` is where those names live; everything else reads an entry
-through it. Entries not seen in a poll for 7 days are pruned. Pruning only reaches entries
-the daemon has *forgotten*, which is a different thing from the reaper: the
-daemon still lists sessions a month old, so those keep their entry and it is
-the 14-day reap that clears them.
-
-## Layout
-
-```
-Sessions.load: AgentsClient → JobState → PullRequests  →  Poller  →  Store  →  Renderer  →  App
-               (shells out)   (jobs dir)  (known states)  (thread, then gh)  (pure)  (strings)  (terminal + key loop)
-```
-
-- `AgentsClient` is the only thing that runs `claude`. `FixtureClient` swaps in a JSON file.
-- `Sessions.load` is the one place the list is put together: `AgentsClient`,
-  then `JobState`, then `PullRequests#enrich`, in that order because the links
-  `PullRequests` wants are the ones `JobState` read. `Session` is immutable; a
-  step that adds something hands back a copy.
-- `JobState` reads `~/.claude/jobs/<id>/state.json`, the daemon's own file: the scanned
-  links `PullRequests` wants, the open work behind a `working` state, the session's
-  own line (`detail`, `needs`, `output.result`) and the `/color` each session carries. Never cached. `enrich` returns each background session
-  with its file attached, for `Sessions.load`.
-- `PullRequests` pairs each session with the PRs its `job_state` links and keeps
-  their state fresh through `gh`. `enrich` never asks gh and runs inside
-  `Sessions.load`; `refresh` is the slow half and runs after the list has gone
-  up. `--fixture` points it at `test/fixtures/jobs` with `gh` off.
-- `Palette` maps a session color to an escape sequence and knows nothing else.
-- `RateLimits` reads `~/.claude/rate_limits.json`, the file a status line script writes, and gives the header its usage label. Nil without the file.
-- `Store` holds the last poll and the entry table behind a mutex, and folds each poll in.
-  A key it was told to `hide` or `forget` stays out of every poll until it is released or the daemon stops listing it.
-  `Store::Entry` is what is remembered about one session, and the only place the state file's key names appear.
-  `Store::Row` is one session with its entry, and the rules are its methods.
-  `Store::Sections` is one poll sorted into sections and knows where the cursor can land: the `/` filter, the fold-or-rows rule and which section a key is in live there.
-- `Renderer` turns sections into an array of fixed-width strings. `Painter` diffs frames
-  and repaints only changed rows.
-- `Reaper` runs `claude rm` over whatever `Row#reapable?` picks and appends a
-  line to the log for each one. `due` names them without touching anything;
-  `sweep` does the deleting. Both run on the poller, and the list goes up
-  between them with the rows `due` named hidden in the store, so a slow `rm`
-  stalls neither a frame nor the first one and a row never paints while it is
-  being deleted.
-- `Poller` is the thread that asks `Sessions.load` for the list, every four
-  seconds and on demand, runs it past the `Reaper` and then the gh refresh,
-  and hands each result to `App` over a queue. An on-demand poll queues onto
-  that same thread rather than racing it, so a burst of them while it is idle
-  is one `claude agents` call, one that lands mid-poll is a single follow-up,
-  and no two polls overlap. `App` pauses it while `claude
-  attach` has the terminal.
-- `Terminal` is the screen: the alt screen with its mouse and wheel modes, raw
-  mode, the cached size and the `Painter` that diffs frames onto it. `release`
-  lends it to `claude attach` and takes it back.
-- `App` owns the key loop, the poller thread and the logs thread, and is the
-  only place that spawns a child.
-- `Peek` is the peek pane: whether it is open, how far back it is scrolled and
-  what to paint for the selected row. `Logs` is where the lines come from: the
-  `claude logs` replay of each session, fetched off the main thread, debounced
-  and cached.
-- `VtScreen` is a small cursor-addressed grid used to turn the `claude logs` replay
-  into readable lines for the peek pane.
-- `SlashCommands` reads the skills and commands `claude` would offer from the
-  same directories it reads them, front matter included, for the new-session
-  prompt's menu. Pure filesystem; it never runs `claude`.
-- `Dialog` is a box over the list that claims every key until it answers:
-  the snooze menu, the stop and delete confirms, the alias and pull request
-  prompts. Pure, like `NewSessionForm`; `App` acts on the answer.
-- `Mouse` turns the SGR escape sequences the terminal sends for clicks and
-  wheel ticks into `Event`s; `App` maps a click's row back to whatever
-  `Renderer` painted there.
-
-## Things learned from the real CLI (2.1.273)
-
-- Terminal.app puts the tty's active process in the tab title, so a poller that
-  forks `claude` every few seconds makes the title flicker. Every helper
-  subprocess here is started with `setsid` so it has no controlling tty.
-
-- `claude agents --json --all` matches the documented shape exactly. A `done`
-  session can still carry a `pid` and `status: idle`.
-- `claude logs <id>` is **not** plain text. It is a replay of the session's terminal
-  output: cursor positioning, erase-line, color. Words are frequently separated by
-  cursor motion rather than spaces, so stripping escapes yields run-together garbage.
-  Feeding it through a screen grid produces readable text.
-- `claude logs` fails with "job not found" for a finished session whose process the
-  supervisor has reaped. The peek pane shows a notice instead.
-- `claude attach --help` says `←` returns to agent view and `Ctrl+Z` drops to the
-  shell. Under the hood `←` makes the attach process exec `claude agents` in place,
-  same pid, using its own executable path, so a PATH shim never sees it.
-- `CLAUDE_CODE_DISABLE_AGENT_VIEW=1` disables `agents`, `attach` and `logs` alike.
-- A prompt beginning with a slash command is expanded, `$ARGUMENTS` and all,
-  in `-p` and `--bg` alike (checked on 2.1.274 with a project command).
-  Installed plugins are listed in `~/.claude/plugins/installed_plugins.json`,
-  keyed `name@marketplace`, each pointing at its `installPath`; claude.ai's
-  synced skills sit in `~/.claude/skills/synced/<bucket>/<name>/SKILL.md`
-  and show up as `anthropic-skills:<name>`.
-- Interactive sessions (a `claude` you started in a terminal yourself) appear in
-  the JSON with no `id` and no `state`, only `status`, and cannot be attached,
-  peeked or stopped from outside.
-- `~/.claude/jobs/<id>/state.json` is where the daemon keeps what the JSON
-  leaves out: `children` (scanned PR and issue links), `intent`, `worktreePath`,
-  `worktreeBranch`, token count and the transcript path, plus the line the
-  agents view prints under a row: `detail` is the session's status line,
-  `needs` what it is waiting on while blocked, `output.result` its closing
-  summary once done. `~/.claude/gh-pr-status-cache.json`
-  is keyed by PR url and calls an open draft `DRAFT`; `gh pr view` reports
-  `OPEN` plus `isDraft`.
-
-- The job file is also where `/color` ends up, as `color`. `claude agents --json`
-  does not carry it, so a color is only ever visible by reading the file. The CLI
-  offers eight, and its own tmux code is the authority on what they mean to a
-  terminal: six are ansi names, `orange` and `pink` are 256-color indexes 208 and
-  205. Interactive sessions have no job file and so never have a color.
-
-## Development
-
-```
-bundle install
-bin/ci                       # full signoff: lint, gem audit, tests (see CONTRIBUTING.md)
-bin/release --dry-run        # the version the commits since the last tag call for
-bundle exec rake test        # minitest/spec, test/**/*_spec.rb
-bundle exec standardrb
-CLAUDE_INBOX_STDERR=/tmp/err.log bin/claude-inbox   # crash traces off the alt screen
-DEBUG=1 bin/claude-inbox                            # slow-frame notes in /tmp/inbox-debug.log
-CLAUDE_INBOX_NO_REAP=1 bin/claude-inbox             # never delete an idle session
-bin/screens                                         # drive the fixture in a pty, print every screen
-```
+## Contributing
 
-`bin/screens` is how a refactor is checked against the real screen: run it on
-`main` and on the branch and diff the two.
+See [CONTRIBUTING.md](CONTRIBUTING.md).