Small, local, inspectable

What do you want to do?

Pick a task and copy the commands. The current agent becomes the Lead. cmux opens the Builder, Reviewer, and Watchdog tabs.

Choose a task Run the first tutorial

Make commands ready to copy

Set your project path

The page uses this path and its directory name in every project command.

Absolute project path

Task index

I want to…

Filter tasks

01Install on a fresh machineClone, link, and verify 02Add the factory to a projectCreate the project brain 03Start with Codex as LeadOpen the full workspace 04Start with Claude as LeadUse the same factory roles 05Check what the factory is doingStatus and watchdog events 06Change instructions for one projectRules, style, and roles 07Change defaults for future projectsEdit the central templates 08Change an agent providerKeep it provider-neutral 09Update the factoryCommands, skills, and project rules 10Learn from a factory sessionTurn repeated feedback into rules 11Stop a factory sessionInterrupt workers safely 12Review an exact commitUse isolated Git worktrees 13Publish a changeOnly Lead can push

I want to set up a new machine

Install cmux-factory

Result: the command and agent skill point to one local clone.

Check the prerequisites
Install cmux, Git, Python 3.11 or later, and at least one agent command.
```
cmux version
git --version
python3 --version
command -v codex
command -v claude
```

Clone and install

git clone https://github.com/mullender/cmux-factory.git \
  ~/.local/share/cmux-factory
cd ~/.local/share/cmux-factory
./install

Add the command to your shell

grep -qxF 'export PATH="$HOME/.local/bin:$PATH"' ~/.zshrc || \
  printf '%s\n' 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Connect cmux and verify
```
cmux hooks setup
factory version
factory doctor
```
Done when the cmux binary and socket checks report PASS.

I want to add the factory to a project

Create the project brain

Result: the Git root contains a readable .factory directory.

Initialize from any project directory
```
cd /path/to/project
factory init
```
A second run preserves project rules and prints READY.
Check the project
```
factory doctor --project
```
Done when cmux, the project config, worker commands, and ignore rules pass.

Safe by default. If .factory is unknown or invalid, initialization stops. It does not replace the files.

I want Codex to be the Lead

Start with Codex

Choose the command for your current location.

From a normal terminal

Open cmux, then start Codex

cmux /path/to/project

In the new cmux terminal:

codex /start-factory

From an existing cmux terminal

Create and start in one command

cmux new-workspace --name project \
  --cwd /path/to/project \
  --command 'codex /start-factory' --focus true

I want Claude to be the Lead

Start with Claude

The worker roles still come from .factory/factory.toml.

From a normal terminal

Open cmux, then start Claude

cmux /path/to/project

In the new cmux terminal:

claude /start-factory

From an existing cmux terminal

Create and start in one command

cmux new-workspace --name project \
  --cwd /path/to/project \
  --command 'claude /start-factory' --focus true

If /start-factory is not available

Give the Lead this prompt:

Run factory doctor --project, then run factory start. You are the Lead.

I want to see what the factory is doing

Inspect status and watchdog events

The output uses exact cmux IDs and readable reasons.

Read status

factory status

Follow watchdog actions

factory events --follow

Get JSON status

factory status --json

Record feedback

factory note "Keep the next change smaller"

Read Lead mail

factory inbox lead
factory inbox lead --archive

Send agent mail

factory mail builder lead \
  "The change is ready" --kind handoff \
  --base BASE_SHA --head HEAD_SHA

Lead-centered mail. Agents never poll for mail. The Watchdog counts each inbox and wakes an idle recipient. Each worker turn must mail the Lead before it stops. A missing handoff gets one reminder, then a Lead alert. factory status shows each unread count.

I want Reviewer to inspect what Builder committed

Review an exact commit

Builder and Reviewer use separate worktrees. Reviewer never reads Builder's live files.

Assign Builder from its current commit

factory status
factory mail lead builder "Make the bounded change" \
  --kind assignment --base BASE_SHA

Receive Builder's committed handoff
```
factory inbox lead --archive
```
The mail contains full base_sha and head_sha fields.
Assign that range to Reviewer
```
factory mail lead reviewer "Review this change only" \
  --kind assignment --base BASE_SHA --head HEAD_SHA
```
The factory checks out HEAD_SHA and its recorded submodule commits before it sends the mail.

Inspect the worktrees when needed

git -C .factory/worktrees/builder status
git -C .factory/worktrees/reviewer status
factory status

I want to change instructions for one project

Edit project-owned rules

These changes travel with the project repository.

File	Purpose
`.factory/config/OPERATING_RULES.md`	Rules for all agents
`.factory/config/STYLE.md`	Shared writing style
`.factory/roles/lead.md`	Lead duties and limits
`.factory/roles/builder.md`	Builder duties and limits
`.factory/roles/reviewer.md`	Reviewer duties and limits
`.factory/agents/<name>/IDENTITY.md`	One agent identity
`.factory/factory.toml`	Names, commands, and role paths

Edit a rule

cd /path/to/project
$EDITOR .factory/config/OPERATING_RULES.md

Review and publish it

git diff -- .factory/config/OPERATING_RULES.md
git add .factory/config/OPERATING_RULES.md
git commit -m "docs: update factory operating rules"
git push

Restart the factory
Existing agents keep their original prompt. Start a new session to load the change.

I want to publish a change

