Skip to content

Quickstart

This page takes you from nothing to a verified run in about five minutes. You need Python 3.11 or newer, git, and at least one provider credential (an Anthropic key or an OpenAI-compatible endpoint). Everything else is created by mini-ork init.

1. Install

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

The installer clones the engine into $HOME/.local/share/mini-ork, installs system dependencies, and puts a mini-ork command on your PATH. To install from an existing checkout instead, see Installation.

Confirm the CLI is reachable:

mini-ork --help
mini-ork doctor

doctor reports the tools it found, which engine is running, and which provider credentials are visible. Warnings are not fatal — you only need one working lane.

2. Initialise the project

Run this in the repository you want mini-ork to work on:

cd /path/to/your/project
mini-ork init

init creates a .mini-ork/ home containing:

.mini-ork/
  config/          task classes, agents.yaml, providers.yaml
  runs/            one directory per run
  kickoffs/        kickoff templates
  INBOX/           review-gate decisions
  locks/           run leases
  state.db         SQLite state
  engine           pointer to the installed engine

It also writes the ignored-state entries into .gitignore. .mini-ork/engine is the one file you commit, so collaborators resolve the same engine.

3. Pick a lane

Open .mini-ork/config/agents.yaml. Each role maps to a lane — a provider and model pair:

planner:
  lane: claude
implementer:
  lane: claude
verifier:
  lane: claude

If you have a different provider configured, change the lane names to match .mini-ork/config/providers.yaml, or run:

mini-ork providers configure <lane>

providers status shows what is configured without ever printing a key.

Start with one lane

A single strong lane is enough for a first run. Add cheap lanes for planning and reflection once you have seen the loop work.

4. Write a kickoff

A kickoff is a markdown file describing the outcome. The shipped example is a good template:

cp examples/01-hello-world/kickoff.md ./kickoff.md

The important sections are the problem, the definition of done, an explicit scope, and success criteria that a command can check:

## Problem

The project has no record of the new session-token-rotation work under the
`[Unreleased]` section of `CHANGELOG.md`.

## Definition of Done

New entry exists in `CHANGELOG.md` under `## [Unreleased]`.

## Scope

Only `CHANGELOG.md` may be edited.

## Success Criteria

- `grep -A3 "## \[Unreleased\]" CHANGELOG.md` returns at least one bullet line.
- No other file in the repository is modified.

See Writing a kickoff for the full contract.

5. Run

mini-ork run code-fix ./kickoff.md

run walks the lifecycle: classify → plan → execute → verify. You will see one block per stage, ending in a verdict:

[classify]  task_class=code_fix  risk=medium  confidence=0.96
[plan]      steps: 1  estimated_lines_changed: 5
[implement] files_changed: CHANGELOG.md
[verify]    gates: 4/4 passed
[verdict]   PROVEN

You can also let the classifier choose the recipe:

mini-ork run ./kickoff.md

6. Inspect the run

Every run gets a directory under .mini-ork/runs/<run-id>/ containing the plan, node outputs, gate logs and the verdict. Two ways to look at it:

mini-ork board                  # project state as JSON
mini-ork board show <run-id>    # one run

Or query state directly:

sqlite3 .mini-ork/state.db \
  'SELECT id, recipe, status, verdict FROM task_runs ORDER BY created_at DESC LIMIT 5;'

To watch runs in a browser, start the local web app described in The web app and IDE.

What a verdict means

Verdict Meaning Next step
PROVEN The gates ran and passed on the produced change Review the diff, then merge
REFUTED A gate ran and failed Read the failing gate, fix, re-run
UNVERIFIED No gate produced a trustworthy signal Do not ship; add a check
VACUOUS The run passed nothing meaningful Treat as a failure

If something goes wrong

  • Run mini-ork doctor and mini-ork validate.
  • A run that stopped mid-way can be resumed: mini-ork run --resume <run-id>.
  • Common first-run failures are collected in Troubleshooting and Failure triage.

Next