Skip to content

Software factory ​

The software factory turns a piece of work into a pull request without you sitting in the loop. You keep a kanban board for each project and write cards on it. An agent takes a card, fixes it in its own clone of the repository, the repository's own check command verifies the change, a second agent reviews it, and the factory pushes a branch and opens a pull request (a merge request on GitLab) as a dedicated factory account, or delivers a local branch for a project that is just a folder. Every change gets a risk tier, T0 to T3, that decides how much of your attention it needs. If CI fails it loops on the failures, up to a capped number of attempts, then stops and waits for you. You review and merge. The factory merges nothing on its own unless you turn on auto_merge_t0 or Full auto, and then only for trivial changes.

It works on GitHub, Azure DevOps and GitLab. Pull request, merge request and repository names below follow the forge you use.

The factory is free on the Personal plan, with 2 agent slots shared across all your projects. Projects and the board are free; more slots are a paid candidate.

Early access

The factory ships behind the factory.core release flag, which is off by default. Turn it on per node in Settings > Labs. See Feature Flags.

Set up ​

Setup has three required parts for a forge repository. Do them once per repository the factory may change. A folder project needs no factory account and no factory.toml in the repository. To give agents a full machine of their own (root, Docker, services), also set up a factory machine.

1. Create the factory OS user ​

On the node that hosts the factory account, create an operating system user named clusto-factory. It is a regular account with a shell, no password, and no git or GitHub credentials. If the repository needs pnpm or node to build and test, make them available to that user.

The agent runs as this user, so it cannot read your own files or credentials.

2. Add a factory account ​

The steps below are for GitHub. For Azure DevOps or GitLab see the end of this section.

  1. Open Settings > GitHub and add a separate GitHub account for the factory. Do not reuse your own.
  2. Set its Purpose to Factory.
  3. Enter the Organization the factory works in. The field appears when the purpose is Factory and is required for a factory account. One factory account serves one organization.
  4. Give it a fine-grained token scoped only to the repositories the factory may change, with these permissions:
PermissionAccess
ContentsRead and write
Pull requestsRead and write
IssuesRead and write
ActionsRead and write
ChecksRead
Commit statusesRead
MetadataRead

Workflows stays off, so the factory can never change a repository's CI. Make the token's resource owner the same organization, so GitHub enforces the same boundary as Clusto does. Create token on GitHub, under the token field, opens GitHub's new-token page with all of this filled in, the organization as resource owner included; pick the repositories, generate it and paste it back.

Your personal accounts stay on the Browse purpose and are never used by the factory.

Organization binding ​

The factory only starts work in repositories owned by the factory account's organization. The owner is matched case-insensitively, and the node's daemon enforces it, so a repository from another owner is refused even if it is sent by other means. The Send to factory repository picker lists only that organization's repositories.

Azure DevOps and GitLab accounts ​

A factory account on another forge works the same way, bound to its own boundary instead of a GitHub organization:

ForgeRepository nameBound to
GitHubowner/repositorythe account's organization
Azure DevOpsorganization/project/repositorythe account's Organizations list
GitLabgroup/.../projectthe account's Group
  • Azure DevOps. Add the account in Settings > Azure DevOps with a personal access token, set its Purpose field to Factory, and list the organizations it works in. The list must not be empty for a factory account: repositories outside it are refused. The factory finds its pull request by source branch, shows the tier as a label, reads PR builds and their failed task logs, retries them, and completes the pull request with the account's default merge type. Work items are the issues you can send. See Azure DevOps.
  • GitLab. Add the account in Settings > GitLab, set its purpose to Factory and its Group to the full path it works in (acme or acme/platform; subgroups are included). A repository must sit inside that group. The factory opens merge requests, labels them with the tier, reads pipelines and failed job traces, retries them, and merges with the expected head commit. GitLab accounts sit behind the gitlab.accounts flag in Settings > Labs (see Feature Flags). See GitLab.

The token stays on the account's host node on every forge, and the factory machine and the agent never see it.

