mnmx

CLI reference

mnmx reads goals and submits changes to a project engine. mnmx-harness builds from a goal bundle and runs the checks you supply.

mnmx

@mnmx/engine · Node 22.18+

The starter runs npm test in a clean checkout of HEAD. Commit the test script and any changes you want it to check.

mnmx init
mnmx read demo
mnmx check demo
Configuration and exit codes

The default config, ./mnmx.config.mjs, runs as JavaScript. Load only a config you trust.

Export an adapter with an engine, or a factory that takes the mnmx API and returns the adapter. The factory can be async. For check and submit, supply adapter.submission(goal) to build the request.

Results from read, check, and submit are JSON. Success exits 0. A usage, configuration, or execution error exits 2.

init

mnmx init [--config PATH]

Create a starter config in a Git project with a commit. Choose an unused config path. The starter keeps its signing keys and audit repository in the common Git directory.

read

mnmx read GOAL [--config PATH]

Show the goal, its holds, and its latest record without preparing a submission.

check

mnmx check GOAL [--config PATH]

Preview the decision without landing the change. A verdict of fail or unknown exits 1.

submit

mnmx submit GOAL [--config PATH]

Prepare fresh evidence and attempt to land the change, even if you already ran check. A rejection exits 1.

setup

mnmx setup [DIRECTORY] [--dry-run] [--model MODEL] [--codex PATH]

Create or update AGENTS.md using your authenticated Codex CLI. DIRECTORY defaults to the current directory. --dry-run still calls the model and prints the proposed text. --model defaults to gpt-6.1-sol. --codex selects the executable.

pilot init

mnmx pilot init STATE

Create the CI recorder’s audit repository and keys in a new directory. Readers need the repository and trusted public.json. Keep private.json on the recorder.

pilot record

mnmx pilot record STATE LOCAL_REPO COMMIT RUN pass|fail|unknown

Record the supplied CI verdict for the full SHA-1 commit ID. Reuse RUN when retrying the same observation. The command exits 0 once it records the verdict, even when CI failed.

pilot replay

mnmx pilot replay AUDIT.git PUBLIC.json GOAL COMMIT RUN

Verify the saved evidence and reproduce the decision using public keys. GOAL is pilot.ci for CI receipts or demo for the starter. A verified rejection exits 0.

--help

mnmx --help

Also available as -h or by running mnmx without arguments.

--version

mnmx --version

Print the installed engine package version. The short form is -v.

mnmx-harness

@mnmx/harness · Node 22.18+

Set the goal bundle and checks in mnmx-harness.json. To continue a saved run, use resume with its output directory.

mnmx-harness run mnmx-harness.json --output runs/first
mnmx-harness status runs/first
mnmx-harness report runs/first
Agent sessions and exit codes

Codex, Pi, and Claude Code start fresh sessions. In a command adapter, {request} expands to the request file path.

For run, resume, and report, status pass exits 0 and evidence-incomplete exits 2. Other reported outcomes exit 1. Configuration and execution errors exit 2.

run

mnmx-harness run CONFIG.json --output RUN_DIRECTORY

Choose a new output directory for the frozen goals and checks. The harness saves each candidate there with its plan and review evidence.

resume

mnmx-harness resume RUN_DIRECTORY

Continue from the last completed stage using the original inputs. Logs from interrupted attempts stay in the run directory.

status

mnmx-harness status RUN_DIRECTORY

Show the run status and attached diagnostics. Reading a failed run’s status still exits 0.

report

mnmx-harness report RUN_DIRECTORY

Show each attempt’s verdict and which cases it fixed or broke compared with the previous attempt.

compare

mnmx-harness compare LEFT_RUN RIGHT_RUN --output NEW_DIRECTORY

Rerun reviewer probes on the original and both final candidates. Both runs must be finished (pass or exhausted) and pin identical originals, goal bundles, and checks. Use a new output directory outside the runs and their inputs.

attach-diagnostics

mnmx-harness attach-diagnostics RUN_DIRECTORY SUITE TARGET_SUMMARY.json

Attach new case results to the saved attempt whose number and file hashes match the summary. The original verdict stays on record.

scope-export

mnmx-harness scope-export RUN_DIRECTORY --output NEW_LEDGER.json

Export the expectations that count toward acceptance. The run must have scopeLedger enabled.

scope-revise

mnmx-harness scope-revise LEDGER.json GOALS_DIRECTORY REVISION.json --output NEW_LEDGER.json

Apply the reviewed changes to the ledger for this goal bundle. Use the output ledger in a new run.

--help

mnmx-harness --help

Also available as -h or by running mnmx-harness without arguments.