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
Make a change you can check.
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.20.0. Try the guided rehearsal free, then check your project and make one small change. GitHub automation is optional.
- 01Try it freeRead, inspect, and accept a sample
- 02Check readinessTest your committed baseline
- 03StartOne objective becomes T1
- 04Read the planSaved as an exact Spec commit
- 05ApproveAuthorize the exact Spec SHA
- 06ExecuteImplement and verify
- 07ReviewIndependent, advisory findings
- 08AcceptIntegrate the reviewed candidate
Try the workflow free
No coding-agent login neededUse 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.
Check your project before model work.
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.
Verification
Use a real test command that works from committed files in an isolated Workshop. Baseline verification runs before model work.
uv run pytest
uv
Installs the released controller from PyPI. Python 3.12 or newer is required.
uv --version
A coding harness
Choose Claude Code, OpenCode, Pi, Codex, or Goose. Install and authenticate it before your first Task.
claude --versionFirst-run discovery never picks Goose. Choose it by name: --harness goose
Claude Code
Anthropic coding CLI
claude auth login--harness claude-codeOpenCode
Open-source agent
opencode auth login--harness opencodeCodex
Coding CLI
codex login--harness codexPi
Lightweight agent
pi auth check --model <model> --json --no-refresh--harness piLocal 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.
Install once. Learn the decisions first.
- Install the AgentMachinist package.
- Run the free guided rehearsal.
- Then change into the project where you want to work.
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
Begin locally. Add collaboration when useful.
The foreground route completes a Task without a forge. Existing GitHub issue automation remains available separately; github.spec_source: local in that legacy route still means GitHub-backed work.
FOREGROUND ROUTE
Your checkout owns the whole Task
LEGACY GITHUB
Actions writes the Spec; your runner executes
Foreground local setup
- Run
machinist start "Your bounded objective", supplying--test-cmdwhen needed. - First start saves local settings and verifies the committed baseline before asking the Harness for a Spec.
- Read the saved Spec, then run the printed
approve --task T1 --spec-shacommand. Execute, verification, and independent Review follow. - Inspect the report and candidate diff.
integrate T1and optionalpublish T1 --provider github|gitlabare separate decisions.
Existing GitHub Actions setup
- Use
machinist onboard --setup-pr --spec-source github-actionsto commit and push managed setup changes and open a draft setup PR. - Managed workflows install the selected Spec adapter and use its declared repository secret.
github.spec_install: pypipins the published controller version;checkoutis for its own development repository. - Review and merge setup first. Then run
machinist doctor --run-gatesto verify default-branch deployment. - Actions generates Specs and records trusted Approval. A local runner or watcher owns Execute and optional legacy Review. You merge the resulting PR yourself.
Start writes the settings it needs.
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
Reuse the Harness you know
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.
Require executable verification
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.
Always complete local Review
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.
Dependencies must work inside the Workshop
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.
Make one small real change.
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.
01 / GIVE THE TASK CONTEXT
Describe one outcome.
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"
A useful Task body
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.
02 / READ THE SAVED SPEC
Start stops at the decision.
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
03 / AUTHORIZE ONE EXACT COMMIT
Approve the Spec you actually read.
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.
The initial plan needs a correction?
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.
04 / INSPECT AND INTEGRATE
Keep the final decision explicit.
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.
Import an issue. Publish the result when ready.
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
Issue numbers are provenance
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.
One persistent runner for a small team
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.
Publish the reviewed candidate
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
Status tells you who moves next.
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.
Local orchestration is not offline inference.
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.
- The controller owns Git changes, Task records, and optional publication.
- Spec and Review are read-only; Execute checks for Harness commits, protected metadata edits, and other custody violations.
- Credential reduction and postconditions detect violations; they are not OS isolation against a hostile process running as your user.
- AgentMachinist never automatically merges or merges a remote PR/MR. Explicit local integration is a clean, exact-base fast-forward.
Resolve the cause, then retry explicitly.
Failed Task Runs retain Evidence and require explicit retry. Inspect the error, report, and retained Workshop before choosing recovery.
Baseline verification failed
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 specThe approval SHA does not match
Read the current saved Spec and copy its complete Approval command. Revision and amendment both require fresh Approval of the new Spec.
machinist status T1Execute failed or was interrupted
Local 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 --freshBounded repair stopped
Repair, 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.
Independent Review failed
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 reviewLocal integration stopped
Check 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 T1Publication stopped after a push
Resolve 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 gitlabA Task must stop
Request 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 --clearCheck your project in a fresh Workshop
Run 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.
Existing GitHub adoption stopped
Rerun machinist onboard --setup-pr to resume managed setup work and reuse its draft PR. Existing valid settings are preserved; change them with machinist config set. Merge setup before checking deployed default-branch workflows.
machinist doctor --run-gatesKeep issue automation when you need it.
The supported GitHub workflow uses issues, draft PR Specs, workflow-authored Approval, and a local Execute runner. Numeric issue IDs and local T1 IDs are separate.
GitHub Actions adoption and daily commands
onboard --setup-pr performs setup preflight, commits and pushes managed changes, and opens or reuses a draft setup PR. A retry preserves valid settings and resumes managed-only setup work; unrelated branch history is rejected.
machinist onboard --setup-pr --spec-source github-actions
Add the repository secret declared by your selected Spec adapter. Review and merge the setup PR before checking the deployed default-branch workflows:
machinist doctor --run-gates
Create a GitHub Task by answering five terminal prompts: Objective, Acceptance criteria, Constraints, Verification, and optional Context. To supply an existing Markdown body instead, add --body-file ../task.md.
machinist task new --title "Add CSV export for filtered transaction rows" --dispatch
Available since 0.16.0: issue creation prints the next activity and a sample command for the configured Spec source. In GitHub Actions mode, follow machinist explain 42 while the Spec is generated. In legacy local Spec mode, an undispatched issue suggests machinist spec 42; a dispatched issue suggests machinist watch --once -v, which can process other eligible queued Tasks too.
Wait for Actions to create its Spec PR, then read the Spec. Issue 42 and PR 18 below are illustrative; use the numbers returned for your Task.
machinist approve --issue 42 # Or target its PR explicitly: machinist approve --pr 18
Stop here and wait for the approval workflow to complete successfully. The CLI requests Approval asynchronously; it does not mint trusted Evidence. Confirm the configured approval label is on the draft PR, then inspect the full commit identities:
machinist inspect 42 --json
In the github_pr source, approval_sha must equal head_sha. If Approval is missing, stale, or the workflow failed, resolve that before executing. An early run can create a failed Execute attempt that requires explicit retry. Once the current Spec has trusted Approval, run:
machinist run 42
Only if legacy review.enabled: true is configured, run independent Review after Execute succeeds:
machinist review 42
The managed workflow checks write or admin access and the current head before recording its trusted SHA marker. To request Approval from GitHub instead of the CLI, post the PR-body command /machinist-execute <full-spec-commit-sha> as a PR comment. GitHub’s review Approve button is not this Gate.
A label without trusted Evidence is approval pending; a changed head is approval stale. With legacy Review enabled, Execute leaves the PR draft until independent Review completes. Findings remain advisory. With Review disabled, Execute can mark it ready after verification. You perform the remote merge.
If you used init or onboard without --setup-pr, commit setup manually: inspect the generated file list and stage selected files. Stage the Approval workflow with git add -- .github/workflows/machinist-approve.yml. With github.spec_source: github-actions, also run git add -- .github/workflows/machinist-spec.yml. When switching Spec modes or disabling workflow management, stage any removed managed workflow path shown by git status --short with git add -- <path>. Omit the workflow commands when no managed workflow files were generated or removed. Review the full staged diff with git diff --cached, then git commit and git push before the full doctor check.
Choose the recovery action matching the Task’s state; these are alternatives:
- Revise a draft Spec:
machinist spec 42 --revise. - Abandon the Task and close its Spec PR:
machinist spec 42 --abandon --reason "requirements changed". - Retry failed Execute with retained edits:
machinist retry 42 --phase execute --run --resume. - Retry failed Execute from a fresh Workshop:
machinist retry 42 --phase execute --run --fresh.
Legacy Execute recovery defaults to fresh; local retry --task T1 defaults to resume. In legacy github.spec_source: local mode, use machinist spec 42 or watch for Spec generation. It still requires GitHub Approval workflows. See the GitHub setup reference and operator runbook for watcher services, labels, and recovery.
Ready for the first Task?
The guide remembers these checks in this browser.
The daily local commands.
Use the Task ID shown by your run. For legacy numeric issue commands and watcher operations, use the GitHub reference above.
| 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.
GitHub-specific diagnostics remain available: machinist doctor --run-gates, machinist sync-labels [--check|--apply], and machinist sync-workflows --check. These are not prerequisites for a local-only Task.