3. Add factory.toml to the repository ​

Add .clusto/factory/factory.toml to the repository's default branch. Only check is required; this is the smallest useful file:

toml
check = "pnpm check"

A complete example with every key and a recipe:

toml
setup = "pnpm install --frozen-lockfile"
check = "pnpm check"
test = "pnpm test:e2e"
max_check_attempts = 2
max_ci_fix_attempts = 3
max_usd = 5.0
model = "sonnet"
review = true
review_model = "opus"
max_open_prs = 3
max_diff_lines = 600
intake_label = "factory"
plan = false
auto_merge_t0 = false
deploy = "pnpm deploy:prod"
holdout_pass_rate = 1.0
instructions = "Follow the conventions in AGENTS.md. Never edit generated files."

[recipe.feature]
description = "A new feature: plan first, review with a stronger model"
plan = true
review_model = "opus"
max_usd = 12.0
max_diff_lines = 900
instructions = "Add or update documentation for every user-facing change."
labels = ["feature", "enhancement"]

[recipe.cleanup]
description = "Small refactors and chores"
plan = false
review = false
max_usd = 2.0
labels = ["chore"]
KeyDefaultMeaning
check(required)The command that verifies a change, for example pnpm check. Exit 0 passes.
setuppnpm install --frozen-lockfileRuns once in the clone before the agent starts.
testunsetA slower command that runs after check passes, for example an end-to-end suite. Exit 0 passes. It has its own budget of max_check_attempts. Unset, the step is skipped.
max_check_attempts2How many times the agent may retry after the check command or the test command fails.
max_ci_fix_attempts3How many times the agent may push a fix after CI fails on the pull request.
max_usd5.0Agent spend per item before it stops and waits for you. Must be above 0.
modelthe agent CLI's defaultThe author's model.
reviewtrueA clean-context reviewer reads every change before the pull request opens.
review_modelthe agent CLI's defaultThe reviewer's model. A different model than the author's catches more.
max_open_prs3Open factory pull requests this repository may have at once; further items wait in the queue. At least 1.
max_diff_lines600Changed lines above which the change is sent back once to shrink, then to you. At least 1.
intake_labelunsetOpen issues carrying this label start items on their own (GitHub only). Unset, you start every item.
planfalseThe agent writes a plan first. A T2 or T3 item waits for you to approve it.
auto_merge_t0falseT0 items merge themselves once CI is green. See Auto-merge.
deployunsetA command that runs when you press Deploy on a merged item. See Auto-merge.
holdout_pass_rate1.0Share of holdout scenarios that must pass, from 0 to 1.
instructionsunsetExtra instructions added to every brief of this repository.

A key outside this list is an error, so a typo fails loudly instead of being ignored.

Recipes ​

A [recipe.<name>] table is a profile for one kind of work. The name is 1 to 40 lowercase letters, digits and -. Every key is optional and overrides the base value for items that use the recipe:

KeyMeaning
descriptionShown in the New card dialog.
plan, reviewTurn the plan step or the reviewer on or off.
model, review_modelModels for this kind of work.
max_usd, max_check_attempts, max_ci_fix_attempts, max_diff_linesBudgets and the size limit.
instructionsAdded after the base instructions in every brief.
labelsIssue labels that select this recipe when intake starts an item. The first matching recipe wins.

Name a recipe in the optional Recipe field when you add a card, or let intake pick one from the issue's labels. With no recipe the base values apply.

The file is read only from the default branch, so an agent's own branch can never change its rules. A project can also keep its rules in Clusto instead of the repository; see Rules.

4. Optional: add risk.toml ​

.clusto/factory/risk.toml tells the factory which parts of your repository are riskier than they look. It is also read only from the default branch. See Risk tiers.

Factory machine ​

By default the agent runs as the clusto-factory user on the node itself. For work that needs more, such as installing packages, running Docker or keeping services running between items, give the factory its own machine: an Incus system container on the node.

