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
A field guide to AgentMachinist 0.19.0
Your first Task, reviewed and ready locally.
Start with an objective. Approve its exact Spec, follow implementation and verification in your terminal, then inspect the independent Review before integrating the change.
Prefer a concise command walkthrough? Use the short text guide (Markdown).
AgentMachinist 0.19.0 adds a built-in Goose Harness and clearer first-run guidance. Install 0.19.0 from PyPI. The GitHub issue workflow remains supported.
- 01PrepareCommitted repo, Harness, gates
- 02InstallInstall released controller
- 03StartOne objective becomes T1
- 04SpecCheck baseline; save the plan
- 05ApproveAuthorize the exact Spec SHA
- 06ExecuteImplement and verify
- 07ReviewIndependent, advisory findings
- 08IntegrateYou accept the local candidate
The foreground journey
No forge account requiredUse a small change with a meaningful test. The Spec and final diff are human decision points; the machine Phases continue in the foreground after Approval.
# Install the released controller: uv tool install agentmachinist # Then change to your project, with a clean committed baseline: cd ~/code/your-project machinist start "Add CSV export for filtered transaction rows" --test-cmd "uv run pytest"
Read the saved Spec before using its printed Approval command. After the machine Phases finish, use machinist status T1 to find the candidate SHA and Review report path. Open the report and inspect the candidate diff before choosing machinist integrate T1. Follow the separate commands in the walkthrough below.
Prepare the repository
One clean baseline. One working Harness.
Start in a Git repository with an initial commit, configured author, and no uncommitted changes. You do not need an origin, issue tracker, watcher, or server.
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 the controller
Install once. Start in your own project.
- Install the published AgentMachinist 0.19.0 from PyPI.
- Check that
machinist start --helpis available. - Change into the project where you want to work.
Already installed with uv? Run uv tool upgrade agentmachinist, then check machinist --version. Optional local readiness has been available since 0.15.0.
machinist rehearse exercises the production local journey in a disposable real Git repository with a deterministic fake Harness. It makes no model or API calls. --harness explicitly uses configured Harnesses and may consume provider usage.
# Install the released controller: uv tool install agentmachinist machinist start --help # Run the remaining commands in the project you want to change: cd ~/code/your-project
Choose the workflow
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.
Keep setup small
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.
Complete one Task
From objective to an inspected local candidate.
Use 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 Spec in command output or use status to see it again. Check requirements, scope, risks, and the testing plan before authorizing implementation.
machinist status T1
03 / AUTHORIZE ONE EXACT COMMIT
Approve the Spec you actually read.
Copy the complete command printed by start or status. 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 Spec is not right?
Do not approve it. Cancel the Task with machinist cancel --task T1 --reason "Spec needs different scope" and start a new Task with clearer context. Local amendment is available after a verified candidate and completed Review, before integration begins.
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.
Status prints the candidate SHA and Review report path. Open the report and inspect git diff <spec-sha> <candidate-sha> using the exact SHAs from status. When satisfied, integrate the exact reviewed candidate into the original local base:
machinist status 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.
Collaborate when it helps
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
Read the next action
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.
Know the boundary
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.
When the machine stops
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. Fix the required Gate in .machinist/runs/local/config.yaml 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. An amendment requires 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 --clearOptional local readiness (new in 0.15.0)
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 --run-gates explicitly runs project commands in your controller checkout; commands can write files or fetch dependencies. This does not prove a fresh Workshop has its dependencies. Plain doctor keeps the GitHub setup checks.
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-gatesExisting GitHub workflow
Keep 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.
Pocket checklist
Ready for the first Task?
The guide remembers these checks in this browser.
Quick reference
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 approve --task T1 --spec-sha <sha> | Approve one exact Spec and continue Execute, verification, and independent Review. |
machinist status T1 [--json] | Show the saved Spec, candidate SHA, Review report path, and next action. Default status lists local Tasks after local adoption. Use machinist inspect 42 for legacy issue Evidence in a mixed checkout. |
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 | Exercise the local path in a disposable repository with a fake Harness and real Git and gates. |
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.