AgentMachinist - Onboarding

Run a one-person machine shop for your code

AgentMachinist turns your GitHub issues into reviewed, tested pull requests — built by the coding agent you already use, on your own Mac, with you signing off at every step that matters.

amber = you act blue = the machine acts

The whole system in one line: work alternates between you (amber) and the machine (blue), and it always ends with your merge.

The one principle everything follows

Coding agents are fast, but speed without checkpoints is how you end up with code you don't understand in a repo you no longer trust. AgentMachinist's answer is simple: the expensive machine work only ever happens between two cheap human decisions.

Gate 1 is cheap — rejecting a plan costs a minute. Gate 2 is thorough — real code review. The machine never merges.

Gate 1 works because a plan is much easier to judge than code. The spec is a short Markdown document in a draft PR: what will be built, which files change, how it will be tested. If it's wrong, you close the PR and sharpen the issue — no code was written, nothing was wasted.

How it's built, in plain terms

Local-first

Local runs use the GitHub CLI session and provider authentication already available to your harness. CI may require a scoped provider secret.

Your files are never touched

Every task runs in its own disposable workshop (a git worktree), away from whatever you're editing. Your checkout, including uncommitted work, stays exactly as you left it.

Permissions match trust

Spec adapters request their strongest available read-only mode and the controller rejects file mutations. OpenCode's plan mode remains advisory; the trust model names that limit.

Tests are the gatekeeper

After implementing, your test command runs. If it fails, nothing is pushed and the PR stays draft — you get the failing workshop kept on disk to inspect.

Everything is visible on GitHub

Specs are commits, approvals bind a label to an exact SHA, and PR state stays visible. Local Task Run records preserve failures and recovery checkpoints.

Bring your own agent

Claude Code is the default, but OpenCode, PI, and Codex plug into the same pipeline through one config line.

Each task gets a fresh workshop branched from GitHub. It talks to GitHub — never to your working copy. Successful workshops are cleaned up automatically; failed ones are kept so you can look inside.

Set up in three steps

Check your tools

You need git, the GitHub CLI signed in (gh auth status), uv, and at least one coding agent CLI such as claude.
Install the machinist
```
uv tool install agentmachinist
```
Straight from PyPI. Then confirm with machinist --version.
Initialize your project
```
cd ~/code/my-project
machinist init
```
This writes machinist.yaml, creates a spec folder, installs the approval workflow, and creates the pipeline labels. The default local spec dispatcher omits the CI spec workflow. Set your test command before anything else.
```
tests:
  command: npm test   # or pytest, cargo test, go test ./...
```
Commit the new files and push. You're operational.

A day with the machinist

The system fits around your day instead of demanding it. Here's the rhythm it settles into:

Amber moments are yours; blue stretches belong to the machine. None of the amber moments take long — that's the point.

Prefer to drive manually? Every stage is also a command: machinist spec 12 plans one issue, machinist run 12 implements an approved one, and machinist watch --once does a single sweep — handy under cron.

Comforts of a well-run shop

A few details exist purely so the system feels trustworthy while it works:

It never looks hung

Agent runs can take many minutes. Every half minute machinist prints a pulse — … claude-code still working (4m 30s elapsed) — so silence never means mystery.

Failures find you

If a daemon dispatch fails while you're away, machinist sends a macOS notification with the issue number and reason. Best-effort: on other systems it simply stays quiet and logs as usual.

Rework is deliberate

Failures become durable Task Runs. Fix the cause and use machinist retry; a finished run is not silently dispatched again.

No label homework

machinist init creates both pipeline labels in your repository. If the repo has no remote yet, it just tells you and moves on.

The two things everyone gets wrong once

GitHub's green “Approve” review button is not the approval. Use machinist approve <pr> or comment exactly /machinist-execute. The system records the label and current head SHA together; a label without matching evidence cannot execute.

And leave the spec PR as a draft. Flipping it to “Ready for review” yourself pauses the daemon — draft means “not yet built”, and the machine flips it to ready itself when the implementation lands.

Getting good specs out of it

The machine plans from your issue the way a machinist works from a drawing: it can only be as precise as what you hand it. Three habits make the difference:

One outcome per issue. “Add CSV export to the reports page” specs beautifully. “Improve the app” doesn't. If a spec comes back sprawling, that's the signal to split the issue.
Say how you'll know it's done. A sentence of acceptance criteria (“exports the filtered rows, not the whole table”) shows up almost verbatim in the spec's testing plan.
Treat a bad spec as cheap feedback. Closing a spec PR costs nothing and teaches you what your issue left ambiguous. Reject freely at Gate 1 so you rarely have to at Gate 2.

When something goes wrong

machinist status is your shop-floor board — it shows every issue and PR in the pipeline and what each is waiting for. Beyond that, the failure behavior is designed to be boring:

Tests failed? Nothing was pushed. The workshop folder is kept on disk (the error tells you where) so you can open it and see exactly what the agent did.
A task keeps failing? The daemon will not burn agent time in a loop. Fix the cause, run machinist retry <issue>, and restart a long-running watcher.
Bad code got through to the PR? That's what Gate 2 is for. Push your own fixup commits to the branch, or close the PR — the machine never merges, so nothing lands without you.

Command reference

Command	What it does
machinist init	Sets a repository up: config file, spec folder, GitHub workflows.
machinist doctor	Runs read-only setup, auth, harness, test-gate, and workflow-drift checks.
machinist sync-workflows	Projects config and the installed version into managed workflows. `--check` only verifies.
machinist watch	Runs the daemon: plans labeled issues, implements approved specs. `--once` for a single pass.
machinist spec <n>	Plans one issue by hand — spec, branch, draft PR.
machinist approve <pr>	Binds approval to the draft PR's current head commit.
machinist run <n>	Implements one SHA-approved spec by hand and runs the configured test gate.
machinist retry <n>	Makes one failed phase eligible for an explicit retry.
machinist status	Shows where every issue and PR stands in the pipeline.

AgentMachinist is open source (agentmachinist on PyPI) and is, fittingly, partly built by itself: its getting-started guide — and even the watch daemon's own failure notifications — were specced, approved, implemented, test-gated, and shipped through this exact pipeline. Full details live in the repository's docs/ folder.