Factory mode

What it does

Factory mode turns one of your workflows into a worker for one project. You write down the things you want built, one per item, and Cerevisor runs the workflow once for each item, one at a time, in the order you listed them. Each item gets:

• its own folder of working files inside the project,
• its own run, which you can watch on the canvas like any other run,
• and, in a project that uses git, its own commit on a branch called cerevisor-factory.

When the workflow has a checker (the ready-made one does), an item only counts as done once the checker says the work passes. An item that fails is tried again: up to three times in all by default, and each new try is told what went wrong in the one before.

Nothing is ever pushed. Cerevisor never pushes, merges, rebases or opens a pull request. What happens to the branch afterwards is up to you.

Factory mode is part of Founding membership and is included in the 7-day trial; see Plans & licensing. On any other plan the settings show a short card saying so, and the switch stays off.

Switching it on

1. Open the workflow you want to use, then open Settings → Factory mode. The Deploy the factory button in the workflow's controls (the small factory beside Schedule, or under More workflow actions on a narrow canvas) opens it, and so does the factory panel's settings button.
2. Turn on the switch beside the title, Factory mode — queue development items and run this workflow once per item. Or use the ready-made factory card under The workflow: it draws the five stages of the ready-made team (Research, Discuss, Plan, Build, Validate), and Deploy the ready-made factory (below) lays that team on the workflow and turns the switch on for you. The stages light up one after another, a check appears, and the card says "Your factory is ready." With reduced motion turned on in your system, you see the finished card straight away.
3. Under The project, press Choose folder… and pick the project the items are for. If the workflow already has a folder set, that folder is filled in for you.
4. Under How it runs, pick a mode: Attended or Unattended (below).
5. If you want, change Tries per item, Spending limit per item (US$) and the smart routing box (Trying again, Picking models). The defaults suit most projects.
6. There is nothing to save by hand. The factory always runs the saved copy of the workflow, so Start, adding an item and the other panel actions save the workflow first, by themselves. Only if that save fails does Cerevisor say "Cerevisor couldn't save the workflow, so the factory can't read it. Save it (Ctrl+S), then press Start." If the saved file cannot be used, Start names why instead: "This workflow is not in the saved file yet. Save the world (Ctrl+S), then press Start." when the workflow was added after the last save, "Cerevisor can't read this workflow's saved file in this session…" when the file needs saving again or opening from File → Open, or "The saved workflow file could not be read: …" with the reason.

A small label beside the tab's title says whether the factory is Off, Ready, Running or Paused, and Open the queue at the bottom closes Settings and shows the factory panel.

Once the factory is on, the canvas changes in these ways:

• The panel that usually sits to the left of the workflow, where you type what a run should do, is replaced by the factory panel: the project's readiness line, the list of items, a box to add a new one, and Start / Pause.
• The Deploy the factory button in the workflow's controls is lit, and its tooltip reads Factory mode settings. It still opens the Factory mode settings.
• The workflow's own Run button reads Start factory, and Pause factory while the factory is working, between items. Pressing Start factory shows the usual summary of what the run may do, once for the whole list, and then the factory starts working through it. For an unattended factory the summary says the items run hands-free, and why. The summary also carries the factory's own notes: how many times each item is tried and up to what cost, whether smart routing picks the models, and, when the project has no tests, "No tests were found in the project, so nothing will check what the items build." For an attended factory it also names any agent that is meant to ask you questions but runs on a service that cannot, for example "Planner runs on Cursor, which cannot ask you questions, so it will decide on its own."
• While an item runs, that button is a Stop button that stops the item, exactly like Stop item. The controls have no Pause of their own then; the label on the workflow's frame has both Pause factory and Stop item.
• The run window opens for each item as it starts, the same window a Run-button run opens, so you can follow every item as it happens.

The factory never starts by itself, not even when you open Cerevisor. It only works while Cerevisor is open.

Is your project ready?

The factory panel (and the Factory mode settings) shows one line about what the factory can check your project with, for example:

Ready: tests (npm test), build, linter, README.

or, when it finds no tests:

No tests found — the factory can build, but nothing will check the result.

To work this out, Cerevisor looks at the file names at the top level of the project and reads at most three small files there (package.json, pyproject.toml and Makefile). It recognises:

• Node: the test, build and lint scripts in package.json, run with npm, pnpm, yarn or bun, whichever lock file the project has. The placeholder test script npm writes (no test specified) does not count.
• Python: pytest, when there is a pytest.ini or a [tool.pytest…] section in pyproject.toml.
• Go (go.mod), Rust (Cargo.toml) and .NET (a .sln or .csproj file): their own test and build commands.
• Make: a test, build or lint target in the Makefile.
• Linters by their settings files: ESLint, Ruff, golangci-lint and Clippy.

When more than one command of a kind turns up, the first one is used and the line below it says "Also found: … The first one is used." A project that holds several packages is looked at only at its top level, and the panel says so.

