The picker

The picker is the front door and the only screen you need. It lists the sessions one factory owns: its reception, its gaffer, and the workers that gaffer dispatched. Each row carries the signals that matter for agent work: which are streaming output (●) and which are idle (○), a ! on anything in trouble and a ? on anything waiting for an answer from you, the plan step the session is working, and what it is doing this second. Your own shells are not on it, because a list you have to read past is one you stop reading.

acme   ↵ attach   ^d details   ^g tell gaffer   ^x stop one   ·   type to filter

💁 reception      the front desk — ask anything
── sub-agents ──
●  gaffer-acme          acme                          claude  working   dispatching the index worker
●! worker-acme-index    acme              ~index      claude  working   npm test has failed the same way …
○? worker-acme-search   acme     HEV-14   rfc-search  claude  waiting   asks which index to rebuild first

🚨 stop the line  3 agent(s) in 3 sub-agent(s)

One screen is one factory. Configure two on the same machine and the picker asks which one before it shows anything, and esc on the floor goes back to that question rather than quitting. Configure one and there is nothing to choose, so the question is skipped.

The last column is read out of each pane every two seconds and labelled by Claude Haiku, so the screen says what every agent is doing and not only that it is up. A session that has stopped to ask you something reads waiting, and the count of those rides in the header so the one that needs you is visible before you have scrolled to it.

Reception is the top row whether or not the desk is on duty. An off-duty desk says so, and ↵ boots it and attaches once it comes up. That matters because factory opens the screen without starting anything on its own, so a desk that exited stays down until you put it back.

↵ attaches to the highlighted session, ^d opens the detail panel for the row the cursor is on, and ^g leaves the gaffer a note it reads on its next beat. Typing filters, so an RFC slug narrows the list to the workers on it. ^x stops one session.

Stop the line is the andon cord and the one control on the screen that touches a running agent. It sends TERM to every agent in this factory and closes those sessions, and it reaches exactly the rows above it, so your own shells keep running. Reception is not on the cord, because the desk is who you ask about a line that just stopped.

factory comes from Homebrew and is on your PATH from the moment you install it. In a checkout it stays current on its own: every run of ./factory copies the binary it just built into $GOBIN, so the command you type from any directory is the code in that tree. A global install drifting behind the repo is the bug nobody looks for, and FACTORY_NO_GLOBAL_INSTALL=1 turns the copy off. Bare factory is the picker and its subcommands, while ./factory in the checkout boots reception and the gaffers first. Both take the same arguments.

docs/picker.md in the repo is the deeper reference: every column, the scope rule that decides what counts as the factory’s, and how the pane summaries are produced.