Skip to main content

AgentMachinist

Website and docs: agentmachinist.com

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, Codex, OpenCode, Pi, 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.21.0. Package reference: AgentMachinist 0.21.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, codex, opencode, pi, or goose). GitHub operations require authenticated gh; GitLab operations require authenticated glab. The core CLI runs on macOS and Linux with Python 3.12 or newer (tested on 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."

Revision shows the difference from the previous saved Spec before the new plan. Each revision needs fresh Approval, including when its text is unchanged. 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 a decision summary first, followed by the plan, change, checks, and Review. The summary covers accumulated Task files, including amendments; the detailed diff covers the latest Execute. Then accept the reviewed change with integrate:

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

start, revise, and approve use your Harness's model and provider quota. The guided rehearsal remains free. If a command stops, machinist status T1 prints the error and the next command. Saved settings, baseline recovery, and optional publication are in the short guide and the local workflow guide. To try the loop on something disposable first, copy examples/first-task.

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

Command Purpose
machinist start [<objective>] [--body-file <path>] [--from-issue <url>] Save a local Task, generate its Spec, and stop for exact human Approval.
machinist revise <Tn> --feedback <text> Correct an initial local Spec before implementation; read and approve its new exact SHA.
machinist approve --task <Tn> --spec-sha <sha> Approve one local Spec and continue Execute, verification, and Review in the foreground.
machinist continue <Tn> Continue eligible local work or show the next required human action.
machinist status <Tn> [--json] Inspect one local Task and its next action without forge access.
machinist inspect <Tn> [--json] Read the local plan, candidate diff, Verification, Review, and next action together.
machinist integrate <Tn> Explicitly fast-forward a clean local base to the exact reviewed candidate.
machinist publish <Tn> --provider github|gitlab [--host <host>] Publish the reviewed local candidate as a PR or MR with recoverable intent.
machinist retry --task <Tn> --phase spec|execute|review [--fresh] Explicitly retry a failed local Phase in the foreground.
machinist retry --task <Tn> --phase execute --fresh --harness <name> [--model <id>] Retry once with another installed Harness or model; the choice is not saved.
machinist amend --task <Tn> --feedback <text> Turn feedback on a reviewed candidate into a new Spec that needs fresh Approval.
machinist init [--yes] Create config, spec storage, labels, managed issue form, and workflows; asks setup questions in a terminal (--yes hands-free, --no-input skips without auto-enabling test command).
machinist onboard [--setup-pr] [--yes] Run guided setup in place or deliver only managed setup files on a draft PR; --yes accepts defaults + detected test command.
machinist rehearse [--guided] [--harness] Try the local workflow free with a fake Harness; guided mode pauses for your decisions. Paid Harness use is opt-in.
machinist doctor [--run-gates] Run read-only setup and workflow-drift diagnostics; single health check that prints the exact fix for any FAIL (only run individual --check commands if doctor asks). Without machinist.yaml, plain doctor runs the local readiness checks.
machinist doctor --local [--run-gates|--fresh-workshop] [--json] Check local readiness; explicitly run Gates in the current checkout or a disposable committed checkout.
machinist update-check [--json] [--timeout <seconds>] Compare the installed release against PyPI, print how to upgrade, and report managed-workflow drift.
machinist sync-workflows [--check] Write or verify config-derived workflows.
machinist sync-labels --check|--apply Verify or create the two configured lifecycle labels.
machinist config validate|show|schema|set Validate, inspect, export, or atomically update configuration; show --local and set ... --local select saved local settings explicitly.
machinist task template --write|--check Project or verify the sealed GitHub issue form.
machinist task new --title <title> [--body-file <path>] [--dispatch] Create a structured GitHub issue; preserve drafts on failure and dispatch only after lint passes.
machinist task lint <issue> [--json] Check objective, acceptance criteria, constraints, and verification readiness.
machinist spec <issue> [--dry-run] Preview a Spec, or generate it and open its draft PR.
machinist spec <issue> --revise Regenerate a successful Spec on its existing branch and PR.
machinist spec <issue> --abandon [--reason <text>] Record rejection and close the open draft PR.
machinist approve [--issue <issue>|--pr <pr>] Request asynchronous workflow Approval for the current PR head; wait for trusted Evidence before Execute.
machinist run <issue> Implement an approved Spec and run the configured Verification Gates.
machinist review <issue> When legacy Review is enabled, independently review the exact implemented draft and mark it ready.
machinist amend <issue> --feedback <text> Rework a ready PR from explicit feedback after fresh approval.
machinist cancel <issue> [--reason <text>|--clear] Cooperatively stop or block an issue's dispatch.
machinist watch [--once] [--dry-run] [--max-tasks <n>] Preview or dispatch eligible tasks continuously or once.
machinist queue pause|resume|defer|allow|show Persist operator controls over new watcher dispatches.
machinist service install|start|restart|stop|status|logs|uninstall Manage the repository's macOS launchd watcher; destructive lifecycle actions refuse active Claims unless forced.
machinist explain <issue> [--json] Show effective policy, resolved profiles, attempts, and the exact next action without secrets.
machinist status [--local|--all] [--json] With local configuration, default status and --local show local Tasks. Otherwise, default status shows the GitHub board and --local reads legacy Run Evidence. --all shows the registered GitHub portfolio.
machinist status --watch [--interval <seconds>] [--json] Emit changed-only live pipeline snapshots until Ctrl-C.
machinist runs [--issue <issue>] [--json] Read current, historical, orphaned, and corrupt local run records.
machinist report [--source all|legacy|local] [--since 30d] [--json] [--otlp-endpoint <url>] Aggregate both history namespaces by default; local/all export requires an explicit endpoint.
machinist retry <issue> [--phase spec|execute|review] Re-enable one failed Task Run.
machinist retry <issue> --phase execute --run [--resume|--fresh] Reuse a retained workspace or start a fresh Execute attempt; fresh is the default.
machinist inspect <issue> [--offline] [--json] Show GitHub, workspace, and complete Task Run diagnostics.
machinist repo add|remove|list Maintain the optional local repository registry.
machinist clean [--issue <issue>|--task <Tn>|--all] List or remove retained Workshops for GitHub issues and local Tasks.

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.

Metadata

Release files for agentmachinist 0.21.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for agentmachinist 0.21.0
File Size Uploaded Provenance Actions
agentmachinist-0.21.0.tar.gz 544.7 kB With provenance Details for agentmachinist-0.21.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for agentmachinist 0.21.0
File Interpreter ABI Platform Actions
agentmachinist-0.21.0-py3-none-any.whl Python 3 none any Details for agentmachinist-0.21.0-py3-none-any.whl

Total release size: 843.9 kB

Release files / agentmachinist-0.21.0.tar.gz

Download URL agentmachinist-0.21.0.tar.gz
Size 544.7 kB
Tags Source
SHA-256 checksum
How to use checksums
9809315c791223d75c7c9a00a23d4794b8a073a85cd8ccb518223a7ec3d1d038
BLAKE2b-256 checksum
How to use checksums
dd54ba3f9fee1be9456930d349dd66f4b465ccaddc59cf62ec71277c2b9fa228
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / agentmachinist-0.21.0-py3-none-any.whl

Download URL agentmachinist-0.21.0-py3-none-any.whl
Size 299.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ebc94a45f46503e4df60cf9a23127f0901e9ab02e849b654ceee001a4e564d82
BLAKE2b-256 checksum
How to use checksums
789852116b961130cde882cbc8d43e589d9b7166b4815814bfed03753e3abe8d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Security for agentmachinist 0.21.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for agentmachinist-0.21.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page