# What is Millrace?

Millrace is an open-source, filesystem-backed runtime for long-running autonomous agent work. It surrounds raw agent harnesses with durable structure. The core split is:

- a stage agent does one bounded unit of reasoning and emits one legal result
- the runtime decides what the next stage is, when it runs, and what state change is authoritative
- the workspace keeps durable queue state, compiled runtime structure, recovery context, and run artifacts

That makes Millrace useful when an ordinary direct agent session is no longer enough on its own because the work is multi-stage, interruption-prone, recovery-sensitive, or closure-sensitive.

## What Millrace is not

Millrace is not any of the following:

- a coding model
- an IDE
- a hosted autonomous engineer product
- a general chat workflow
- a replacement for Codex CLI, Claude Code, or Aider

Those tools are direct harnesses, editors, or managed products. Millrace is the runtime and governance layer that can sit around raw harness execution.

## What Millrace owns

Millrace owns runtime authority over:

- queue movement between queue, active, done, blocked, incoming, and resolved directories
- active-stage identity and runtime snapshot state
- recovery counters and stale-state repair context
- compiled plan persistence
- run directories and stage-result artifacts
- closure-target state for Arbiter-driven completion

Millrace does not delegate that authority to stage prompts. Stages do not directly mutate authoritative queue state. They emit legal terminal results, and the runtime applies the authoritative state changes after the fact.

## Workspace model

Millrace bootstraps its runtime tree under `<workspace>/millrace-agents/`.

Canonical work documents are markdown:

- tasks: `millrace-agents/tasks/{queue,active,done,blocked}/*.md`
- specs: `millrace-agents/specs/{queue,active,done,blocked}/*.md`
- incidents: `millrace-agents/incidents/{incoming,active,resolved,blocked}/*.md`

Canonical runtime/state artifacts include:

- `millrace-agents/state/runtime_snapshot.json`
- `millrace-agents/state/recovery_counters.json`
- `millrace-agents/state/compiled_plan.json`
- `millrace-agents/state/compile_diagnostics.json`
- `millrace-agents/state/execution_status.md`
- `millrace-agents/state/planning_status.md`

Run artifacts persist under `millrace-agents/runs/<run-id>/`.

## Planes and loops

Millrace currently runs two planes:

- execution
- planning

The shipped built-in loop ids are:

- `execution.standard`
- `planning.standard`

The shipped canonical mode ids are:

- `default_codex`
- `default_pi`

The compatibility alias `standard_plain` resolves to `default_codex`.

The execution loop stages are:

- `builder`
- `checker`
- `fixer`
- `doublechecker`
- `updater`
- `troubleshooter`
- `consultant`

The planning loop stages are:

- `planner`
- `manager`
- `mechanic`
- `auditor`
- `arbiter`

## Runner model

Millrace does not make the harness itself the runtime authority. Instead, it freezes runner choice into the compiled plan and dispatches stage runs through a narrow contract:

- `StageRunRequest -> RunnerRawResult`

As shipped, the built-in adapters are:

- `codex_cli`
- `pi_rpc`

`default_codex` binds every shipped stage to `codex_cli`. `default_pi` binds every shipped stage to `pi_rpc`. `standard_plain` is only an alias for `default_codex`.

## When to use Millrace

Use Millrace when any of the following matter:

- the work must survive pauses, crashes, or context loss
- durable queue state matters
- stage progression should be runtime-governed instead of conversational
- recovery routing matters more than one-shot speed
- you need persisted run artifacts, runtime snapshots, or diagnosable failure surfaces
- closure should be based on runtime criteria rather than "the agent said it was done"

Good fits include:

- long-running implementation work that will outlast one session
- planning-to-execution flows that need durable decomposition and auditability
- repair-sensitive work where blockage should route into `mechanic` or `troubleshooter`
- closure-sensitive work where an Arbiter pass should judge completion against contracts

## When not to use Millrace

Prefer a direct raw-harness session when all of these are true:

- the task is small and likely to finish in one session
- durable queue state is unnecessary
- staged planning or execution gates are unnecessary
- interruption or retry cost is low
- no persisted run trail or closure pass is needed

Bad fits include:

- a small direct bugfix in one file
- a short exploratory coding spike
- an ordinary repo edit where governance overhead would be larger than the work
- source-repo maintenance where no runtime workspace is actually being operated

## Start-here commands

Installed surface:

```bash
pip install millrace-ai
millrace compile validate --workspace <workspace>
millrace status --workspace <workspace>
millrace queue ls --workspace <workspace>
```

Module form during source development:

```bash
uv run --extra dev python -m millrace_ai status --workspace <workspace>
```

See also:

- `/ai/install.md`
- `/ai/cli-reference.md`
- `/ai/modes-and-loops.md`
- `/ai/comparisons.md`