Quick start

1. Prerequisites

brew install tmux go gh jq
gh auth login

Linear. Approving happens there, so a factory does not run without it:

claude mcp add --transport http --scope user linear https://mcp.linear.app/mcp

Then /mcp in any claude session to authenticate. Your team needs a workflow state that means approved, which on a default Linear board is Todo: Backlog already means captured-but-undecided, and Todo means decided-not-started. Setup asks which one you mean and never guesses.

If you already use Linear for something else and this factory is for a different workspace, register a second server under its own name — linear-acme, same URL — and authenticate that one against the other workspace. MCP logins are keyed by server name, so both work side by side and the config names which one this factory uses.

You also need claude, logged in. The factory ships no model and never sees your API keys: reception, the loop, and every worker it dispatches run claude on the subscription you already hold. Every agent is a tmux session, which is why you can attach to any of them mid-task and take over by typing. Run it on a Mac that never sleeps — a laptop that sleeps stops the loop mid-beat, and a Mac mini is the intended shape.

2. Clone and build

git clone https://github.com/hev/factory ~/workspace/factory
cd ~/workspace/factory
./factory list

list builds the picker and copies it into your $GOBIN, so factory works from any directory; on a fresh clone it reports nothing configured, which is right. Clone this repo alongside your work, never inside it. It is generic machinery, and your own repos and Linear team stay the source of truth for plans, issues, and pull requests.

3. Run the factory

./factory

There is nothing to configure by hand. On a fresh clone this puts reception on duty in a tmux session and drops you into the conversation, and reception walks you through your first factory from there.

4. In another pane, watch the floor

factory

That is the picker, and it is the screen you leave open: reception, the gaffers, and every worker they dispatched.

acme   ↵ attach   ^x stop one   ·   type to filter

💁 reception      the front desk — ask anything
── sub-agents ──
●  gaffer-acme          acme                          claude  working    ✻ Brewed for 41s
●⚠ worker-acme-index    acme              ~index      claude  working    ⏺ Bash(npm test -- --watch)
○  worker-acme-search   acme     HEV-14   rfc-search  claude  idle 12m   ⏺ Rebased onto main; ready for review.

↵ on any row attaches to that session, so watching becomes steering the moment you start typing. Most workers carry no issue at all — machine work never becomes one — so that column is blank except where a person is already involved.