AgentMachinist

AgentMachinist is a local-first, issue-to-reviewed-PR build pipeline for solo developers. It connects GitHub issues to Claude Code, OpenCode, Pi, or Codex, with a human-approved specification between planning and implementation.

issue + trigger label → spec commit → draft PR → SHA-bound approval
                    → implementation → test gate → ready PR → human merge

The controller—not the harness—owns commits, pushes, PR transitions, and task records. AgentMachinist never merges.

Current release: AgentMachinist 0.2.0 on PyPI.

Install

uv tool install agentmachinist

You also need git, an authenticated gh, and one supported harness executable (claude, opencode, pi, or codex).

Start

cd your-repository
machinist init
# Set tests.command in machinist.yaml, then:
machinist doctor
machinist watch

The default github.spec_source: local makes watch own spec generation. Choose github-actions and run machinist sync-workflows if CI should own that phase instead. Exactly one source is active, preventing duplicate spec runs.

Approval is bound to the exact PR head commit. Use either:

machinist approve 57
# or post the exact PR comment: /machinist-execute

Editing the spec after approval makes that approval stale and blocks execution until the new head is approved.

Commands

Documentation

• Getting started
• Visual first-run field guide
• Architecture and lifecycle
• Operator runbook
• Trust model
• Harness support
• Visual handbook
• Contributing
• 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 requires tag/version equality, runs the suite, builds both distributions, installs and smoke-tests the wheel, and publishes last.

License

MIT — see LICENSE.