AgentMachinist documentation
Start with a bounded objective. Approve its exact Spec, then let the controller coordinate implementation, verification, and independent Review. Inspect the result and integrate it locally. Publish a GitHub PR or GitLab MR whenever sharing helps.
AgentMachinist 0.19.0 adds a built-in Goose Harness and clearer first-run guidance, including a repository-local Git author and free checks before your first paid run. Install 0.19.0 from PyPI. Exact Spec Approval, verification, independent Review, and optional GitHub or GitLab publication remain part of the workflow. The existing GitHub workflow remains supported.
Start with the workflow explainer, then complete your first Task. Use the references below when you need more detail. The same directory is available in the repository documentation index.
These records explain earlier decisions. Follow the operating references above for current commands and behavior.
Previous onboarding URL redirects to the visual first-run guide.
The retired job card and animated explainer URLs redirect to the first-run guide and the workflow explainer.
The local loop
The foreground command shows progress and a next action. Your original branch stays unchanged until you explicitly integrate the reviewed candidate.
Available since 0.16.0: completion prompts suggest the next activity and a sample command after issue creation, Spec generation, Approval requests, and Review. They guide GitHub workflow waits, human review, and optional publication after local integration.
See the full loop in one diagram, including who owns each step.
Start from a clean committed Git checkout with an installed Harness and a verification command. Add detail from a file outside the checkout with --body-file ../task.md, or import a GitHub or GitLab issue with --from-issue. The controller gives the Task a local ID such as T1.
The controller discovers local settings and verifies the committed baseline in an isolated Workshop. A read-only Harness returns a Spec; the controller writes and commits it and retains its exact SHA. The command prints the Spec and stops for you.
machinist status T1Read the Spec and copy the full Approval command printed by the CLI. Approval records this repository, Task, Spec SHA, actor, and time. A mismatched Spec or moved candidate branch refuses execution. Approval also starts the remaining machine Phases in the foreground.
machinist approve --task T1 --spec-sha <full-spec-commit-sha>The Harness edits in an isolated Workshop from the approved Spec. The controller owns commits and Task records, checks Git custody, and runs the configured Verification Gates. A failed Execute retains Evidence and requires explicit retry.
machinist status T1 --watchA separate read-only Harness compares the approved Spec, candidate diff, and verification Evidence. Local Review always runs. Findings are advisory: a completed report means the candidate was reviewed, not that every finding is resolved.
machinist status T1 --jsonKeep the candidate local, or explicitly fast-forward the clean expected base with integrate. To share it, choose publish T1 --provider github or gitlab. Publication needs a matching origin and authenticated forge CLI; it never reruns successful local Phases or merges a remote change.
Watch it run
Step through local Task T1: terminal on the left, saved Task Evidence on the right. Output and SHAs are illustrative; this page does not run a Harness or publish anything. Optional publication appears last.
$ machinist start "Add CSV export for the currently filtered rows" --test-cmd "uv run pytest"
Created T1. Recover with machinist status T1.
Baseline verification completed in the Workshop.
Spec retained: .machinist/specs/task-1-spec.md
State: awaiting approval
# Read the printed Spec; copy its full Approval command.
$ machinist approve --task T1 --spec-sha a17c98d42e6f0123456789abcdef0123456789ab
Execute: Harness implementing in an isolated Workshop…
Verification: uv run pytest
Required verification completed; candidate retained locally.
Independent Review completed; findings are advisory.
State: ready to integrate
# Inspect the report and candidate diff before accepting.
$ machinist integrate T1
State: integrated
# Optional: origin + authenticated glab required.
$ machinist publish T1 --provider gitlab
Published T1: <verified merge-request URL>
Objective and optional body · saved in this checkout
↳ Spec commit retained on the Task branch
.machinist/specs/task-1-spec.md
Read the plan before authorizing implementation.
✓ required Verification Gates completed
Independent Review report names this exact candidate SHA. Inspect its advisory findings and the diff.
Optional publication checks origin, leases the push, and verifies the exact PR/MR head. Remote merge remains a separate human action.
When something changes
Before integration begins, amend a completed candidate with feedback. A new Spec needs fresh Approval, verification, and Review. Once integration starts, create a new Task from the current base.
machinist amend --task T1 --feedback "Also escape quoted values in the export."
Inspect status, then retry the failed Phase explicitly. Execute resumes retained edits by default; --fresh starts a new Workshop. Recovery after the implementation commit uses saved Evidence.
machinist retry --task T1 --phase execute
Cancel cooperatively while preserving Evidence. If publication fails, repeat the same publish command; successful implementation and verification are not repeated.
machinist cancel --task T1 --reason "Requirements changed"
Integration refuses dirty checkouts, a moved base, or a changed candidate. See the local workflow, field guide, and operator runbook for recovery actions.
Added in 0.18.0: optional bounded repair can make one additional Harness call for an eligible required Gate failure inside active Execute, then rerun all Gates. It defaults off; failed or interrupted repair needs explicit retry --fresh. Aggregate report --source all also includes local Task history.
Get started for real
Install AgentMachinist from PyPI, then change into your project. First start saves local settings without overwriting your existing configuration.
git status --shortuv --versionClaude Code · OpenCode · Pi · Codex · Gooseuv run pytestFirst-run discovery never picks Goose, so choose it with machinist start --harness goose.
Dependencies in your original .venv/ or node_modules/ are not copied. Include dependency setup in the Gate when needed, such as npm ci && npm test.
Solo developers can keep the whole Task local. Small teams can use one persistent runner checkout and publish reviewable changes to their forge. Local Claims do not coordinate separate laptops. Watcher budgets do not constrain foreground local Tasks.
# install the released controller
$ uv tool install agentmachinist
# then change into your own committed project
$ machinist start "Add CSV export for the currently filtered rows" --test-cmd "uv run pytest"
# inspect the Spec; use the full SHA printed by start
$ machinist approve --task T1 --spec-sha <full-spec-commit-sha>
# inspect the report and diff before integration
$ machinist status T1
$ machinist integrate T1
# optional: choose one forge; matching origin/auth required
$ machinist publish T1 --provider github
# or: machinist publish T1 --provider gitlab
# deterministic rehearsal: temporary Git repo, fake Harness
$ machinist rehearse
Local orchestration does not guarantee offline inference. Your Harness may use a cloud model. Offline operation requires a local provider, downloaded models, prepared dependencies, and separate network-denied validation. Custody checks reduce credentials and detect violations; they are not an OS sandbox.
GitLab supports issue import, nested projects, explicit self-managed hosts, and MR publication through glab. Hosted GitLab Spec CI and remote GitLab Approval are outside this workflow. Existing GitHub Actions setup and watcher commands remain supported.