Repository navigation
Releases
AgentMachinist 0.21.0
AgentMachinist 0.21.0 puts the decision first when you inspect a local Task or revise a plan. It also refreshes the project's dependencies.
Read the decision before the details
machinist inspect T1opens with a bounded decision summary: the paths the Task changed, each Gate outcome, high-severity advisory Review findings, and the next actions you can take. The full plan, diff, checks, and history follow, and the actions repeat after them.- After
machinist revise T1 --feedback "...", AgentMachinist shows a bounded difference between the two Spec commits before the revised plan. A revision that changes only line endings says so. Every revised plan still needs fresh Approval. - The summary counts results before it truncates them, so omitted failures and findings stay visible. It leaves out an Execute report whose commit does not match the candidate instead of showing it as a passing check.
Recovery
- When
approveorcontinuemeets a stopped local Phase, the message namesmachinist retry --task T1 --phase execute. It used to print the GitHub issue form,machinist retry 1.
Documentation
- The documentation now lives at https://agentmachinist.com/docs/.
- The first-run guide covers the local workflow only. The GitHub Actions setup has its own page.
- Two new pages: a reader glossary, and a local Task lifecycle diagram that shows each state
machinist statusprints and the command that moves it.
Dependencies
- The lockfile moves to Click 8.5.1, pydantic 2.14.3, and pytest 9.2.0. The pinned development tools move to Ruff 0.17.5, mypy 2.4.1, and Hatchling 1.33.0. Runtime requirements keep their existing minimums.
- The managed Spec workflow template now pins
astral-sh/setup-uvv10.3.3. If your repository runs Spec in GitHub Actions, runmachinist sync-workflowsafter you upgrade.
Upgrade:
uv tool upgrade agentmachinist
machinist --versionPython 3.12 or later is required.
The release workflow verifies the exact version, builds and smoke-tests the wheel and source distribution, and publishes using PyPI Trusted Publishing. Distributions and SHA-256 checksums are attached after successful publication.
AgentMachinist 0.20.0
AgentMachinist 0.20.0 makes the local workflow easier to learn and inspect, and improves recovery before implementation.
Learn the workflow before your first Task
machinist rehearse --guidedpauses at the saved plan and reviewed candidate so you can practice Approval and acceptance for free. It runs from an installed package without a source checkout.machinist doctor --local --fresh-workshopchecks committed code and dependencies in a disposable checkout before a paid run.- CLI help and first-run documentation lead with the local plan, review, and integration journey.
Make informed decisions and recover safely
machinist revise T1 --feedback "..."revises an initial plan while preserving Task identity, prior Specs, and feedback history. Every revised plan needs fresh Approval.machinist inspect T1 [--json]brings the plan, candidate diff, checks, Review, and next action into one read-only view.machinist config show/set --localmakes saved local settings and their effects explicit.- Local retries can explicitly select another Harness or model without changing saved preferences.
Reliability and documentation
- Goose Specs and Reviews retain the final assistant answer from its structured transcript.
- Failed local Reviews report a concise error and retain raw output for diagnosis.
- Verification has larger finite time budgets for the full real-Git suite, preserving every check and publication guard.
- Documentation includes the updated 90-second explainer, clearer recovery guidance, more readable labels and headings, improved contrast in both themes, and simpler layouts. Commands, diagrams, and onboarding controls are preserved.
Install or upgrade:
uv tool install agentmachinist
# Existing uv installation:
uv tool upgrade agentmachinist
machinist --version
machinist rehearse --guidedPython 3.12 or later is required. The free rehearsal makes no model/API calls. Real Tasks use your configured coding assistant and its provider usage.
The release workflow verifies the exact version, builds and smoke-tests the wheel and source distribution, and publishes using PyPI Trusted Publishing. Distributions and SHA-256 checksums are attached after successful publication.
v0.19.0
0.19.0 adds a built-in Goose Harness adapter and clearer first-run guidance found by walking the first-Task path as a newcomer. Human Approval, exact-SHA binding, and controller ownership of Git operations remain unchanged.
- Add a built-in Goose adapter (
harness.name: goose). Spec and Review run
goose run -q --no-session --no-profile --with-builtin developer, and
Execute runsgoose run --no-session. The developer builtin can also write
files, so read-only custody is advisory and the controller's postconditions
enforce it, as for OpenCode. - Set
GOOSE_MODE=autofor every Goose run. The approval modes wait for a
confirmation that a headless Task Run cannot give. - Keep Goose out of first-run discovery. pressly/goose, a Go database
migration tool, installs the samegooseexecutable, so choose Goose with
--harness goose. - Goose has no managed GitHub Spec CI profile and no non-interactive auth
probe. Workflow projection refuses it with the local-dispatch recovery, and
doctorasks you to verify its login yourself. - Adapters can pin non-secret environment variables with
environment_overrides()and opt out of first-run discovery with
auto_select = False. - Point
config showandconfig setatmachinist startwhen neither
machinist.yamlnor saved local settings exist, instead of recommending
GitHub onboarding. Neither command creates a file. - Align help text with the local workflow:
onboardis optional GitHub
automation,amend --taskstarts from a reviewed candidate, and
retry --freshnames both defaults. - Document that the controller ignores global Git identity. Set
user.nameanduser.emailinside the repository, or Spec and candidate
commits use the AgentMachinist identity. The first-Task example now does
this and clones the repository before copying.
Upgrade:
uv tool upgrade agentmachinist
machinist --versionGoose is never chosen automatically; select it with machinist start --harness goose. If your commits should carry your name, set git config user.name and git config user.email inside the repository, because the controller ignores your global Git identity.
The release workflow verifies the package, publishes through PyPI Trusted Publishing, attaches wheel and source distributions with SHA-256 checksums, and checks an isolated install of the published version.
v0.18.0
0.18.0 adds combined local and legacy reporting, an opt-in single repair round inside Execute, and the first-run fixes found by setting up a fresh repository from scratch. Repair defaults off. Human Approval, exact-SHA binding, and controller ownership of Git operations remain unchanged.
- Report baseline Verification failures truthfully in the local workflow. The
Gate's own error replaces the misleading read-only Workshop message, files a
Gate created are named, failure messages show both output streams, and
statusprints the error, the log directory, and abaseline failedstate
with both recoveries. - Detect
uv run pytestwhenuvis installed andpython3 -m pytest
otherwise; a lockfile no longer selects the runner. - Check the checkout before
startsaves local configuration, name pending
paths in the refusal, and let--harnessand--test-cmdreplace saved
settings until the first Task exists. - Route
doctor,status,config,clean, andrunsto the local workflow
whenmachinist.yamlis absent.clean --task T1removes one local Task's
retained Workshops. - Add
examples/first-task, a disposable project for a first Task, linked from
the short guide and the README. - Simplify documentation navigation around the workflow diagram and a short
first-Task guide. Add complete Markdown/web directories, group alternate
formats and historical records, and retain existing document URLs. - Include local and legacy Task history in
machinist report, with explicit
source selection, separate Task namespaces, first-pass Execute and repair
outcomes, current local delivery snapshots, and token usage coverage. Reports
work without local setup or root configuration. Local/all telemetry export
requires an explicit endpoint; configured legacy export uses--source legacy. - Add an opt-in single repair round inside Execute after ordinary required
Verification failures. Persist the consumed round and extra-work deadline,
retain separate Evidence, recheck custody and limits, and rerun final gates.
Control failures stop immediately. Failed Task Runs still need explicit retry,
and interrupted repairs require a fresh attempt rather than replaying paid work. - Expand this repository's configured Verification to required, check-only
workflow drift, formatting, lint, types, and coverage/test gates. Existing
saved local configurations keep their settings until explicitly updated. - Align operating, visual, contributor, and architecture documentation with
the repair and reporting contracts in this release. Clarify metrics, recovery,
telemetry consent, and release availability; correct the managed Spec
workflow's instructions for switching back to local dispatch.
Upgrade:
uv tool upgrade agentmachinist
machinist --versionFor an existing managed GitHub setup, run machinist sync-workflows, review and commit any generated changes, and deliver them to the default branch. Existing saved local configurations keep their Verification settings until you edit them.
The release workflow verifies the package, publishes through PyPI Trusted Publishing, attaches wheel and source distributions with SHA-256 checksums, and checks an isolated install of the published version.
AgentMachinist 0.17.1
machinist init and machinist onboard now print explicit staging commands for managed workflow files. Fresh setup includes new workflows in the commit, setup reruns retain the right files, and mode changes include tracked workflow removals while leaving unrelated workflow edits unstaged. Review the staged diff before committing as before.
This release also includes the Approval policy, advisory source-text guidance in all three Harness prompts, and the workflow diagram prepared for 0.17.0. Human Approval and controller ownership of Git operations remain unchanged.
Upgrade:
uv tool upgrade agentmachinist
machinist --versionFor an existing managed GitHub setup, run machinist sync-workflows, review and commit any generated changes, and deliver them to the default branch.
The release workflow verifies the package, publishes through PyPI Trusted Publishing, attaches wheel and source distributions with SHA-256 checksums, and checks an isolated install of the published version.
AgentMachinist 0.16.0
AgentMachinist 0.16.0 makes the next step easier to find. CLI completion messages now suggest the next activity and a sample command throughout the local and GitHub workflows.
- Issue creation guides direct Spec generation, watcher processing, or hosted Spec progress according to the configured source.
- Spec and Approval receipts explain the human review step and how to wait for trusted GitHub Approval.
- Completed Review and local integration guide inspection and optional GitHub/GitLab publication. One-pass watcher runs print the same completion receipts.
- The full documentation directory has been reviewed and updated, including command examples, recovery instructions, Harness settings, and historical applicability notes.
Exact-SHA Approval, dispatch eligibility, structured JSON output, verification, and independent Review remain intact.
Upgrade with uv tool upgrade agentmachinist, then verify with machinist --version. The package name is agentmachinist; the executable is machinist.
AgentMachinist 0.15.0
AgentMachinist 0.15.0 adds optional local readiness diagnostics, exact remote-base validation for new legacy Task Workshops, and bounded, credential-redacting diagnostics. The guided local workflow and optional GitHub/GitLab publication from 0.14.0 are unchanged.
Install or upgrade
uv tool install agentmachinist
# Existing uv installation:
uv tool upgrade agentmachinist
machinist --version # 0.15.0Optional local readiness
machinist doctor --local
machinist doctor --local --json
# Explicitly run the configured Verification Gates in this checkout:
machinist doctor --local --run-gatesdoctor --local reuses the configuration resolution that start uses, checks Git, Harness probes, and verification command availability, creates no Task or runtime state, and contacts no forge. Plain machinist doctor keeps its GitHub setup checks.
Changes
- Add optional
machinist doctor --local [--json] [--run-gates]readiness for
new and existing local projects. Reuse start's configuration resolution,
inspect Git/Harness/verification readiness without creating local state or
contacting a forge, and execute project gates only when requested. Existing
GitHub doctor behavior remains available without--local. - Fetch and validate the exact remote base before provisioning a new legacy
Task Workshop. Deleted or renamed remote branches fail despite stale local
tracking refs; construction uses the captured commit. Existing remote Task
branches remain authoritative for recovery, and local Tasks remain offline
with respect to Git. - Sanitize bounded Git, GitHub, GitLab, and doctor diagnostics before rendering:
redact recognized credential syntax and remove unsafe terminal controls while
preserving useful multiline failures. Successful Git and forge data remains
unchanged; arbitrary raw logs are outside this defense-in-depth boundary.
See ADR 0004 · Local workflow guide · Visual first-run guide
Release verification
The tag points to merged commit 2b701f9438d68b4ff1fd49e7957e0799d95c6a05 (PR #44).
The pull request CI passed on Linux and macOS with Python 3.12, 3.13, and 3.14, including coverage, minimum dependencies, packaging, static checks, and both CodeQL analyses. The local bash scripts/verify.sh gate passed on the merged head: 1,508 tests at 88% coverage, lockfile, managed-workflow, format, lint, and type checks, and installed wheel and sdist smoke tests reporting 0.15.0.
The release PR also corrected two CI-environment assumptions in the new local doctor tests (a Git author name derived from the OS account, and a snapshot race with Git's background auto-maintenance); no controller behavior changed.
Full changelog: v0.14.0...v0.15.0
AgentMachinist 0.14.0
AgentMachinist 0.14.0 adds an end-to-end local workflow for solo developers and small teams. Start from a Git checkout, approve the exact Spec, and inspect a verified candidate with independent advisory Review. Integrate locally and publish to GitHub or GitLab when collaboration is useful.
Install or upgrade
uv tool install agentmachinist
# Existing uv installation:
uv tool upgrade agentmachinist
machinist --versionFirst local Task
machinist start "Handle an invalid timezone without crashing" --test-cmd "uv run pytest"
# Read the Spec and use the exact full SHA printed by start:
machinist approve --task T1 --spec-sha <full-spec-commit-sha>
machinist status T1
# Inspect the candidate diff and advisory Review before integrating:
machinist integrate T1
# Optional: matching origin and authenticated forge CLI required:
machinist publish T1 --provider gitlabLocal Tasks require at least one required Verification Gate and always complete independent Review. GitLab support covers issue import and MR publication through glab, including nested projects and self-managed hosts; it does not add hosted GitLab Spec CI or remote Approval. A local workflow can still use cloud models. Existing GitHub issue automation remains supported.
Changes
- Allow 30 minutes for the expanded real-Git CI test and package/release build jobs, keeping all checks required.
- Add the guided foreground local journey:
startsaves a Task and generates
its Spec;approve --task T1 --spec-sha <sha>continues verified Execute and
independent advisory Review. Status shows the local result and next action.
Initial setup needs Git, an installed Harness, and a verification command;
no origin, forge account, labels, daemon, or hosted workflows are required. - Add durable local Task IDs, exact repository/Task/Spec Approval, retained
candidate refs, reports, explicit amendments, cancellation, and retry. Local
Task Run construction reuses the dispatcher, lifecycle, custody, and
Verification engine. Local orchestration does not imply offline inference. - Add explicit local integration: fast-forward only, from a clean expected
base to the exact reviewed candidate, with persisted recovery intent.
Automatic and remote merges remain outside the controller's contract. - Make local publication optional and recoverable through GitHub PRs or GitLab
MRs. GitLab issue intake and MR publication use authenticatedglab, including
nested projects and explicit self-managed hosts. Exact repository/head
checks and leased pushes prevent silent destination changes or overwrites;
publication retries do not rerun successful Harness work or verification.
Native GitLab Spec CI and remote GitLab Approval are not included. - Fix GitHub setup PR's circular deployed-workflow prerequisite. Validate local
setup before creating the PR and check deployed readiness after merge.
Recognized partial onboarding resumes while preserving configuration. - Permit a fresh Review after a new successful Execute candidate, including
amendments, while blocking duplicate Review of the same successful head.
Print Review completion and finding counts instead of claiming it passed an
unimplemented severity policy. - Run rehearsal through the production local Phases, real Git, Verification,
Review, and integration. The default uses a deterministic fake Harness;
configured provider invocation remains an explicit--harnesschoice. - Accept Task bodies from files/stdin and preserve drafts on lint or creation
failure. Lint recognizes##and GitHub issue forms'###sections, respects
nested headings, and rejects empty or placeholder acceptance checkboxes. - Rename the daily Phase-attempt limit to
max_runs_per_day. Legacy
max_tasks_per_daystill loads with unchanged counting semantics; conflicting
aliases fail validation and effective configuration emits the canonical key. - Update the complete documentation set and interactive guides for local
onboarding, configuration and command namespaces, recovery, optional
publication, and GitLab support. Preserve earlier design records with
applicability notes and current references. - Reconcile a crashed Execute push from the remote Task branch as well as
GitHub's PR listing. When the listing lagged a push the controller had just
made, a fresh run failed its approved-head check and advised approving the
current head again, which could rerun the Harness on already-verified code.
That window now delivers the pushed implementation; the head-mismatch
messages say the remote branch moved after Approval and point at
machinist inspect. - One push step for fresh and resumed Execute runs. A retry after the
implementation commit re-enters the same leased push, observation, and
delivery instead of a separate resume-push path; a remote already at the
implementation is a no-op, one that moved elsewhere fails the lease. - Legacy GitHub
machinist approvetakes exactly one of--issue <n>or--pr <n>. The
positional target, which resolved issue-versus-PR ambiguity with its own
error, is removed; every documented example already used the flags.
Local workflow guide · Visual first-run guide
Release verification
The tag points to merged commit cf967186083f3195322bfb6fb0e76b7ae1a9b93d.
The release build and publication workflow passed all 1,413 tests, built and smoke-tested both distributions, published through PyPI Trusted Publishing, and verified an uncached install from PyPI. The release candidate CI passed on Linux and macOS with Python 3.12, 3.13, and 3.14, including coverage, minimum dependencies, packaging, and static checks.
The wheel and source archive were downloaded independently from GitHub and PyPI; both matched the attached SHA256SUMS. All 23 deployed documentation files matched the tagged source. The installed PyPI package passed the complete production local rehearsal with a deterministic fake Harness, including Spec, exact-SHA Approval, Execute, verification, Review, and local integration.
CI on the tagged, merged main commit also passed every job, including the complete Linux/macOS matrix and aggregate CI gate. Both CodeQL analyses passed on the same commit.
v0.13.0
- Trust an approval marker only when the managed approve workflow authored it
(github-actions[bot]). A marker typed by a human is no longer Approval,
whatever their repository association: only the workflow checks write
access before minting Evidence. A repository that runs its own approve
workflow must post the marker as the bot. Invariant 2 inCLAUDE.mdand
the architecture notes say so. - Remove
run --retry,run --resume, andrun --fresh. The one recovery
entry isretry <n> --phase execute --run [--resume|--fresh], which, unlike
the removed flags, also recovers an interrupted run. - Fix
retry --runon an Execute Task reporting "marked ready for review" and
sending the PR-ready notification while independent Review was enabled and
the PR was still draft. It now prints the Review next action, asrundoes.
The same renderer serves every command, soretry --phase review --run
now sends the PR-ready notification exactly asreviewdoes, andamend's
cancellation refusal usesrun's wording with the--clearhint. - Fix two operator instructions: Execute's approval refusal names the full
/machinist-execute <sha>form the workflow requires, and the Spec PR body
no longer claims that AgentMachinist only watches the label. - Stop writing Task Run Evidence that no recovery path or report reads
(ready_intended_sha,ready_observed_sha,review_required_sha,
completion_comment_intended_sha,completion_comment_observed_sha,
workspace_head,recovery_mode,pr_observed_base,
pr_observed_number,pr_observed_sha,verification_log_dir,
completion_duration_seconds,spec_recovery,resume_forbidden_reason)
and record the instruction overlay under one vocabulary
(instructions_sha256,instruction_paths,instruction_append) for Spec
and Execute. Existing records keep the old keys as readable unknowns. - The Workshop owns Git-custody invocation.
Workspace.git_custody()exposes
the tokenprovisioncaptured andWorkspace.resume(..., git_custody=)
asserts it before any Git subprocess, refusing with "start a fresh retry"
when the checkpoint has none; Execute's parallel custody layer is gone. A
custody violation detected after the Harness surfaces as aWorkspaceError
with the Workshop's message. - Verification Gate failures carry the engine's own message and report shape
in Task Run errors instead of a second renderer with a different separator
and excerpt length. - Internal simplifications with no operator-visible change: Harness adapters
spliceHarness._passthrough_argv()formodelandextra_args; preview
clones no longer write an ownership sidecar file; every Phase requires a
Claim and takes plain boolean options; Spec decides existing-PR identity
through repository custody and previews through the dispatcher; approved
label metadata lives once ingithub.py;RunDispositionand
WatchResultlose fields nothing read. - Correct invariant 7 in
CLAUDE.md: a crash after push is reconciled without
rerunning the Harness or the verification gates; gates rerun only when the
crash happened before the implementation commit.
Install or upgrade:
uv tool install agentmachinist # or: uv tool upgrade agentmachinist
machinist --version # 0.13.0Full changelog: https://github.com/vscarpenter/AgentMachinist/blob/main/CHANGELOG.md
v0.12.1
- Fix independent Review failing at "provision Review preview" with a misleading
"outside managed workspace root" error. Review named its ephemeral clone
review-issue-<n>, butWorkspaceonly accepts preview clones named
<repo>-preview-*; Review now usespreview-review-issue-<n>-<hex>, matching
Spec. A regression test drivesrun_review_phasethrough a realWorkspace. - Accept a Review report that a harness wraps in a Markdown fence or prefixes
with a sentence, as long as it contains exactly one JSON object followed by
nothing but whitespace or the closing fence. Two objects, trailing prose, or
no object still fail closed with "review report must be valid JSON". - State the Review report contract in the prompt: exactly one JSON object with
no fence or prose, and severity and confidence limited to low, medium, or
high. A harness previously had to guess the allowed levels and could emit
values such as "critical" that the parser rejects.
Install or upgrade:
uv tool install agentmachinist # or: uv tool upgrade agentmachinist
machinist --version # 0.12.1Full changelog: https://github.com/vscarpenter/AgentMachinist/blob/main/CHANGELOG.md