Quick start

1. Install

brew install hev/tap/factory
gh auth login

The formula brings tmux, gh and jq with it. macOS only: this is launchd, tmux and the login keychain, so there is no Linux build to fall back to.

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, because a laptop that sleeps stops the loop mid-beat. A Mac mini is the intended shape.

2. Run the factory

factory

The first run has no checkout to read, so it asks before cloning the repo to ~/workspace/factory and starts from there. The contracts a factory runs on live in that checkout and are yours, so changing how a factory operates is a commit rather than a setting. Keep the checkout alongside your work and 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.

There is nothing to configure by hand. Reception goes on duty in a tmux session, you land in the conversation, and it walks you through your first factory from there.

3. Decide how you approve

Approving is the one thing that stays yours, and there are two ways to do it. Reception asks which one you want while it sets the factory up.

Out of the box it is merging a pull request that adds the plan to plans/active/. Nothing in the factory merges into that branch, which is why the merge means something. Turn on branch protection requiring a pull request and that stops being a rule the factory follows and becomes one it cannot break.

Linear is better, and setup offers it. Moving an issue into your team’s approved state is one tap from a phone, and approving on the way somewhere beats approving next time you are at a machine. It costs one OAuth:

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. Skip it now and add it later, because it is two fields in the config.

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 against the 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.

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   ^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

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

From source

Working on the factory itself, or running an unreleased revision:

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

This one needs Go. ./factory builds the picker and copies it into your $GOBIN so factory works from any directory, and on a fresh clone it reports nothing configured, which is right. Set FACTORY_NO_GLOBAL_INSTALL=1 to leave your $PATH alone.