Map the OS user to the container in the node's config:

toml
[sandboxes]
clusto-factory = "clusto-factory"

The key is the OS user and the value is the Incus container name. Leave the section out and nothing changes. Edits apply on config hot reload to processes started after the change; running processes are not moved.

When a user has a sandbox, every process Clusto runs as that user runs inside the container instead of on the host, as the same user (same uid and gid, with the home directory mounted at the same path): the factory's setup and check commands, the agent chat, git, and terminal sessions. Inside the container the agents can use sudo, run Docker, install packages and keep services running. Root in the container is not root on the host.

  • Shell on the factory machine. Open a terminal session on that node with run as clusto-factory and you get a shell inside the container. Use it to look around, install tools or sign the agent CLI in. Signing in happens inside the container as that user, and the login stays in that home.
  • The token stays out of reach. The node's daemon and the factory's GitHub token stay on the host. The container cannot read them, so an agent cannot push to your default branch or merge its own pull requests.
  • Internet only. The container's network reaches the internet. Private address ranges, the host's daemon port and the tailnet are blocked.

Requirements:

  • a Linux node, with the daemon running as root,
  • Incus installed on the node, with a container prepared for the user,
  • the user must exist on the host and in the container with matching user and group ids.

To move the factory to another machine, move the factory account's host node (see GitHub), then prepare the container on that node and add the [sandboxes] entry there. The GitHub token is handed over to the new host list. Standby nodes do not run factory work: it stays on the host node. See the configuration reference for the key.

Projects ​

The Factory view is organised by project. Under the view header sits a row of tabs: Board, Team, Channel, Insights and Settings. Team and Channel show only while the company.agents flag is on (see Company). The tab you pick is remembered.

The rail on the left is the scope for every tab. It lists All projects first, then your projects grouped by owner:

  • Forge projects sit under their organization, named after the owner of the repositories (for example RobotaWorks). When that factory account has a company, the organization also shows a Team link and a count of what is waiting on you.
  • Folder projects sit under On your nodes.

Pick a project to scope the tab to it, or pick All projects for the board across every project, where each card shows its project as a tag. Press Add project on the rail to start the wizard. On a phone there is no rail: the scope is the project picker in the view header.

A project is one of:

  • A forge repository. A repository inside a factory account's boundary on GitHub, Azure DevOps or GitLab. Finished work is delivered as a pull request.
  • A local folder. A git checkout on any of your nodes. It needs no factory account and no forge.
  • A new repository. Clone a URL into a folder on a node, or create an empty folder with git init.

Repositories outside your organization work through fork pull requests: the factory account forks the repository into its own organization, pushes there and opens the pull request upstream. Fork pull requests are GitHub only. Upstream CI and the merge are the maintainers', so the card waits in Review until the pull request closes.

The Add project wizard ​

  1. Where is the code. An existing Clusto project (its folder, node and run-as user, and its agent docs join every brief), a repository of a factory account, a git URL to clone into a new folder on a node, or a new empty project (a folder with git init). For a monorepo app, a subfolder makes setup, check and test run there.
  2. Who runs the agents. The runner node and, for a folder project, the user the agents run as.
  3. Rules. The daemon looks at the checkout and detects the stack (Node with pnpm, yarn, bun or npm, Rust, Go, Python, or a Makefile) and suggests setup, check and test commands. You edit them and choose where they live, see Rules.
  4. Delivery and autonomy. How finished work leaves the factory and how much the agents do on their own.
  5. Dry run. Runs setup, check and test once in a fresh clone and shows the result, so a red check on an untouched branch shows up before any card fails because of it.

Projects replicate across your cluster, so you can edit a project or its board from your phone while the runner node is offline. Only the runner node runs the agents.

Project settings ​