The commands it found are written into every item's request.md under Commands to verify with, so the agents that build and check the work use the project's own tools.

Nothing is run until you ask. Looking at the project only reads file names and those three files. To find out whether the commands actually work on this computer, press Check the commands work. Cerevisor then runs the test command and the build command once each, in the project folder, and tells you for each one whether it worked ("npm test worked.") or not, with the exit code. Open a result to see what the command printed. The linter is shown but never run by the check.

• No model is involved and nothing is billed.
• Each command gets 10 minutes. A command still running after that is stopped, together with everything it started, and the result says so.
• The check cannot run while the factory is working on the project, and Start waits while a check is running ("The commands are being checked. Wait for the check to finish, then press Start.").
• The commands run with a trimmed set of your environment settings (your PATH, home folder, proxy settings and a few system ones). A tool that needs a variable of its own, such as JAVA_HOME or GOFLAGS, may fail in the check even though it works in your own terminal.

An unattended factory may still start with no tests. The Start confirmation says so, so you know nothing will check what the items build.

Attended and unattended

The mode belongs to the factory, not to each item.

Attended stops for you. Nothing waits against a clock: when an agent asks a question, asks for a permission, or the workflow reaches an approval step, the item waits for you with no time limit until you answer or press Stop. (In an ordinary run, and in an unattended item, the usual waits still apply.) The items are ordinary runs, so the phone companion shows them like any other run.

When something is waiting, the review panel opens by itself in front of the canvas (Answering in the review panel). Nothing is pressed for you when it opens: the keyboard stays on the panel itself, so a key you were already pressing, such as Ctrl+Enter from the item box, answers nothing. Press Tab to reach the main button, or click.

While an attended item is waiting for you, its row in the factory panel also says so under the title: "Waiting for your approval.", "Waiting for your answer to a question.", "Waiting for your permission.", or "Waiting for your answer: some agents may not see this item's pictures." The line goes away once you answer. Beside an approval, a question or a permission, Review opens the review panel on that request, so you can come back to it after closing the panel. The picture question is answered in its own dialog in front of the canvas.

Answering in the review panel

The review panel shows one request at a time, the oldest first, and says how many are waiting ("1 of 3 waiting"). Closing it (Esc, the close button or a click outside) answers nothing: the request keeps waiting, and Review brings it back.

• An approval shows the question the step asks (for example "Approve the plan before it is built?"), where it comes from, and the documents being approved, one tab per file, formatted as they would read in the File Viewer. For the ready-made factory that is approach.md, then plan.md and acceptance.md. A very long file shows its first part and says so. The agent's closing message is folded away underneath. Then:
• Approve lets the next step start with this work. Ctrl+Enter (Cmd+Enter on a Mac) does the same once you are in the panel.
• Ask for changes opens a box: say what to add, remove or do differently, and press Send. The agent that made the work runs again with your note and its earlier files, and the same approval comes back with the new documents, marked "Revised after your changes (round 2)". You can ask for changes up to three times at one approval in one run; after that only Approve and Stop here are offered. If the agent could not make the changes, the run window says so ("Planner could not make the changes you asked for, so Builder did not run.") and the next step does not run.
• Stop here skips the next step and the steps that depend on it. The item ends needs-you, as any declined approval does.
• A question shows who asks, the question, and its choices as large buttons, with the one the agent recommends marked Recommended. You can type another answer instead.
• A permission shows what the agent wants to do in plain words, the command or the change, and how risky it is, with Approve once, Always allow (for the rest of this run) and Deny.

A few things to know about asking for changes:

• If the work changed since you looked, an Approve is not taken at its word. This can happen when one agent's work goes to two approval steps and you asked for changes at the other one. The approval asks again with the new documents and the line "The work changed since you last looked."
• A Stop is always honoured, even on a card that showed older work.
• Asking for changes is not a declined approval: the item carries on, and decisions.md lists your note ("Asked for changes at …").
• Asking for changes is only offered in the desktop app. The phone and scripts can approve or stop.

Unattended does not wait for anybody. Choosing it asks you to confirm first:

Unattended items run hands-free: agents act without asking, inside this workflow's permission settings. Questions and approvals are decided by the model.

Press Confirm unattended to switch. An unattended factory needs two agreements: one saved in this workflow, and Cerevisor's own one-time Hands-free agreement on this computer — the same one Cerevisor asks for when you choose the Hands-free approval setting anywhere else. The second stays with this computer, not with the workflow file.

If this computer has not given the Hands-free agreement yet, Confirm unattended opens Cerevisor's own Hands-free dialog, "Turn on Hands-free?", which explains that agents then never pause to ask and that your permission limits still apply. Press Turn on Hands-free there to agree; the workflow is switched to Unattended only then. Press Cancel and nothing changes: the factory stays Attended. (The dialog records the agreement for this computer; it does not change the approval setting of your other workflows.) If this computer has already agreed, Confirm unattended switches the workflow straight away.

