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

Everything runs on your Mac using the logins you already have — your GitHub CLI session and your coding agent's own account. There are no API keys to create or store.

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

While writing the spec, the agent can read your code but can't change a file. Edit rights only switch on after you approve — the gates exist in the process itself, not just in policy.

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 are labels, progress is PR state. There's no hidden database — you can audit every decision in your repo's history.

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 git+https://github.com/vscarpenter/AgentMachinist

Then confirm with machinist --version.

Initialize your project
```
cd ~/code/my-project
machinist init
```
This writes machinist.yaml, creates a spec folder, and installs two small GitHub workflows. Open machinist.yaml and set one thing before anything else: your test command.
```
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.

The one thing everyone gets wrong once

GitHub's green “Approve” review button is not the approval. GitHub actually blocks that button on your own PRs. To approve a spec, add the machinist:approved label — or simply comment /machinist-execute on the PR, which does it for you.

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 won't retry it in a loop and burn agent time — it parks the issue until you restart watch after fixing the cause.
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 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 run <n>	Implements one approved spec by hand.
machinist status	Shows where every issue and PR stands in the pipeline.

AgentMachinist is open source and was, fittingly, partly built by itself: its getting-started guide was specced, implemented, test-gated, and shipped through this exact pipeline as the project's first task. Full details live in the repository's docs/ folder.