The Settings tab is a full page for the selected project. With All projects selected it lists the projects so you can pick one. It holds:

  • Runner node. The node that runs this project's agents.
  • Delivery.
    • Pull request - the factory account pushes a branch and opens a pull request (a merge request on GitLab).
    • Fork pull request - as above, from a fork (GitHub only).
    • Local branch - the checked branch is delivered into the folder as factory/<slug>-<card>. An approved run fast-forwards your target branch. It waits while the folder has uncommitted changes on that branch or has it checked out in another worktree. If the target moved on, the agent gets a merge-conflict turn first.
    • Push branch - the branch is also pushed to a remote you name.
  • Autonomy. Manual, Auto or Full auto.
  • Runs at once (WIP limit) - how many agent runs this project may have at once.
  • Weight - this project's share of agent slots against other projects.
  • Paused - the dispatcher skips a paused project.
  • Rules overlay - see Rules.
  • Dry run - see the Add project wizard.
  • Holdouts - see Holdout scenarios.
  • Issue sync - see Issue sync. It lives on the Main board's link now.
  • Delete - removes the project.

When a company is in scope, a Project | Company switch at the top of the page shows the company roster page instead.

Folder projects ​

A folder project runs as a user you choose, never as root. Each run works in its own clone in that user's home directory, so your own checkout and stash are never touched. The folder is read and written only as that user.

Running as your own account gives the agents your files and credentials, so the project settings show a warning and Auto and Full auto require an explicit acknowledgement. If the run-as user has a factory machine entry, the run happens inside the container.

The board ​

The Board tab shows the selected project's kanban board with six columns:

ColumnMeaning
BacklogIdeas that are not committed to yet.
ReadyAgents may take these, top card first.
In progressAn agent is working on the card.
ReviewWaiting on you: a plan to approve, a pull request to merge, or a run that stopped.
DoneMerged or delivered.
BlockedNeeds input or another card first.

A card shows its pipeline state as a chip (planning, coding, check, AI review, CI, holdouts, conflicts), a spinner while an agent turn is live, its risk tier once known, its cost, and its pull request as a link. Open a card to see its details, the plan, the agent's chat, the changes and its runs. On desktop the card opens in a centered dialog over the board; close it with the X or Escape (Escape inside a text field does not close it, so typed edits are kept). On a phone it opens as a full-screen view.

A project can have several boards. Every project has a Main board, and cards from before boards existed are on it. A board row above the columns switches boards (tabs on desktop, a picker on a phone), shows a linked repository as a badge and how many cards on the board need you. The row's menu has:

  • Edit - rename the board or change its GitHub link.
  • Import issues - on a linked board, see Issue sync.
  • Delete - not available for the Main board, and only once the board has no cards.

New board adds one. The project still owns the repository, rules, runner, autonomy and run limit, and agents pick Ready cards from all of the project's boards.

One row of controls sits above the board: the project name, the autonomy select, an agents chip, a "needs you" chip that filters the board to Review and Blocked, Task for a quick add, and a ... menu with Refresh, New card, Add project and, when a company is in scope, Pause, Resume and Reload roster. Rules, Holdouts, Insights and project settings are tabs and pages now, not menu entries. The Review column replaces the Inbox.

Add a card ​

Use the quick add to type a title and press Enter (Shift+Enter starts the description on a new line). Add puts the card in Backlog and Add to Ready queues it for agents right away. New card in the ... menu builds a card from an open issue (a work item on Azure DevOps), from a failing CI run on the default branch, or from a typed task. You can also file cards from the command line, from an agent, from a GitHub view issue with Send to factory, or by issue sync. Choose a recipe in the optional Recipe field to use one of the repository's [recipe.<name>] profiles. Adding a card starts nothing by itself.

Move cards ​

Drag a card between columns. Each drop is one action, and a drop that is not allowed has no drop target.

DragWhat happens
Backlog or Ready to In progressStarts the card now.
In progress back to Backlog or ReadyStops the run. The card keeps its history.
Review to DoneMerges the pull request, after you confirm. For a plan review or a run waiting on you, it marks the card done instead.
Review to ReadySends the card back, with an optional note. The agent continues on the open pull request.
Anything to BlockedNeeds a note saying why.
Within a columnReorders the cards, which sets their priority. Not in Review or Done.

