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.21.0. Try the guided rehearsal free, then check your project and make one small change. GitHub automation is optional.

Task T1 local objective SPEC SHA APPROVED $ harness implements $ uv run pytest tests passed REVIEWED Review report YOU review and integrate INPUTPLANGATE 1 MACHINE WORKADVISORY REVIEWHUMAN DECISION
Human actions use safety orangeMachine work uses blueprint blue
  1. 01Try it freeRead, inspect, and accept a sample
  2. 02Check readinessTest your committed baseline
  3. 03StartOne objective becomes T1
  4. 04Read the planSaved as an exact Spec commit
  5. 05ApproveAuthorize the exact Spec SHA
  6. 06ExecuteImplement and verify
  7. 07ReviewIndependent, advisory findings
  8. 08AcceptIntegrate the reviewed candidate

Try the workflow free

No coding-agent login needed

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.

terminal / free guided rehearsal
# 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.

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

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. It needs Python 3.12 or newer (tested on 3.12 to 3.14).

uv --version

A coding harness

Choose Claude Code, Codex, OpenCode, Pi, or Goose. Install and authenticate it before your first Task.

claude --version

First-run discovery never picks Goose. Choose it by name: --harness goose

Claude Code

Anthropic coding CLI

Log in:
claude auth login
Flag:
--harness claude-code

Codex

Coding CLI

Log in:
codex login
Flag:
--harness codex

OpenCode

Open-source agent

Log in:
opencode auth login
Flag:
--harness opencode

Pi

Lightweight agent. Set up a provider first.

Credential check:
pi auth check --model <model> --json --no-refresh
Flag:
--harness pi

Goose

Extensible open-source agent

Log in:
goose configure
Flag:
--harness goose

Local 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.

  1. Install the AgentMachinist package.
  2. Run the free guided rehearsal.
  3. 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.

terminal / install AgentMachinist
# 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. 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.

FOREGROUND ROUTE

Your checkout owns the whole Task

Task T1your objective machinist startyour checkout coding harnessspec + implement + review Candidateyou integrate No origin or forge required

Foreground local setup

  1. Run machinist start "Your bounded objective", supplying --test-cmd when needed.
  2. First start saves local settings and verifies the committed baseline before asking the Harness for a Spec.
  3. Read the saved Spec, then run the printed approve --task T1 --spec-sha command. Execute, verification, and independent Review follow.
  4. Inspect the report and candidate diff. integrate T1 and optional publish T1 --provider github|gitlab are separate decisions.

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.

terminal / start one Task
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.

LOCAL TASKgood first input
T1 Add CSV export for filtered rows Created in your checkout Acceptance criteria Exports only the currently filtered rowsPreserves visible column orderHas a focused automated test Task T1
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.

terminal / inspect saved Spec
machinist inspect T1
SAVED SPEC COMMITmachine wrote the plan
SPEC Spec: Add CSV export (T1) .machinist/specs/task-1-spec.md DOCUMENT MAP SummaryRequirementsApproachRisksTesting planOut of scope agent/task-1
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.

terminal / exact Spec Approval
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.

HUMAN GATEapproval names one commit
SAVED SPEC COMMIT a17c98d42e6f T1 · approved SHA SHA BOUND new Spec → fresh Approval
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>.

terminal / accept the local candidate
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.

REVIEW COMPLETEcontroller delivered; human decides
REVIEW COMPLETE Add CSV export (T1) QUALITY GATE uv run pytest tests passed YOUR FINAL GATE Review the diff • Does the code match the spec?• Do the tests prove the outcome?• Are deviations explained? INTEGRATE Only machinist integrate T1 updates the local base.

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.

terminal / optional issue import
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.

terminal / optional publication
# 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 spec

The Task exists and the next eligible machine work is Spec generation.

awaiting approval

Read the saved Spec and approve its exact full SHA.

approved

The exact Spec is authorized. Foreground continuation can Execute.

awaiting review

A verified candidate needs its independent Review at that exact SHA.

ready to integrate

Review is complete. Inspect its findings and the candidate diff before integrating.

integrated

The 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.
  • Reduced credentials limit what the agent can reach. Post-run Git checks catch violations. Neither is OS isolation against a hostile process running as your user.
  • AgentMachinist never merges automatically, and never merges a remote PR/MR. Explicit local integration is a clean, exact-base fast-forward.

Read the full trust model.

LOCAL USER BOUNDARY AgentMachinist controller Git · Approval · gates · Task Runs Harness reads / edits Workshop Optional forge GitHub / GitLab YOU approve + integrate

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 spec
The 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 T1
Execute 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 execute
machinist retry --task T1 --phase execute --fresh
Bounded 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 review
Local 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 T1
Publication 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 gitlab
A 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 --clear
Check 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.

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, see the legacy GitHub Actions setup.

CommandWhat 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 T1Advance 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 T1Explicitly fast-forward a clean expected local base to the exact reviewed candidate.
machinist publish T1 --provider github|gitlabOptionally publish that candidate using the origin-bound forge CLI. --host binds an explicit expected host.
machinist rehearse --guidedTry the real local path with a fake Harness, pausing at Approval and integration. Free; no model or API calls.
machinist doctor --local --fresh-workshopCheck readiness and explicitly run Gates in a disposable committed checkout before model work.
machinist config show --localRead the settings saved for local Tasks.
machinist config set tests.command "uv run pytest" --localUpdate 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.