AgentMachinist

AgentMachinist helps your coding agent make a change you can check before accepting it. You read its plan, authorize the work, then inspect the changes, test results, and a separate review before adding them to your project.

It works with Claude Code, OpenCode, Pi, Codex, or Goose. GitHub and GitLab are optional inputs and places to share the result.

New here? Follow Start here: try the workflow free, check your project, then make one small real change.

Task → Spec commit → human Approval → implementation → verification → Review
                                                                    │
                                  human review → local integration ◄─┘
                                  optional GitHub PR / GitLab MR

The controller owns commits, Task records, and optional publication. Local integration is an explicit fast-forward operation into your clean base checkout. AgentMachinist never merges remotely or automatically.

This guide covers AgentMachinist 0.20.0. Package reference: AgentMachinist 0.20.0 on PyPI.

Install

Install the controller, then enter the repository you want to work on:

uv tool install agentmachinist
machinist --version

Use AgentMachinist 0.20.0 or newer for the onboarding commands below.

You also need git and one supported Harness executable (claude, opencode, pi, codex, or goose). GitHub operations require authenticated gh; GitLab operations require authenticated glab. The core CLI is tested on macOS and Linux with Python 3.12 to 3.14. Managed background service commands are macOS-only; on Linux, schedule machinist watch --once with your existing service manager.

Start

Try the workflow free

After installation, learn the decisions with a disposable sample project:

machinist rehearse --guided

The rehearsal uses a fake coding agent and a disposable project. It makes no model or API calls. Read the sample plan (Spec), approve it when prompted, then inspect the change, checks, and independent Review before accepting it. You can decline at either decision; the printed project path lets you return to inspect it. No coding-agent login or GitHub setup is needed for this trial.

Make a small real change

Start on a clean named branch with an initial commit and an installed, authenticated Harness. Set your author inside the repository with git config user.name and git config user.email, because the controller ignores your global Git identity. Replace the example's Python test command with verification appropriate to your project.

cd your-repository
machinist doctor --local --fresh-workshop
machinist start "Reject unknown timezone names in parse_timezone with a ValueError" --test-cmd "uv run pytest"

Read the saved plan (Spec). If it needs a correction, keep the same Task and ask for a new plan before approving:

machinist revise T1 --feedback "Keep the public API unchanged."

Each revision needs fresh Approval. When satisfied, copy the exact Approval command printed by start or revise:

machinist approve --task T1 --spec-sha <full-spec-commit-sha>

Approval continues implementation, verification, and independent Review. Use inspect to read the plan, change, checks, and Review together. Then accept the reviewed change with integrate:

machinist inspect T1
# After reading the change, checks, and Review:
machinist integrate T1

Completion output explains the next activity and includes a command using your Task or issue ID. Local integration reports completion; publication is an optional follow-up with an explicit forge selection.

First start reuses applicable root settings, discovering an installed Harness and verification command when those settings are absent. Its local settings and Task records live under .machinist/runs/local/, excluded through Git's local exclude file. It does not require an origin, labels, a daemon, forge authentication, or hosted workflows. Existing machinist.yaml settings remain available. Local orchestration can still use a cloud model; offline inference requires a separately configured local provider.

Verification runs in an isolated committed checkout; dependency folders from your working repository are not copied. Use a self-preparing command such as npm ci && npm test or uv run pytest, with its lockfile committed. A failing baseline stops before the Spec Harness, and machinist status T1 shows the Gate's error and log directory. Correct the Gate in .machinist/runs/local/config.yaml or its dependency setup, then run machinist retry --task T1 --phase spec. If the committed baseline itself needs a fix, commit it and start a new Task. To try the loop on something disposable first, copy examples/first-task.

start, revise, and approve use your Harness's model and provider quota. The guided rehearsal remains free. doctor --local --fresh-workshop explicitly runs your project checks in a disposable checkout of committed files; commands may download dependencies. It makes no model call and creates no Task.

machinist doctor --local is an optional readiness check using the same configuration resolution as first start or your saved local settings. It checks Git, Harness probes, and verification command availability without creating a Task or requiring a forge. Add --json for structured output. Add --run-gates to execute project commands in your current checkout; this does not prove dependencies are ready in a fresh Workshop. Plain machinist doctor runs these local checks when no machinist.yaml exists and its GitHub setup checks otherwise.

You can publish the same reviewed candidate when collaboration is useful:

machinist publish T1 --provider gitlab
# Or: machinist publish T1 --provider github

Publication requires an origin that matches the selected forge and authenticated CLI. It preserves local work on failure and retries the same branch and change request without repeating Harness work or verification. GitLab support includes nested projects and explicitly bound self-managed hosts; it covers issue intake and merge-request publication, not GitLab-hosted Spec automation.

See the local workflow guide for input files, external issues, amendments, recovery, and use by a solo developer or small team.

GitHub automation

GitHub issue intake, trusted workflow Approval, draft PRs, independent Review, and the watcher remain available as an optional mode. Set it up once per repository:

machinist onboard
# Review, stage, commit, and push the generated setup files, then:
machinist doctor --run-gates && machinist watch

The GitHub setup guide covers which setup files to stage, local and CI Spec generation, SHA-bound Approval, Review, and recovery. Managed workflows pin the installed controller version, so run machinist sync-workflows after each upgrade.

Commands

Upgrade

Upgrade an existing tool installation with uv tool upgrade agentmachinist.

machinist update-check compares the installed release against PyPI and prints the upgrade command for how this copy was installed (uv tool, pipx, pip, or a source checkout). machinist doctor reports the same result as a diagnostic row. Set MACHINIST_NO_UPDATE_CHECK=1 to suppress both probes on offline or CI machines.

Upgrading the package is not always the whole upgrade. Managed workflows are projected files: run machinist sync-workflows, review the generated changes, and commit and merge them into the default branch for hosted workflows to use them. machinist watch reports local drift at startup and machinist update-check reports it alongside the release comparison, so you do not have to run doctor to find out. The advisory never blocks a command and never appears in update-check --json.

Documentation

1. Understand the workflow: one diagram of your decisions and the controller's work. Prefer video? Watch AgentMachinist in 90 seconds. The Approval policy explains what each Approval authorizes.
2. Complete your first Task: the short installation-to-integration guide. Prefer illustrated instructions? Use the visual first-run guide.

The complete documentation index links every guide, reference, architecture decision, and historical plan. For detailed settings, use the configuration and GitHub reference. Contributor and release information lives in CONTRIBUTING.md and the changelog.

The trust model is deliberately narrower than “the agent cannot use git.” Harness flags, credential reduction, repository postconditions, and push leases reduce risk, but local harnesses still execute with the operating-system access of the user who launched them. Read the trust model before unattended use.

Releasing

Releases use PyPI Trusted Publishing. Bump pyproject.toml, update the changelog, and publish a GitHub Release tagged v<version>. The release job first checks tag/version equality, runs tests and workflow checks, builds both distributions, smoke-tests the installed wheel and sdist through a generated first-run project, and records SHA-256 hashes. A minimal job then publishes those verified artifacts. Only after publication do separate jobs attach the distributions and checksum file to the GitHub Release and verify that the exact version is visible and installable from PyPI.

License

MIT — see LICENSE.