Skip to content

Apache-2.0 · Python 3.11+ · open source

Agents that prove their work.

mini-ork turns a goal into a planned, executed and verified run across a fleet of different models. The verdict on every change is what the code actually did when it ran — tests, type checks, schemas, real execution in an isolated sandbox — not a model's opinion of its own output.

Get started Why verification

curl -fsSL https://raw.githubusercontent.com/SourceShift/mini-ork/main/install.sh | sh

Start here

  • New to mini-ork

    Install it, write a kickoff, and watch a run go from goal to verdict in about five minutes.

    Quickstart

  • Understand the model

    Task classes, recipes, nodes, lanes, gates and artifact contracts — the six objects every run is made of.

    Core concepts

  • Run it for real

    Worktree isolation, review gates, cost caps, recovery and failure triage for work you intend to ship.

    Guides

  • Look something up

    Every subcommand, every environment variable, every schema — generated from the dispatcher and the source.

    CLI reference

What it is

mini-ork is a task operating system for agents. You hand it a kickoff — a markdown file describing an outcome — and it runs a fixed loop:

flowchart LR
    A[classify] --> B[plan]
    B --> C[execute]
    C --> D[verify]
    D --> E[reflect]
    E --> F[improve]
    D -- fail --> C
    E -. lessons .-> B
  • Heterogeneous models. Each node is routed to a lane — a model + provider pair — by role. A cheap model plans, a strong one implements, a separate one verifies.
  • Execution is the oracle. Gates read what a command returned, not what a model said. A judge can veto a pass; it cannot manufacture one.
  • Cost is governed. Per-model spend meters at list price, with a daily circuit breaker, a cost-pause sentinel and a wall-clock deadline.
  • Learning is earned. Contexts, prompts and routing only change when a measurement says the change did not regress.

Common paths through these docs

If you want to… Read
Get a first run working Quickstart → Your first run
Write a good kickoff Writing a kickoff
Understand a verdict Verification and gates → Certifying a change
Control spend Cost governance → Providers and lanes
Fix a failed run Failure triage → Recovery
Extend the engine Extending mini-ork
Look up a flag CLI reference

Project