If you receive a workflow file that is already set to Unattended, or open yours on another computer, the settings ask you to confirm again there, and until you do, Start says "Unattended mode is not confirmed on this computer. Confirm it in the Factory mode settings, then press Start."

From then on, for every item:

• Questions are decided by the model. An agent that asks a question is told "Nobody is available to answer — this is an unattended run. Go with the option you recommend, and state in your output which one you chose and why."
• Approval steps are approved at once, and the approval is recorded as the factory's, not yours.
• The run is hands-free, whatever approval setting the workflow itself saved. Agents act without asking you, but only inside the permissions the workflow allows. Those limits still hold.
• The picture check goes on without you. When an item has pictures and Cerevisor cannot confirm that an agent's model can see them, an attended item asks you; an unattended item goes on, as Proceed anyway would, and writes that down.
• Anything else that would ask you is declined. For example, an offer to continue a step on another paid key after a usage limit, or an agent whose fallback is set to ask you. If something needs a permission in the middle of the run, it is refused automatically and the agent carries on without it.
• Everything decided for you is written down in the item's decisions.md: each question and the answer the model chose, each approval, each refused permission, and each agent that went on without seeing the pictures.

Switching back to Attended forgets the workflow's confirmation. Choosing Unattended again asks you to confirm again.

The factory keeps the workflow it was started with. If the workflow file's mode or its confirmation changes while the factory is working (say it is edited by hand, or by another program), the factory does not run the next item in the new mode. It pauses with "The factory's mode was changed in the workflow file. Check it in Settings, then press Start." In the same way, if the project folder saved in the file changes, it pauses with "The factory's project folder was changed in the workflow file. Check it in Settings, then press Start." (If the folder has simply disappeared, it says "The project folder can't be found." instead.)

The same goes for the rest of the workflow: its agents, its connections, its waves and its settings. If any of them is saved differently while the factory works, the factory runs no further item or try on the changed workflow, and pauses with "The workflow was changed while the factory worked. Check it, then press Start." Moving a card or changing a wave's colour does not count. Pinning or unpinning a note on the team board counts, because pinned notes are part of the workflow's settings: do it while the factory is paused.

Adding items

Type what should be built in the factory panel's box (a title is optional), then press Add to queue or Ctrl+Enter (Cmd+Enter on a Mac). The box grows as you type. If you leave the title blank, the first line of the request is used as the title.

While an item is waiting its turn you can Remove it or drag it to a new place in the list. The factory takes the first waiting item from the top each time.

Pictures on an item

A screenshot often says more than a paragraph. You can attach pictures to an item:

• paste a screenshot into the box (for example after Win+Shift+S on Windows, or Cmd+Ctrl+Shift+4 on a Mac);
• drop image files onto the box;
• or press the paperclip under the box and pick them.

The pictures show as small previews before you add the item; point at one and press its small remove button to take it off. Later, on any row that is not running, you can drop more pictures onto the row or press its paperclip, and remove one from its preview the same way. A running item's pictures stay as they are until it finishes ("This item is running. Add or remove its images once it has finished.").

The limits:

• PNG, JPEG, GIF and WebP only. Cerevisor tells them apart by what is inside the file, not by its name.
• At most 10 pictures per item, 10 MB each, and 25 MB in one go.

The pictures are saved in the project, in .cerevisor/project/items/<id>/images/, with names Cerevisor makes (01-login-page.png and so on). Every try of the item uses the same pictures. Like the rest of .cerevisor/, they are never committed.

When the item runs, every agent is given the pictures and told to look at them before it starts. An agent whose model can see pictures gets them with its first message; a harness such as Codex or Claude Code gets them as files it opens. The item's request.md lists them under Images. If Cerevisor cannot confirm that an agent's model can see pictures, an attended item shows the app's "Image inputs may be ignored" dialog: press Proceed anyway to go on (that agent may work without seeing them) or Cancel run. An unattended item goes on by itself and writes it down in decisions.md.

Adding items from other programs

A script, your CI or another program on this computer can add items too, through the local API. This needs the local API switched on (or the cerevisor command, which starts Cerevisor in the background when it is closed), and a plan that includes both the local API and Factory mode.

From a terminal:

cerevisor factory add "D:\Projects\shop\shop.cerevisor-world" --request "The checkout page shows the total twice" --title "Checkout total" --source-ref ci-1234

It prints queued <id>, or already queued <id> when that --source-ref is still waiting or unfinished. Programs that speak MCP use the add_factory_item tool. Both are described in Running workflows from scripts.

Some things to know:

