Git
Needs an initial commit and an author set inside the repository, since the controller ignores your global Git identity. The controller creates isolated Workshops and retains local candidate commits.
git --version
AgentMachinist helps your coding agent make a change you can check before accepting it. Read its plan, approve the work, then inspect the changes, checks, and a separate review.
Begin with the free guided rehearsal, then check your project and make one small real change. Prefer text? Use the short guide (Markdown).
This guide covers AgentMachinist 0.21.0. Try the guided rehearsal free, then check your project and make one small change. GitHub automation is optional.
Use a disposable sample project before your own code. The guided rehearsal uses a fake Harness with the real controller machinery. It makes no model or API calls.
# Install AgentMachinist: uv tool install agentmachinist machinist rehearse --guided
Read the sample plan (Spec) at the first pause. Approve it when satisfied. At the second pause, inspect the candidate diff, checks, and independent Review before accepting the change. You can decline either decision; the printed project path is retained for inspection.
While paused, open the saved plan at the path printed in your terminal. The second pause also prints paths for the candidate diff and Review report. Then check your own project before a real Task. Explicit --harness uses your configured coding agent and may consume provider quota.
For a real Task, install and authenticate your coding agent. Start on a clean named Git branch with an initial commit and repository-local author.
Run machinist doctor --local for readiness, then machinist doctor --local --fresh-workshop to explicitly test a disposable checkout of committed files. It makes no model call or Task; checks may download dependencies.
Needs an initial commit and an author set inside the repository, since the controller ignores your global Git identity. The controller creates isolated Workshops and retains local candidate commits.
git --version
Use a real test command that works from committed files in an isolated Workshop. Baseline verification runs before model work.
uv run pytest
Installs the released controller from PyPI. It needs Python 3.12 or newer (tested on 3.12 to 3.14).
uv --version
Choose Claude Code, Codex, OpenCode, Pi, or Goose. Install and authenticate it before your first Task.
claude --versionFirst-run discovery never picks Goose. Choose it by name: --harness goose
Anthropic coding CLI
claude auth login--harness claude-codeCoding CLI
codex login--harness codexOpen-source agent
opencode auth login--harness opencodeLightweight agent. Set up a provider first.
pi auth check --model <model> --json --no-refresh--harness piExtensible open-source agent
goose configure--harness gooseLocal setup reuses configured Harness profiles or discovers an installed Harness supporting Spec, Execute, and Review. A configured model is optional. Built-in adapters reserve their sandbox and permission flags against extra_args overrides; plugins must enforce their own controls, and provider access is separate from executable discovery.
Already installed with uv? Run uv tool upgrade agentmachinist, then check that machinist --version reports 0.20.0 or newer.
machinist rehearse --guided uses the production local journey with a fake Harness. It pauses for Approval and integration, makes no model or API calls, and retains the printed project path if you decline. --harness explicitly uses configured Harnesses and may consume provider usage.
# Install AgentMachinist: uv tool install agentmachinist machinist rehearse --guided # Then change to the project you want to change: cd ~/code/your-project
The foreground route completes a Task without a forge. You can still import an issue or publish the result when you want to share it.
Already run GitHub issue automation? The legacy GitHub Actions setup has its own page.
machinist start "Your bounded objective", supplying --test-cmd when needed.approve --task T1 --spec-sha command. Execute, verification, and independent Review follow.integrate T1 and optional publish T1 --provider github|gitlab are separate decisions.No separate onboarding wizard is required for local Tasks. Existing repository settings are preserved; local overrides live in .machinist/runs/local/config.yaml. Runtime files are excluded through Git’s local exclude file.
# Illustrative local settings; start resolves Workshop paths. version: 1 harness: name: codex tests: command: "uv run pytest" github: spec_source: local manage_workflows: false review: enabled: true telemetry: otlp_endpoint: null
Select --harness on first start, or let setup find an installed full-pipeline adapter. Conflicting later flags ask you to edit the saved local configuration.
At least one required Verification Gate must exist. When no named verification.gates exist, tests.command supplies that Gate. Local setup refuses a null-only gate configuration.
The local workflow enables and requires independent Review even when an existing GitHub configuration disabled it. Findings are advisory; a completed report is not a guarantee of correctness.
This is an abridged first-run configuration, not a replacement for the file generated by start. Do not commit local runtime records. First local setup does not generate GitHub workflows, labels, or issue forms.
Ignored node_modules/ and .venv/ directories are not copied from your checkout. Use a Gate that prepares dependencies, such as npm ci && npm test with a committed lockfile or uv run pytest with a committed uv.lock. A Gate that leaves new files in the Workshop stops the Spec Phase and names them. A failing baseline stops before model work, and machinist status T1 shows the Gate's error and log directory. Correct the saved Gate or external environment and explicitly retry the Spec; if committed baseline files must change, commit them and start a new Task.
From here, start, revise, and approve call your Harness model and use provider quota. Choose an observable result with a focused acceptance test. The examples below use Task T1; follow the ID and exact SHA printed by your own run.
An objective is enough to begin. Use --body-file ../task.md for acceptance criteria and constraints, or --body-file - to read stdin. Save the body outside the checkout or commit it first, so the repository stays clean. To create a Task from an external issue, use start --from-issue; the new Task receives its own local ID.
machinist start "Add CSV export for filtered transaction rows" --body-file ../task.md --test-cmd "uv run pytest"
Save this as ../task.md before running the command above.
## Objective Add CSV export for currently filtered transaction rows. ## Acceptance criteria - [ ] Export only the currently filtered rows. - [ ] Preserve the visible column order. ## Constraints Keep the current table UI and exclude email delivery. ## Verification Run the focused export test and the existing suite.
The optional GitHub issue-form path accepts both ## and ### field headings. Its Objective lint requires at least six words and meaningful acceptance checkboxes.
The controller creates the local Task, verifies the baseline, invokes the read-only Spec Harness, and commits the resulting Spec on a retained local branch. Your base branch stays unchanged.
Read the plan (Spec) in command output or use machinist inspect T1 to see it again. Check requirements, scope, risks, and the testing plan before authorizing implementation.
machinist inspect T1
Copy the complete command printed by start, revise, or inspect. Approval binds your repository, Task, actor, time, and the full 40-character Spec SHA. A stale or mismatched SHA is rejected.
machinist approve --task T1 --spec-sha <full-spec-commit-sha>
This command continues Execute, required verification, and independent Review in the foreground. It does not integrate or publish the candidate.
Keep the same Task and use machinist revise T1 --feedback "Keep the public API unchanged." before implementation. Read the new Spec and approve its new exact SHA. Use amendment for feedback on a completed candidate.
After implementation, the controller runs the authoritative Verification Gates and retains the candidate before Workshop cleanup. A separate read-only Review checks that exact candidate against the approved Spec and Evidence. Findings remain advisory.
machinist inspect T1 brings the plan, candidate diff, checks, and Review together. Read them, then accept the candidate with integrate. Direct comparison remains available with git diff <spec-sha> <candidate-sha>.
machinist inspect T1 machinist integrate T1
A dirty checkout, switched or changed base, changed candidate, or non-fast-forward result stops integration. No remote is needed and nothing is pushed.
GitHub and GitLab are optional inputs and outputs. Authenticating a forge CLI is only needed when you choose issue intake or publication.
machinist start --from-issue https://github.com/team/project/issues/42 # machinist start --from-issue https://gitlab.com/team/subgroup/project/-/issues/42 # Self-managed GitLab: bind the expected host explicitly. # machinist start --from-issue https://gitlab.example.com/team/project/-/issues/42 --provider gitlab --host gitlab.example.com
Importing issue 42 can create T1. GitHub uses gh; GitLab uses glab, authenticated for the selected host. Remote labels, reviews, and CI do not become local Approval.
Use shared issues and PRs/MRs for discussion. One operator’s checkout owns local Task records and Claims. Multiple laptops are not coordinated workers. Watcher Task Run budgets apply to legacy issue dispatch; they do not limit foreground local Tasks.
A single origin must match the selected forge and repository. Publication checks exact Approval, successful Execute and Review Evidence, candidate identity, and a recorded remote lease before updating a PR/MR.
Publishing can happen before or after local integration. If it fails, rerun the same publish command: recovery reconciles the push and PR/MR without repeating successful Harness work or gates. Native GitLab CI Spec dispatch and remote GitLab Approval are not included.
# Choose one provider matching this repository's origin: machinist publish T1 --provider github # Or: # machinist publish T1 --provider gitlab # Explicit self-managed host: # machinist publish T1 --provider gitlab --host gitlab.example.com
machinist status T1 shows the saved Spec, candidate SHA, Review report path, and one next action. machinist continue T1 advances eligible work; it never grants Approval or replaces explicit retry.
awaiting specThe Task exists and the next eligible machine work is Spec generation.
awaiting approvalRead the saved Spec and approve its exact full SHA.
approvedThe exact Spec is authorized. Foreground continuation can Execute.
awaiting reviewA verified candidate needs its independent Review at that exact SHA.
ready to integrateReview is complete. Inspect its findings and the candidate diff before integrating.
integratedThe local base contains the exact candidate. Publication remains optional.
No forge or server is required for a local Task. Your Harness may still send code to a cloud model. Offline inference needs a local provider, downloaded models, cached dependencies, and separate network-denied validation.
Failed Task Runs retain Evidence and require explicit retry. Inspect the error, report, and retained Workshop before choosing recovery.
The Spec Harness has not run. machinist status T1 shows baseline failed with the Gate's error and log directory. Use machinist config show --local to inspect saved settings. Fix the Gate with machinist config set tests.command "uv run pytest" --local for the single-Gate form, or its external dependency setup, then retry. Changing committed baseline files, including a missing lockfile, requires a new Task; a retry reuses the original base commit.
machinist retry --task T1 --phase specRead the current saved Spec and copy its complete Approval command. Revision and amendment both require fresh Approval of the new Spec.
machinist status T1Local retry defaults to resuming validated retained edits. Use --fresh to start a new Workshop. Saved implementation-commit Evidence avoids repeating completed implementation and verification.
machinist retry --task T1 --phase executemachinist retry --task T1 --phase execute --freshRepair, added in 0.18.0, defaults off. Setting verification.repair.max_attempts: 1 in the saved local configuration permits one additional Harness call for an eligible required Gate failure inside active Execute, followed by all Gates again. A failed or interrupted repair requires machinist retry --task T1 --phase execute --fresh. Resume cannot replay paid repair or reset its deadline. See bounded repair recovery for eligibility, timing, and retained Evidence.
Retry Review at the retained candidate. A completed Review with findings is advisory, not a failed gate. An amendment creates a fresh Spec and later a new Review for its changed candidate.
machinist retry --task T1 --phase reviewCheck that the checkout is clean and on the expected base branch. Do not reset away edits to satisfy the guard. A changed base or candidate needs deliberate reconciliation; status retains the exact expected identities.
machinist status T1Resolve authentication, connectivity, or the reported remote conflict, then repeat the same provider and host selection. The controller reconciles recorded publication intent without rerunning successful local Phases.
machinist publish T1 --provider gitlabRequest cooperative cancellation, inspect the preserved Evidence, and resolve the reason before clearing it. Use the recovery action shown by status.
machinist cancel --task T1 --reason "Requirements changed"machinist cancel --task T1 --clearRun machinist doctor --local to check local Git, Harness probes, and verification command availability using the same settings as start. It creates no Task or runtime configuration and requires no forge. Add --json for structured diagnostics.
machinist doctor --local --fresh-workshop explicitly runs project checks in a disposable clone of committed HEAD, with no Task or model call. It leaves controller Git metadata unchanged; checks can download dependencies. --run-gates instead runs in your current checkout. Plain doctor keeps the GitHub setup checks when root configuration exists.
The guide remembers these checks in this browser.
Use the Task ID shown by your run. For legacy numeric issue commands and watcher operations, see the legacy GitHub Actions setup.
| Command | What it does |
|---|---|
machinist start "Objective" | Create a local Task, verify its baseline, save a Spec, and stop for Approval. |
machinist revise T1 --feedback "text" | Correct an initial saved Spec before a candidate exists; read and approve its new exact SHA. |
machinist approve --task T1 --spec-sha <sha> | Approve one exact Spec and continue Execute, verification, and independent Review. |
machinist inspect T1 [--json] | Read the plan, candidate diff, Verification, Review, and next action together. Use machinist status to list local Tasks; numeric machinist inspect 42 reads legacy issue Evidence. |
machinist continue T1 | Advance eligible local work without bypassing Approval or explicit retry. |
machinist amend --task T1 --feedback "text" | From a verified candidate with completed Review, create a new Spec and require fresh Approval; unavailable after integration begins. |
machinist retry --task T1 --phase execute [--fresh] | Retry explicitly, resuming validated retained edits by default. Select spec or review for those failed Phases. |
machinist cancel --task T1 [--reason "text"|--clear] | Request cooperative cancellation or clear its durable marker. |
machinist integrate T1 | Explicitly fast-forward a clean expected local base to the exact reviewed candidate. |
machinist publish T1 --provider github|gitlab | Optionally publish that candidate using the origin-bound forge CLI. --host binds an explicit expected host. |
machinist rehearse --guided | Try the real local path with a fake Harness, pausing at Approval and integration. Free; no model or API calls. |
machinist doctor --local --fresh-workshop | Check readiness and explicitly run Gates in a disposable committed checkout before model work. |
machinist config show --local | Read the settings saved for local Tasks. |
machinist config set tests.command "uv run pytest" --local | Update the saved single-Gate test command; use your project’s verification command. |
Added in 0.18.0: machinist report --since 30d --source all --json combines local and legacy Task Run history without forge setup or local adoption. Select --source local for local Tasks only. This is aggregate Evidence, not the independent Review report or proof of human acceptance.