On a phone, a column switcher shows one column at a time instead of all of them side by side, and a card's action menu replaces drag and drop.

Cards and runs ​

A card can have several runs. Retry starts a new run of the same card instead of resetting the old one, so the card keeps a history of attempts. If the card still has an open pull request, the new run continues on that branch and pull request. If the pull request is closed, it starts fresh.

Card actions ​

  • Link issue / Unlink - tie the card to a GitHub issue of the board's repository (see Issue sync).
  • Move to board - send the card to another board of the same project. Link issue, Unlink and Move to board are disabled while a run holds the card.
  • Take over chat - stop the factory driving the card so you can type in its chat yourself.
  • Retry - start a new run with fresh attempts and a fresh budget. On a card you took over, this hands it back to the factory.
  • Abandon - stop the run. An open pull request stays open.
  • Address review - send the new review comments on the pull request to the agent so it pushes a follow-up.

Autonomy ​

Each project has an autonomy level:

LevelWhat the factory does
ManualAgents wait. You start each card, by dragging it to In progress. You merge.
AutoAgents pick Ready cards on their own, top first. A plan rated T2 or T3 waits for you. You merge.
Full autoAgents plan, build, test and review on their own. Plans are approved automatically up to tier T1, and T0 changes merge on their own.

In Full auto, plans are approved up to T1 and T0 changes merge on their own by default. Both ceilings are selects on the Settings tab. Auto-merge of T1 changes is planned as a Pro feature and cannot be turned on yet. T2 and T3 changes never merge on their own, and a production deploy is never automatic, at any level.

Dispatcher ​

The dispatcher fills free agent slots from the Ready columns of every unpaused Auto or Full auto project. Slots are one pool for the whole node, because agent turns are the scarce resource. On the Personal plan there are 2 slots.

  • Slots are shared across projects by weight, so a project with weight 2 gets twice the slots over time and a busy project never starves a quiet one.
  • A project never goes over its WIP limit or its max_open_prs.
  • A card with dependencies waits until every card it depends on is Done.
  • Only the project's runner node claims its cards, so two nodes can never take the same one.

Rules ​

A project's rules come from three places, highest first:

  1. The owner overlay, kept in Clusto, outside the repository. It takes the same keys as factory.toml plus risk rules. An agent cannot change it, and it is the way in for repositories you cannot or do not want to commit to.
  2. .clusto/factory/factory.toml and risk.toml on the repository's default branch (the target branch for a folder project).
  3. Built-in defaults.

The files merge key by key, and the overlay wins. A project needs a check command from one of them before it can run cards.

Publish rules writes the current overlay into the repository. For a forge project it opens a pull request adding the files; for a folder project it writes a factory/rules-* branch in the folder.

The risk floor stays on whatever the overlay says: the built-in T3 paths still apply, the reviewer can only raise a tier, and holdouts are never shown to the agent.

Planner subtasks ​

With plan = true, a plan can split a card into subtasks. If the plan ends with a block of subtasks, the factory files up to 12 child cards with dependencies between them. Children are Ready, or Backlog on a Manual project. The parent card stays in In progress, and moves to Done when every child is Done. The parent's own run ends with the note "Split into N subtask cards".

Issue sync ​

A board can be linked to the open issues of a GitHub repository. The Clusto board stays the source of truth. GitHub only for now; Azure DevOps and GitLab issue links are not built yet.

Open the board's menu, choose Edit board and then Link GitHub issues:

  • Account - any GitHub account from Settings > GitHub (browse or factory purpose).
  • Repository - owner/name.
  • Auto import new issues - optional, with an optional label filter. The node hosting the GitHub account checks every 10 minutes.

A link only reads. Clusto does not comment on or close issues through it. The one exception is a forge project's Main board, linked through the project's own factory account on its own repository: after a run merges, the factory comments on its issue and closes it. This replaces the old "Mirror the repository's issues onto the board" project setting, which became the Main board's link.

