Workers and runners
The work on your repo is done by workers: temporary agents that each do one item. They run on runners, the machines you pair, in the Claude Code or Codex CLI, with a profile: one of your CLI setups on that machine.
Workers and validators
Section titled “Workers and validators”When an item is ready, Minga starts a worker for it. A worker gets a ref (W-12) that is never reused in the project,
and shows on Team and in the runs list while it works (“W-12 · Welcome screen · my-mac”).
A worker reads the brief, its item’s full spec and checks, the specs of the items above it, and any outputs passed to it. It works in its own worktree of your repo, reports what it did (done with evidence, progress and what is next, blocked, a question, or impossible) and attaches what it made. A done claim moves the item to review; it is never done straight away.
A validator (V-3) is a separate run that checks a worker’s result against the item’s rubric and commands. By
default it runs on the other model family: Codex checks Claude Code’s work and the other way round.
Worker presets
Section titled “Worker presets”How a project’s workers work is set in Project settings › Temporary agents. Every project has two presets:
| Preset | Works in | Use it for |
|---|---|---|
| Default | The project’s repo: a worktree on a new branch from the base branch, and a pull request against it | Code |
| No repo: research, data | A scratch directory, no repo, no gh, no pull request |
Research, data, writing |
A preset can also name a preferred CLI and the model and effort to use with each. A project has at most eight presets.
Runners
Section titled “Runners”A runner is the minga service on one of your machines: a Mac, a Linux box, a VPS. It connects out to Minga over a
WebSocket and keeps that connection open. Minga never connects into your machine.
A runner:
- reports what it can do: its profiles, whether each CLI is signed in, which models it offers, which repos it has;
- takes runs for your workspace, up to its capacity (four at a time by default);
- runs each one in the CLI, streams the transcript to Minga as it goes, and reports how it ended;
- updates itself to new signed releases when it is idle.
One machine is paired with one workspace. See Pair a runner and add profiles.
Profiles
Section titled “Profiles”A profile is one CLI setup on a runner: the CLI (Claude Code or Codex) and its home directory, such as ~/.claude or a
second Codex home for work. Each profile has an access mode that decides how much its
runs may do without asking: Auto (the default), Ask or Full. A run can never get more than its profile
allows.
Which runner gets a run
Section titled “Which runner gets a run”Minga sends a run to a runner that is online, has a profile for the right CLI that serves this workspace, and has the repo the item needs. If no such runner is online, the run waits and the item says waiting for a runner. It starts as soon as one comes online: your laptop wakes, or the VPS reconnects.
A Linux machine or a VPS that stays on keeps work moving overnight.
Leases
Section titled “Leases”When a runner takes a run, it holds a lease on it and renews it while the run lives. If the machine goes to sleep or crashes, the lease runs out and the run ends with the reason “the runner went offline”. Minga starts the item again once; if the runner is lost a second time, you get a card.
Worktrees and your clone
Section titled “Worktrees and your clone”The runner works in the clone you already have. For each item it adds a git worktree on a local minga/… branch
under ~/.local/share/minga/worktrees, so workers never touch your working copy. In your clone the runner only
fetches and adds or removes worktrees. See Attach a repo.
Every run ends with a reason
Section titled “Every run ends with a reason”Every run ends with a stated reason, and the item and the runs list show it in words:
| Reason | What happened |
|---|---|
| completed | The CLI ended its turn on its own |
| interrupted | Someone stopped the run |
| cancelled | It was cancelled before it started |
| max turns, wall clock, context exhausted | It hit a turn, time or context limit |
| rate limited | The profile hit its provider’s limit |
| auth error | The CLI is signed out, or the key was refused |
| permission denied | A permission it needed was denied, and it could not go on |
| policy refused | The runner’s own limits refused the run |
| sandbox error | The worktree or environment could not be prepared |
| CLI error | The CLI crashed or exited with an error |
| the runner went offline | The machine slept, closed or crashed during the run |
| Minga’s tools didn’t load in the CLI | The run could not reach Minga, so it stopped before starting |