Push from Lead only

Builder and Reviewer never push. They hand commits to Lead.

Check the remote branch

git remote get-url origin
branch=$(git branch --show-current)

Find open pull requests
```
gh search prs --head "$branch" --state open \
  --json repository,number,url
```
Verify that a result uses the exact remote repository and branch.

Check repository visibility

gh pr view URL --json headRefName,headRepository,state,url
gh repo view OWNER/REPOSITORY --json visibility

Ask before a public update
If the matching pull request repository is public, Lead shows its URL and asks the user for permission. Permission applies to one push only.

I want to change defaults for future projects

Edit central templates

New projects receive these files when factory init creates their brain.

Open a template

cd ~/.local/share/cmux-factory
$EDITOR templates/project/.factory/config/STYLE.md

Test and publish it

python3 -m unittest discover -s tests -v
git diff
git add templates/project/.factory
git commit -m "docs: update default agent instructions"
git push

Compare with one existing project

cd /path/to/project
diff -u \
  ~/.local/share/cmux-factory/templates/project/.factory/config/STYLE.md \
  .factory/config/STYLE.md

No hidden merge. factory init does not replace existing instructions. Apply useful changes by hand.

I want to use a different agent command

Change a worker provider

cmux-factory calls commands. It does not depend on a provider SDK.

Edit the project config

cd /path/to/project
$EDITOR .factory/factory.toml

Keep `{prompt}` as a separate argument

[agents.builder]
label = "Builder"
command = ["claude", "{prompt}"]
role = ".factory/roles/builder.md"

Keep source work separate
The worker starts in the project root for shared factory state. Its prompt gives it a separate source worktree.
Check the command
```
factory doctor --project
```

I want the latest factory version

Update commands and project rules

The command fast-forwards the clone, verifies links, and safely syncs managed rules.

Run the update from your project
```
cd /path/to/project
factory update
```
Use factory update --no-pull while you test local template edits.

Resolve any rule conflicts

diff -u \
  .factory/roles/reviewer.md \
  .factory/update/roles/reviewer.md.new

# Accept all incoming rules:
factory update --no-pull --use-upstream

The command prints exact diff, upstream, and keep-current choices. The project file stays unchanged until you choose.

Verify the update
```
factory version
factory doctor
```
Start a new Lead so it loads the updated skill.

Clean rules update automatically. The command records matching templates before it pulls. Project-specific rules stay unchanged. A REVIEW result includes copyable resolution commands.

I want the factory to learn from a session

Review feedback and improve the rules

The POC keeps this process manual and visible.

Record feedback during the session

factory note "Keep each assignment small"
factory note "Require evidence before reporting completion"

Review feedback at the end

tail -n 50 .factory/brain/FEEDBACK.jsonl
$EDITOR .factory/brain/LESSONS.md

Move repeated lessons into the right rules
```
$EDITOR .factory/config/OPERATING_RULES.md
$EDITOR .factory/config/STYLE.md
git diff -- .factory
```
Keep one-time facts in the brain. Add only repeated and useful behavior to agent instructions.

Commit the lesson

git add .factory
git commit -m "docs: apply factory session lessons"
git push

I want to end the current session

Stop the factory

The command interrupts workers and the watchdog. It leaves tabs open for inspection.

cd /path/to/project
factory stop

Close the worker and watchdog tabs when you no longer need their output. The worker worktrees remain for inspection and the next start.

Quick reference

Factory commands

factory init [DIR]Create or verify a project brain

factory doctor --projectCheck cmux, config, and agents

factory updateUpdate source, links, and managed rules

factory startLaunch tabs from the Lead

factory status [--json]Show agents and surface health

factory events [--follow]Read watchdog decisions

factory check-in …Record agent state

factory mail FROM TO TEXTWrite agent mail

factory inbox AGENTRead or archive agent mail

factory note TEXTRecord process feedback

factory stopInterrupt workers and watchdog

factory versionShow source and revision

factory watchRun the watchdog loop

Troubleshooting checks

Command not found

ls -l ~/.local/bin/factory
printf '%s\n' "$PATH"

Project or agent failure

factory doctor --project

Pull cannot fast-forward

git status
git log --oneline --decorate --graph --all -20

Old instructions remain

Stop the old session. Start a new Lead and workers.

What do you want to do?

Set your project path

I want to…

Check the prerequisites

Clone and install

Add the command to your shell

Connect cmux and verify

Initialize from any project directory

Check the project

Open cmux, then start Codex

Create and start in one command

Open cmux, then start Claude

Create and start in one command

Read status

Follow watchdog actions

Get JSON status

Record feedback

Read Lead mail

Send agent mail

Assign Builder from its current commit

Receive Builder's committed handoff

Assign that range to Reviewer

Inspect the worktrees when needed

Edit a rule

Review and publish it

Restart the factory

Check the remote branch

Find open pull requests

Check repository visibility

Ask before a public update

Open a template

Test and publish it

Compare with one existing project

Edit the project config

Keep {prompt} as a separate argument

Keep source work separate

Check the command

Run the update from your project

Resolve any rule conflicts

Verify the update

Record feedback during the session

Review feedback at the end

Move repeated lessons into the right rules

Commit the lesson

Command not found

Project or agent failure

Pull cannot fast-forward

Old instructions remain

Keep `{prompt}` as a separate argument