Import issues ​

Import issues opens the repository's open issues (up to 500, newest updated first). Search, tick the ones you want and choose Import. Each becomes a Backlog card titled "#N title" with the issue body as its brief and the issue's labels. Issues already on the board are greyed out and skipped.

Cards and issues ​

  • A card's overview has Link issue and Unlink for an existing card.
  • A card whose issue is closed on GitHub moves to Done on its own. The factory checks every 10 minutes, for cards no run holds.
  • On a folder project, the run's brief is the issue, with an instruction to end the commit message with Fixes owner/repo#N. Pushing the delivered branch then closes the issue on GitHub.

For forge projects, issues carrying the project's intake_label still become cards on the Main board (GitHub only).

From the command line and agents ​

bash
clusto factory projects
clusto factory board --project shoptet-seo
clusto factory board --project shoptet-seo --board Bugs
clusto factory card add --project shoptet-seo --title "Fix the sitemap" --body "..." --column ready
clusto factory card add --project shoptet-seo --board Bugs --title "Fix the sitemap"
clusto factory card move <id-or-prefix> review --note "Needs a test"

--project takes a project name or id. --board takes a board name or id and defaults to the Main board. factory board prints each board's columns. --column is backlog or ready and defaults to Backlog. card move takes a card id or any unique prefix of it, as factory board prints it, and a column (backlog, ready, in-progress, review, done or blocked). --note is the block reason, or the note for the agent when you send a card back.

Agents on your nodes get two tools through clusto mcp: clusto_factory_projects lists projects, and clusto_factory_file_card files a Backlog card labelled proposed for you to accept by dragging it to Ready. Company employee proposals show up as the same kind of Backlog card.

Existing factory setups ​

On upgrade, each repository the factory already worked on becomes a project in Auto mode, so a repository with an intake_label keeps starting labelled issues on its own. Existing items become cards.

Risk tiers ​

Every change gets one of four tiers. The tier decides how much of your attention it needs, and it is shown as a badge on the item, as a label on the pull request (factory:t0 to factory:t3) and as a Risk tier line at the top of the pull request description, with the reasons and the reviewer's explain-back card below it.

TierNameWhat it means
T0Auto-mergeNo behavior change, such as documentation or lock files only. May merge itself once the repository allows it.
T1Owner skimThe default: a small tested change. AI review plus your skim.
T2Line reviewRead the diff line by line.
T3Designed firstYou design first; the factory builds only what you approved.