• Adding never starts the factory. The item waits in the list until you press Start. Nothing a program adds runs without you.
• --source-ref stops duplicates. Give each signal a stable key (a build number, an issue number). The same key is not queued twice while its item is waiting, running, needs you or failed. Once that item is done or stopped, the same key can be queued again.
• The workflow must have Factory mode switched on, and the request cannot be empty. --source (default local-api) and --source-ref must each be one line, up to 64 and 200 characters.
• Treat what a program adds as your own request. The agents read it exactly as if you had typed it, so only let programs you trust add items.
• Pictures cannot be added this way yet. Add them in the panel.

The queue file

The list lives in your project, in .cerevisor/project/development.csv. It is a plain CSV file with one row per item and these columns:

A queue file from before these last five columns is read as it is, and gets them the next time Cerevisor writes it.

Several workflows can share one project folder. Each item belongs to the workflow that added it: a workflow's panel shows only its own items, its Start runs only those, and it cannot remove, move or retry another workflow's items. A row with a blank workflow (one you typed by hand, or one written before this column existed) shows in every workflow that uses the folder, and belongs to the first one that runs it or changes it. Only one workflow can work a project folder at a time.

You can edit it by hand, for example to add many items at once:

• Add a row with a request and leave id and status blank. It counts as waiting, and it gets an id the next time Cerevisor reads the file.
• Ids belong to Cerevisor. An id is lowercase letters and digits only. Anything else in the id column — a hand-typed name such as login-page, spaces, slashes, dots or capitals — or an id that an earlier row already uses, is replaced with a fresh one the next time Cerevisor writes the file. If that row had already run under its old id, its earlier item folder stays on disk under the old name; the next attempt starts in a new folder under the new id.
• A row with an empty request is left alone. It is never run and never rewritten.
• Columns you add yourself are kept. Cerevisor rewrites the file only when it has something to change, such as a status or a new id.
• A value that contains a comma must be in double quotes, as usual in CSV. If it is not, Cerevisor stops and tells you which row, and changes nothing.
• A status Cerevisor does not know is shown as needing you, with a note saying so. Press Retry to send it back to the queue.

Close the file before pressing Start. Excel locks a CSV file while it is open, and while it is locked Cerevisor cannot update the list. Cerevisor tries for a couple of seconds, then stops and says "The queue file is open in another program. Close it and press Start." Close the file in Excel and press Start again. If the file cannot be saved for another reason (for example, the disk is full), Cerevisor says "The queue file could not be saved: … Nothing was changed." And if the file keeps changing under Cerevisor, so that it picks an item three times in a row and finds it gone or moved each time, the factory pauses with "The queue file kept changing before an item could start. Check it, then press Start."

What each status means

A failed or needs-you item does not stop the list: the factory moves on to the next item. But three in a row pause the factory, with "Paused after 3 items in a row did not finish. The last one said: …". One finished item resets the count. Tries of the same item count once: only how the item finally ended counts.

An item that has run more than once shows a small try 2, try 3 after its title.

Retry is offered on failed, needs-you and stopped items. It starts the item again from the beginning: on a stopped item, use it when you do not want the factory to carry on from where it stopped. It puts the item back in the list as waiting. The next time the factory reaches it, it runs as a new attempt with a fresh folder (attempt-2, attempt-3, …). Earlier attempts' folders are kept as they were, and never reused: if the attempt count was changed by hand and that folder already exists, the next free number is used and written back. Retry does not start the factory by itself; if the factory is paused, press Start. What Retry does to the item's tries and cost is under Trying again.

The factory runs its items again; the canvas does not. An item's recorded run cannot be continued, resumed from an agent or resumed from a wave like an ordinary run, because outside the factory it would run without its own folder and none of its inputs. Trying says "This was a Factory mode item. Press Start in the factory panel to carry on from where it stopped."

Who checks the work

A factory item is only as good as the check at its end. The ready-made workflow splits building from checking:

1. Before anything is built, the Planner writes acceptance.md: a numbered list of what must be observably true when the item is done, each with how to check it (a command and what it must print, a file and what it must contain, or a behaviour and how to see it). The list starts with what you would check by using the result: how you open or start it, what you do, and what you must see. A result that passes its tests but that you cannot open and use is not done. The Builder aims at that list and is told not to change it.
2. After the Builder, a separate agent, the Validator, checks the work. It did not build it. It reads the request, the criteria, the plan, the Builder's report and the verification research, and first uses the result the way you will: it follows the Builder's How to Use It steps exactly, opening a web page in its browser the way the steps say. Whatever it cannot actually use is could not check, so the verdict is FAIL. It then looks at what changed (with git diff in a git project), runs every command under Commands to verify with, and checks the request itself too: a criterion that was met while the request was not is not a pass. It is told not to change, fix, commit or install anything.
3. The Validator writes validation.md in the item's folder. Its first line is exactly Verdict: PASS or Verdict: FAIL. Then comes one section per criterion, each with Result: met, Result: not met or Result: could not check, and the evidence: the command it ran and what it printed. Could not check is not a pass.