The factory takes the highest tier any signal reaches:

  • Built-in T3 paths: CI and deploy definitions (.github/workflows/**, .github/actions/**, .gitlab-ci.yml, azure-pipelines.yml, .azure-pipelines/**), Dockerfile, any migrations folder and the factory's own .clusto/** files.
  • Your risk map: .clusto/factory/risk.toml, below.
  • Diff signals: a changed dependency manifest, more than 400 changed lines or 15 files (T2); SQL schema changes and cryptography (T3); new environment or secret references, new routes or endpoints and new network calls (T2); code changed without a test change (one tier up); and more assertions removed than added in tests (T2).
  • The agent and the reviewer each rate the change too. They can only raise a tier, never lower it.

A change that touches only documentation or lock files starts at T0; anything else starts at T1.

risk.toml ​

Add .clusto/factory/risk.toml to the default branch to mark paths that matter in your repository. Each [[rule]] names glob patterns, the tier a match forces and an optional reason shown on the pull request:

toml
[[rule]]
paths = ["src/billing/**", "src/auth/**"]
tier = "t3"
why = "money and identity"

[[rule]]
paths = ["src/api/**"]
tier = "t2"

tier is t0 to t3. Each rule needs at least one path. why defaults to the first matching path. The map can only raise a tier.

Item flow ​

A run moves through these states. The current one shows as a chip on its card.

StateWhat happens
QueuedClaimed from Ready, waiting for a free agent slot, or for an open pull request slot (max_open_prs).
Setting upThe clone is made and setup runs.
PlanningWith plan = true, the agent writes a plan before any code.
Plan to approveThe agent rates its own plan. A plan it rates T2 or T3 waits for you; any other goes ahead on its own.
Coding, Checking, Fixing checkThe agent works, your check runs, then your test command if set, and failures go back to the agent up to max_check_attempts.
AI reviewA clean-context reviewer reads the task and the diff. A P1 finding goes back to the author within the check budget. The reviewer must not touch the clone; if it does, the item stops.
Opening PRThe branch is pushed and the pull request opens with the tier label. For a folder project the branch is delivered into the folder instead.
CI running, Fixing CICI runs. Failed jobs are re-run once to rule out a flake before a fix attempt counts. Real failures go back to the agent up to max_ci_fix_attempts.
Holdouts runningWith holdout scenarios set, they run after green CI.
Ready to reviewGreen. You review and merge.
MergingYou approved the merge (shown with an Approved badge). The factory merges the pull request at the commit it pushed.
Resolving conflictsThe approved pull request conflicts with the default branch. The factory fetches the latest default branch into the clone and the agent merges it in and resolves the conflicts, up to 2 attempts. The change then goes through the check, AI review and CI again and merges on green without asking you again.
Addressing reviewThe agent answers your review comments. Sending new review comments withdraws an approval.
Needs youStopped: attempts, budget or size limit used up, or a stalled turn.

Other guards:

  • Size gate. A change above max_diff_lines goes back to the agent once to shrink. If it is still too large it goes to you.
  • Stalled turns. An agent turn that has not finished in 60 minutes counts as stuck and the item goes to you.
  • Open pull request cap. Runs above max_open_prs for a repository wait in the queue, so the factory never produces more than you can review.
  • Label intake. With intake_label set, open issues carrying that label become cards. On an Auto or Full auto project, which is what existing repositories become on upgrade, they start on their own. An issue the factory has ever worked on is not started again. GitHub only; on Azure DevOps and GitLab you add cards yourself.

Review ​

The Review column collects everything that waits on you, and works from a phone. The Inbox tab is gone: the "needs you" chip in the board header filters the board to Review and Blocked, and All projects shows Review across every project.

With Company on, questions from employees wait in the company's Team tab (reached from the organization's Team link in the rail), and the tasks employees propose arrive as Backlog cards labelled proposed. Drag one to Ready to accept it.

  • Plans to approve. Open the card, read the agent's plan and press Approve plan. The optional Notes for the agent field changes the plan before it codes. The agent writes no code until you approve.
  • Ready to merge. T3 and T2 first. Each entry shows the reviewer's explain-back card (a walkthrough and questions meant to test your understanding) and the holdout result. Merge asks you to confirm, naming the pull request and its tier. Dragging the card to Done does the same. Confirming approves the card: it shows Approved and the factory account merges it. If the branch has merge conflicts, the agent resolves them first and the factory merges once CI is green again. A merge cannot be undone from Clusto.
  • Stopped for you. The reason is shown. Retry starts a new run with fresh attempts and a fresh budget; Abandon stops the run and leaves any open pull request open. Dragging the card to Ready sends it back with an optional note instead.
  • Sampling audits. One in 20 merged T0 and T1 items is picked for a second look, because those were merged without a line review. Read the change and press Audit clean or Audit finding. The results feed the Audit finding rate in Insights.

Holdout scenarios ​

A holdout scenario is an acceptance check you write for a repository that the agent never sees. After CI is green, the factory runs every scenario against the change. A miss goes back to the agent by scenario name only, so it can fix the behavior without being able to read or game the test.

Open Holdouts on the Settings tab and press Add scenario. A scenario is a name (up to 120 characters) and a shell script (up to 64 KiB) that exits 0 when the change behaves correctly. It runs as root in a fresh clone of the change after the repository's setup, with a 10 minute limit per scenario.

  • Scripts are stored on the host node only, never replicated to other nodes and never quoted into an agent's brief, a log or a notification.
  • Each run happens in a throwaway copy of the factory machine's clean snapshot, with the agent's home folder removed. The agent's own container is not touched and shares nothing with it. This means holdouts need a factory machine: a node with a [sandboxes] entry for clusto-factory and a clean snapshot of that container.
  • holdout_pass_rate sets how many scenarios must pass (default all of them). With no scenarios, the step is skipped.

Auto-merge and deploy ​

  • auto_merge_t0 is off by default. When on, a T0 item approves itself once CI is green and any holdouts pass, then merges like an item you approved, conflict resolution included. Turn it on only after the sampling audit has shown a low finding rate on your repository. A project in Full auto merges T0 changes on its own by default.
  • Deploy. A merged item shows Deploy when the repository's deploy command is set. Pressing it asks for confirmation, then runs the command on the host as the agent user in a fresh clone of the default branch. Deploying is outward-facing, so it is always started by you and never by the factory.

Factory chats ​

Each item's agent runs in a chat. The item dialog in the Factory view shows it in place: pick the Chat tab under the item's actions to read and reply without leaving the board. Changes shows the pull request's description, checks and diff in the same spot, and Details the item's facts and verification. The tab you pick stays picked as you move between items.

Factory chats stay out of the Chats list so they do not crowd your own conversations. Use Show factory chats at the bottom of the Chats tree (or the command palette) to list them on this device. Shown factory chats have a factory icon.

While the factory drives an item, its chat is read-only: a banner above the composer says what the factory is doing, and the node refuses a message typed into the chat from any client. Take over in the banner hands you the chat; Hand back returns it to the factory. Stopping a running response stays available at any time.

Insights ​

The Insights tab is a full page with the numbers for the selected project, or for all projects when All projects is selected. It shows:

  • Merged - how many factory pull requests you merged.
  • Cost per merged PR - agent spend divided by merged pull requests.
  • Rework - the share of merged changes whose files changed again on the default branch within 21 days.
  • Open pull requests, cards waiting on you, CI fixes per merge, abandoned runs, merged changes by tier, the sampling audit finding rate, and spend per repository and per week.

Watch the audit finding rate before you enable auto_merge_t0 or Full auto.

Spend is the figure the agent CLI reports. On a subscription plan it is notional, not money charged to you.

Company ​

The factory only works on what it is given. With the company.agents flag on, Company adds persistent AI employees on the same factory account. Each company appears as a Team link under its organization in the rail, and the Team and Channel tabs show it. Employees wake on a schedule, message each other and you, and file proposals that land as Backlog cards labelled proposed. Every run's agent also joins the company as a task worker, so you can message it from the Team tab without taking the card over.

Safety ​

  • The agent runs as the unprivileged clusto-factory user with no MCP servers, optionally inside a factory machine container.
  • The factory works only in repositories inside the factory account's organization, Azure DevOps organizations or GitLab group.
  • The agent never sees the forge token. Only the daemon pushes branches and opens pull requests.
  • The risk map, tiers and the reviewer can only raise a change's tier, never lower it, and a reviewer that touches the clone stops the item.
  • Holdout scenarios stay on the host and never reach the agent.
  • Deploy is started only by you; auto-merge of T0 changes is off until you turn it on or choose Full auto.
  • Forge text such as issue bodies, logs and review comments is passed to the agent as quoted data, not as instructions.
  • The check command and limits come from the default branch only, or from the owner overlay kept in Clusto, which an agent cannot change.
  • Folder projects run as a user you choose, never as root, in a clone of their own. Running as your own user needs an explicit acknowledgement.
  • T2 and T3 changes never merge on their own, at any autonomy level.
  • Every change reaches your default branch only through a pull request that you merge.

Notifications ​

The factory raises notifications when a card needs you, when a plan waits for your approval and when a pull request is ready. Like the GitHub alerts, you can mute them per device.

Clusto - remote AI coding agents over WebSocket.