Cerevisor reads that verdict to decide the item:

• Verdict: PASS makes the item done.
• Verdict: FAIL means the item is tried again if it has tries left, and otherwise ends needs-you with "Did not pass: ".
• A verdict Cerevisor cannot read counts as not passing: a first line that is neither of the two, or a PASS that still lists a criterion not met or not checked ("The checker's verdict could not be read: …"). So does no verdict at all ("The checker did not write its verdict (validation.md), so the result was not checked."). Cerevisor only takes a verdict the checker itself wrote in this run, after it ran to its end, and only as the checker left it; a validation.md left by another agent, by an earlier run, or by a checker that was skipped or failed, is not a verdict, and neither is one that anything changed after the checker finished (a later agent, a later round of a loop, or another program).

The last_verdict column records the checker's last word, pass or fail, when a verdict it could read decided the try. It stays empty when there was no verdict, when it could not be read, or when it was thrown away because the checker changed project files.

Your own workflows can have a checker too. Any agent that writes a file named validation.md with Keep in each run's own folder ticked is treated as the checker, and its verdict decides the item in the same way. A workflow with no such agent works as before: a run that finishes is done.

A checker that changes your files is not trusted

A checker that edits the work could make any work pass. So, in a git project, Cerevisor takes a fingerprint of the project when the checker starts, and another when the run moves on to a new round (the next time an agent starts in a new part of the run, such as a loop's next round) or when the run ends. That second fingerprint is not taken the moment the checker finishes, so anything an agent after the checker changes in the same run counts against the checker. Make the checker the last agent of its run, as it is in the ready-made workflow. If anything the checker must leave alone changed in between, its verdict is thrown away and the item ends needs-you with "The checker changed project files, so its verdict was not used. Look at the changes, then press Retry." This is never tried again automatically.

What counts as a change:

• any change to a file git tracks, staged or not, and any commit the checker made;
• any change to a file that was new and not yet committed when the checker started, which includes everything the Builder just created;
• a change to the repository's own git settings, its local ignore list or its hooks.

What does not count: a new file that appears while the checker runs, such as the output of a test run or a build.

Put your build output in .gitignore. If a build or test folder already exists, is not ignored, and the checker's own test run rewrites it, that counts as the checker changing project files, and a good item is refused. Ignored files are never looked at.

The limits of this check, plainly:

• It only works in a git repository. Outside one, the checker is trusted without it.
• If Cerevisor cannot take the first fingerprint, when the checker starts (git does not answer in time, or the project holds more than 5,000 files, or 200 MB, that are new and not yet committed), it cannot compare. The item keeps its status, and its summary and decisions.md say "Cerevisor could not check whether the checker changed project files."
• If it took the first fingerprint but cannot take the second (git does not answer in time at the end), that counts as the checker changing project files: the item ends needs-you as above.
• Some changes are not seen: git settings kept in a separate file that the project's settings only point to, the settings of one worktree, the project's .git/info/attributes file, a new .gitattributes file that is not committed yet, and edits inside a submodule that already had uncommitted changes.
• The fingerprint is started as the checker starts, so a change made in the very first moment of the checker's run may be taken for how the project was before it.
• The Builder is told not to edit acceptance.md, but that is an instruction, not a lock.

Trying again

When an item fails, or its checker says it does not pass, the factory tries it again straight away, before it moves on to the next item.

• Tries per item (Settings → Factory mode): 3 by default, anything from 1 to 5. With 1, every item is tried once.
• Spending limit per item (US$): left empty, it means no limit for an attended factory and US$5 for an unattended one, so an unattended factory always has a limit. Type a number to set your own.
• The limit is checked between tries, never during one. A try is not stopped halfway because the item went over the limit, so one try can take the item past it. The next try is then not started.

Each try is committed on its own. A try that is about to be tried again is committed as [retrying] factory: <title> (<id>), and the next try starts from that work, in a fresh attempt folder, instead of from scratch. Cerevisor never resets your project. While the next try waits its turn, the row reads "Try 1 did not finish: Trying again."

Every try after the first also gets a file called previous-attempt.md. It says why the last try ended, asks the agents to build on what it changed and fix what it lists rather than start over, and carries:

• what the checker found: every criterion it marked not met or could not check;
• what the Builder reported (its result.md);
• the decisions made in that try.

The first try's previous-attempt.md simply says it is the first attempt. A try after a failure also prefers stronger models when smart routing is on (Picking models).

When the tries or the money run out, the item ends as the last try left it, and the summary adds "Tried 3 times." or "Not tried again: this item has cost $4.87."

What is never tried again, because another try would do the same, or spend more than you allowed:

• you pressed Stop, anywhere, or Cerevisor was closing;
• you declined an approval;
• the run was refused before it started;
• an agent reported it could not continue;
• the checker changed project files;
• the run could not be recorded;
• one of your own workflow hooks halted the run;
• the run reached the workflow's own cost or turn limit;
• something went wrong unexpectedly, or git could not commit the try.

These items go straight to needs-you, failed or stopped for you to look at.

Your own Retry keeps the item's tries and its cost. They are not reset:

• If the item used up all its tries, Retry gives it one more try.
• If it ended in a way that is never tried again (a Stop, say) with tries left, Retry gives it the tries it had left.
• The spending limit is not checked before a try you asked for.

The cost column counts every try's spend, from each run's own total. Two things are not counted: a try that ended with an unexpected error, and a try whose last update Cerevisor could not write to the queue file as it closed (for example because the file was open in Excel).

Picking models

Agents set to Auto need a model. With smart routing on (the default), every time the workflow runs for an item, every try and every round of a loop, each Auto agent gets a model chosen for its task, on its own account. Models that did badly for an agent before are passed over. A try after a failed one prefers stronger models.

• Choosing usually costs one extra model request each time the workflow runs; the Start confirmation says so.
• The item's request.md says models are being chosen, and decisions.md lists the model each agent got ("Model chosen"), or that it kept its usual model.
• Agents with a model you picked yourself are never changed. Agents on Antigravity, OpenRouter or Ollama keep their own model.
• The choice only affects the item's own copy of the workflow. Your saved workflow is never changed, and routing never changes what an agent is allowed to do.

To switch it off, untick Pick a model for each agent set to Auto, for each item (smart routing) in Settings → Factory mode, and save. Auto agents then run exactly as the workflow is saved, and a retry uses the same models.

Pausing, stopping and closing

• Pause (in the panel, or Pause factory on the workflow's frame or its Run button) lets the current item finish, then holds. Nothing else is started until you press Start.
• Stop item (in the panel, or on the workflow) stops the running item straight away. Whatever it had changed so far is committed with [stopped] at the start of the commit message, the item shows stopped, and the factory pauses with "Paused because an item was stopped. Press Start to carry on with it, or remove it to go on with the next one." The next Start carries the stopped item on from where it stopped, before any other item. To skip it instead, remove it (the bin on its row); to start it over, press Retry.
• A Stop from anywhere counts. Stopping the item's run from the run window, the phone or a script does exactly the same as Stop item: the item shows stopped and the factory pauses; it does not move on to the next item. That includes stopping a repeat round of a loop inside the item: it stops the whole item.
• If you press Stop just as the factory is getting the next item ready, that item is not started: it stays waiting and the factory pauses.
• While the factory is working, the label on the workflow's frame shows only Pause factory and Stop item, and the controls' Run and Stop buttons pause the factory and stop the item. The ordinary Run, Pause and Stop controls come back when the factory pauses.
• You cannot run the workflow by hand while the factory is working on it. Every other way of starting it is refused: running one agent, "Resume from here", a column's own run, Loop & Enhance, Continue, a schedule, the Operator, a script or the phone. The refusal says "Factory mode is working on this workflow. Pause it and let the current item finish, then run it by hand."
• Loops report into their item. When the workflow has a loop, each repeat round belongs to the item: a No on an approval step inside a round makes the item needs-you, and the round's questions, approvals, missed approvals and refused permissions go into the item's decisions.md.
• Closing Cerevisor in the middle of an item stops the item and waits up to 15 seconds for its changes to be committed and the list to be updated, then closes. The item shows stopped. If Cerevisor could not finish in time, the item still reads running in the file. The next time the factory reads the list, it corrects the item to stopped with "Cerevisor closed before this item finished." If you cancel the close (for example, on a Mac you press Cmd+Q and then Cancel), the item has still been stopped. After a few seconds, press Start to go on. Either way, the next Start carries the item on from where it stopped.

Carrying a stopped item on

When the factory reaches a stopped item, it carries on with the same try, in the same attempt folder. The agents that had finished keep their work and do not run again, and approvals you already gave are not asked again. Only the agents that had not finished run. The item's decisions.md keeps what was decided before the stop, and adds what was decided after under "Carried on from where it stopped."

It starts the item again as a new try instead, in a fresh attempt folder, and its decisions.md says why, when:

• the workflow was changed after the item stopped ("The workflow was changed after this item stopped, so it started again from the beginning.");
• Cerevisor cannot find where the item stopped, for example because the run's record was removed ("Cerevisor couldn't find where this item stopped, so it started again from the beginning.");
• every agent had already finished when it stopped ("Every agent had already finished when this item stopped, so it started again from the beginning.");
• or the item was stopped while it waited for its next try. Then the factory simply makes that try.

In a git project, the project must have no uncommitted changes first. If it has some, the factory pauses with "The project has uncommitted changes. Commit or stash them, then press Start to carry on with the stopped item." and the item stays stopped.

When the factory pauses and keeps the item waiting

Some problems are not about the item. The factory then pauses and leaves the item waiting, rather than marking it as needing you. Fix the problem and press Start:

The factory also pauses if your plan no longer includes it. The item that was running finishes first.

Git: the branch, the commits, and undoing one item

When the project is a git repository, before each item Cerevisor:

1. adds .cerevisor/ to git's own local ignore list for this repository (.git/info/exclude), so the queue and the item folders are never committed. Your .gitignore is not touched. Cerevisor also leaves .cerevisor/ out of its own checks and commits, even if something in it was committed to the repository earlier. One thing to know if your repository does track files under .cerevisor/: when one of them changes, Cerevisor never commits that change, but it may leave it staged, so your own next git commit would include it. Check git status before you commit, and unstage it (git restore --staged <file>) if you do not want it;
2. checks that the project has no uncommitted changes. If it has some, the item is marked needs-you with "The project has uncommitted changes. Commit or stash them, then press Retry." and the factory pauses at once, with "Paused because the project has uncommitted changes. Commit or stash them, press Retry on the item, then press Start." Commit or stash your changes, press Retry on the item, then press Start;
3. switches the project to the branch cerevisor-factory, creating it from where you are now if it does not exist yet. If it already exists, Cerevisor switches to it as it is; to bring newer work into it, merge that work in yourself. The project stays on that branch afterwards.

After each try, if anything in the project changed, Cerevisor commits it on cerevisor-factory as factory: <title> (<id>), with [retrying], [failed], [needs you] or [stopped] at the start when the try did not finish well. The short commit id goes into the item's commit column. If nothing changed, there is no commit.

Cerevisor commits only on cerevisor-factory. If the project was switched to another branch while the item ran, nothing is committed, the item is marked needs-you with "The project is no longer on the cerevisor-factory branch, so nothing was committed.", and the changes are left in the project for you.

The commit uses the name and email git is set up with for this project. If git has no name set, the item is marked needs-you with "Git has no author name set for this project." and nothing is committed. The changes stay in the project, uncommitted, and they would stop the next item as uncommitted changes. Set a name with git config user.name "Your Name", commit or stash those changes yourself, then press Retry.

To undo one item, revert its commits:

git revert <commit>

where <commit> is the id in the item's commit column. An item that took several tries has one commit per try; git log --grep=<id> cerevisor-factory lists them all. Every item is its own set of commits, so undoing one leaves the others in place.

Nothing is ever pushed. Cerevisor makes local commits on cerevisor-factory and nothing else. It never pushes, merges, rebases, resets or stashes, and it never switches to any branch but cerevisor-factory. The agents themselves follow the workflow's own git permission, as in any run.

If the project is not a git repository, the factory still works, but items change your files directly, there are no commits, an item cannot be undone on its own, and nothing checks whether the checker changed your files. The panel shows "not a git repository" (or "git not installed" when git is not on this computer).

Keeping the workflow file inside the project

The workflow's own file can live inside the project. The factory leaves that one file out of everything it does with git. Saving the workflow between items does not stop the next item for uncommitted changes, and the workflow file never ends up in an item's commit. (A change to what the workflow does still pauses the factory; see Attended and unattended.) Commit your own changes to the workflow yourself when you want them in the project's history.

Where each item's working files are

Every attempt of every item has its own folder inside the project:

<project>/.cerevisor/project/items/<id>/attempt-<n>/

Cerevisor writes these files there:

• request.md, before the run: the request as you wrote it, the item's id and title, the project folder, the mode, the attempt number, the Commands to verify with, the item's pictures under Images, and a line about how models are picked.
• previous-attempt.md, before the run: what the try before left (Trying again).
• decisions.md, after the run: every question and approval of the run, the answer, and who gave it (you, the model, or the factory), the models smart routing chose, and each agent that went on without seeing the pictures. In unattended mode it also lists every permission that was refused.
• ending.md, after a try that did not finish: why it ended, in a sentence, for the next try.
• OUTPUTS.md and, when the workflow writes a run report, run-report.html: Cerevisor's own notes about the run. In a factory item they go here, not into the project.

The workflow's own working files go there too, when they are marked Keep in each run's own folder (see below). In the ready-made workflow that is every report the agents write, including acceptance.md, validation.md and result.md, whose first paragraph becomes the item's summary.

The item's pictures sit one level up, in <project>/.cerevisor/project/items/<id>/images/, shared by all its attempts.

The agents work in the project folder itself. Only the working files go in the item folder. Folder on a finished item in the panel opens its latest attempt's folder. You can find the item's recorded run, like any run, in the workflow's run history.

"Keep in each run's own folder"

Each file on an agent card has a Keep in each run's own folder checkbox. Ticking it turns the file into a plain name such as approach.md, and each run gets its own copy:

• in a factory item, inside that attempt's folder, so one item never reads another item's leftovers;
• in any other run, in the run's working folder, as a plain file name always was.

The agent that writes the file and the agent that reads it should both have it ticked, so they refer to the same file. Unticking it turns the name back into a full path in the workflow's folder.

A ticked file that no agent in the workflow writes, and that is not there yet, is expected to be supplied when the run starts. The factory writes request.md and previous-attempt.md itself. A run you start by hand simply goes without them, instead of being refused before it begins.

Opening files

Click a file on an agent card to open it in Cerevisor's file viewer.

• A file kept in each run's own folder opens from the run that wrote it. For a factory workflow, that is the running item's folder, or else the folder of the item that finished last. For any other workflow, it is the workflow's working folder.
• "This file has not been written yet. It appears once the agent that makes it has run." means just that: the agent has not run yet in that item, or not in this folder. It is not a permissions problem.

The viewer opens files anywhere on this computer, not only in your project folders. There are three things it never opens, whichever folder they are in:

• Folders that hold keys and passwords, such as .ssh, .gnupg, .aws, .azure, .kube, .docker, the Git, npm and GitHub CLI sign-in files, and the sign-in files of Claude Code, Codex, Grok, Gemini and Antigravity. The viewer says "Cerevisor does not open "…": it is in a folder that holds keys or passwords." This holds even inside a project or a folder you picked.
• Network shares, such as \\server\share\report.md, or anything reached through a link that leads to one. Opening a file on a share would send your Windows sign-in to that server. The viewer says "… is on a network share. Copy it to this computer first." A drive letter mapped to a share (Z:\) opens only inside a project or folder of yours that is itself on that drive. Workflows whose folder is on a share still run as before; only viewing is limited. On a computer whose home folder or AppData folder is redirected to a network share (common on company computers), this means the viewer cannot open files there either, including Cerevisor's own files.
• Programs and scripts. Open in OS never starts a program, a script, a shortcut or an installer (.exe, .bat, .ps1, .lnk, .app, and many more): "Cerevisor does not start programs or scripts. "…" was not opened."

The ready-made factory workflow

Deploy the ready-made factory (in Settings → Factory mode) fills the workflow with a Discuss, Plan, Develop, Check team of seven agents in five steps, and switches the factory on. When the workflow already has agents, the button reads Replace with the ready-made factory… and first asks: "This replaces the agents on this workflow with the ready-made factory." You can undo a replace with Ctrl+Z (⌘Z on a Mac). It keeps the workflow's name and settings:

1. Three researchers read the request and study the project: what the request is about, how the code is put together, and how it can be checked.
2. The approach collaborator reads their reports, works out the options, and asks you about each decision that changes what gets built, before it writes anything: one question at a time, with the option it recommends marked. It then writes approach.md with a Decisions section.
3. An approval step: approve this approach before it is planned.
4. The planner turns the approved approach into small tasks with the exact checks to run, in plan.md, and writes the acceptance criteria in acceptance.md.
5. An approval step: approve this plan before it is built.
6. The builder builds the plan in the project, runs the project's checks, aims at every criterion, and writes result.md: one plain paragraph on what now works (it becomes the item's summary), then How to Use It (the exact steps to open or start the result), the changes, what was checked and what is left. Before it finishes, it follows its own How to Use It steps.
7. The validator uses the result the way you will, checks the work against the request and the criteria, and writes the verdict in validation.md (Who checks the work).

Every file these agents read and write is kept in the item's own folder. On a second or later try, the approach collaborator, the planner and the builder read previous-attempt.md and build on the try before. No model is pinned and no skill needs to be installed. In attended mode you answer the approach questions and the two approvals. The planner and the builder ask you only when they are truly stuck; the researchers and the validator never ask, and choose the most sensible reading instead. An agent that runs on a service that cannot ask questions and wait for the answer (Cursor, Antigravity, Grok, or Claude Code set to not ask) decides on its own, and the Start summary names it. In unattended mode the model answers everything, and decisions.md records what it chose.

You can also run it by hand, like any workflow: with the Run button once the factory is switched off (while it is on, the Run button starts the factory), from a schedule, or from a script. There is then no request.md, so the request is the message you start the run with. Only the first researcher is given that message; it restates the request for the agents after it, and the other two researchers study the project in general and say at the top of their reports that they did not have the request.

You can change any of it like an ordinary workflow.

Known limits

• The phone has no view of the queue yet. An item is an ordinary run, so the phone companion shows it and lets you answer its questions, but the list of items lives only in the desktop app.
• There is no direct link from an item to its recorded run. The running item is on the canvas; a finished item's run is in the workflow's run history.
• Unattended items are always hands-free, whatever approval setting the workflow saved. That is what confirming Unattended agrees to.
• One item at a time, one factory per project folder. Items never run side by side.
• The factory works only while Cerevisor is open, and never starts by itself. Other programs can add items, but only you can start them.
• Pictures cannot be added from a script or the command line yet, only in the panel.
• The spending limit is checked between tries, so one try can go over it.