A visual field guide for version 0.2

Your first issue, machined into a PR.

Set up AgentMachinist, choose who writes the spec, approve the exact plan you read, and let your coding harness build behind a test gate.

AgentMachinist 0.2.0 is available on PyPI. Install it directly below. If machinist --version still prints 0.1.0, run uv tool upgrade agentmachinist.

Issue #42 agent-task SPEC SHA APPROVED $ harness implements $ uv run pytest tests passed READY Pull request #18 YOU review and merge INPUTPLANGATE 1 MACHINE WORKGATE 2OUTPUT
Human actions use safety orangeMachine work uses blueprint blue
  1. 01PrepareGit, gh, uv, harness
  2. 02InstallCLI and project files
  3. 03ConfigureHarness, tests, owner
  4. 04SpecIssue becomes a draft PR
  5. 05ApproveBind consent to one SHA
  6. 06ReviewTests pass; you merge

Station 01 / lay out the tools

Four tools. One repository. About fifteen minutes.

AgentMachinist coordinates software you already use. Get these four checks green before asking it to touch an issue.

Git

Creates isolated worktrees, commits controller-owned changes, and pushes with a lease.

git --version

GitHub CLI

Reads issues, opens PRs, records approvals, and reuses your authenticated GitHub session.

gh auth status

uv

Installs AgentMachinist and provides its locked Python environment.

uv --version

A coding harness

Choose Claude Code, OpenCode, Pi, or Codex. Log in before your first automated run.

claude --version

Station 02 / install the controller

Install, then check the number.

  1. Install the current release directly from PyPI.
  2. Confirm the CLI reports 0.2.0.
  3. Change into the repository you want agents to work on.

Already installed an earlier version? Run uv tool upgrade agentmachinist instead.

terminal / install
$ uv tool install agentmachinist

$ machinist --version
machinist, version 0.2.0

$ cd ~/code/your-project

Station 03 / choose the spec dispatcher

Where should planning happen?

For a first run, keep planning local. GitHub Actions is useful later, but it needs a provider secret and still hands implementation back to your local watcher.

Switch routes to see exactly what changes.

LOCAL ROUTE

Your Mac owns both machine phases

GitHubissue + PR machinist watchyour Mac coding harnessspec + implement Ready PRyou review github.spec_source: local

Local setup

  1. Run machinist init. The default config already selects local.
  2. Set your harness and test command in machinist.yaml.
  3. Run machinist doctor, then start machinist watch.
  4. Keep one watcher per repository. Local claims are not distributed locks.

Station 04 / initialize the project

Three lines deserve your attention.

machinist init creates the file. Your job is to choose a harness, leave spec ownership explicit, and give implementation a real test gate.

# machinist.yaml
version: 1

harness:
  name: claude-code
  command: null
  timeout_minutes: 30
  spec_timeout_minutes: 10

github:
  repo: null
  spec_source: local
  labels:
    trigger: agent-task
    approved: "machinist:approved"
  poll_interval_seconds: 60

workspace:
  root: ~/.machinist/workspaces
  strategy: worktree
  cleanup: on_success
  branch_prefix: agent/

tests:
  command: uv run pytest

Pick the harness you use

claude-code, opencode, pi, or codex. Local runs reuse its provider authentication.

Keep one spec owner

local is simplest for a first run. Changing ownership requires machinist sync-workflows.

Make tests real

A null command skips the gate. Use the same command you trust before merging a human PR.

terminal / initialize
$ machinist init
# edit machinist.yaml, then:
$ machinist doctor
PASS repository               /Users/you/code/your-project
PASS GitHub authentication    gh auth is active
PASS harness                  /path/to/claude
PASS test gate                uv run pytest
PASS workflows                managed workflows match config
PASS Task Runs                no failed or abandoned runs

$ machinist sync-workflows --check
Managed workflows match machinist.yaml.

Stations 05–08 / run one real issue

The first task, screen by screen.

Use a small issue with a visible test. Your first run should teach the workflow, not test the outer limit of your model or repository.

05 / WRITE THE INPUT

File one outcome, not a project.

Give the issue a clear title, acceptance criteria, and the agent-task label. “Add CSV export for filtered rows” is a first run. “Improve reporting” is not.

GitHub · add label agent-task
GITHUB ISSUEgood first input
42 Add CSV export for filtered rows Open · filed by you Acceptance criteria Exports only the currently filtered rowsPreserves visible column orderHas a focused automated test agent-task
06 / MAKE THE PLAN

Run one poll, or address the issue directly.

watch --once picks up eligible work and exits. spec 42 is the direct route. Either way, the result is a draft PR containing only the plan.

machinist watch --once
DRAFT PULL REQUESTmachine wrote the plan
DRAFT Spec: Add CSV export (#42) .machinist/specs/issue-42-spec.md DOCUMENT MAP SummaryRequirementsApproachTesting planOut of scope agent/issue-42
07 / STAMP THE BLUEPRINT

Approve the PR number, not the issue number.

Read the spec first. Then run machinist approve 18 for PR #18, or comment exactly /machinist-execute. Approval is bound to the current commit; edits make it stale.

machinist approve 18
HUMAN GATEapproval names one commit
CURRENT PR HEAD a17c98d42e6f machinist:approved SHA BOUND branch changes → approval stale
08 / BUILD, TEST, REVIEW

Let the machine work. Keep the merge.

The watcher or machinist run 42 provisions the approved branch, asks the harness to implement, runs your test command, pushes with a lease, and marks the PR ready. You review and merge.

machinist run 42
READY FOR REVIEWcontroller delivered; human decides
READY FOR REVIEW Add CSV export (#42) QUALITY GATE uv run pytest tests passed YOUR FINAL GATE Review the diff • Does the code match the spec?• Do the tests prove the outcome?• Are deviations explained? MERGE AgentMachinist never clicks merge.

The shop-floor board

Read status without guessing.

Run machinist status. The wording tells you who moves next. Scroll the board horizontally on a small screen.

awaiting spec

The trigger exists. Local watch or the configured CI owner must write the plan.

awaiting approval

A draft spec is ready. Read it before authorizing implementation.

approval pending

The label exists without trusted SHA evidence. Approve again.

approval stale

The branch changed after approval. Review and approve the new head.

approved

The exact head can execute. Run the watcher or the issue directly.

in review

Implementation reached the ready PR. You own review and merge.

Know the safety boundary

Guardrails, not a vault.

AgentMachinist keeps Git custody and detects ordinary harness violations, but the harness still runs as your operating-system user.

  • Spec runs request the strongest available read-only mode and reject file mutations.
  • Implementation checks for harness commits, remote pushes, and .machinist/ edits.
  • Common GitHub and SSH-agent credentials are removed from the harness environment.
  • These controls are not a VM, container, or protection from a malicious local executable.

Read the full trust model before unattended use.

LOCAL USER BOUNDARY AgentMachinist controller Git · GitHub · approval · tests · Task Runs Harness reads / edits workspace GitHub issues / branches / PRs YOU approve + merge

When the machine stops

Start with the sentence it gave you.

Failures are parked instead of retried forever. Expand the symptom that matches what you see.

Doctor reports a FAIL

Fix that prerequisite before running a task. Common causes are missing gh auth, a missing harness executable, or workflow drift.

machinist doctor
Status says approval pending

The label exists, but no trusted marker names the current SHA. Approve the PR again with the CLI or exact comment.

machinist approve <pr>
Status says approval stale

The spec branch changed after approval. Read the new diff, then approve the current head. This is a safety stop, not a synchronization bug.

machinist approve <pr>
A Task Run failed

Inspect the retained workspace and error first. Fix the cause, mark the phase retryable, then restart a long-running watcher.

machinist retry <issue> --phase execute
The workspace already exists

That is usually retained evidence from a failure. Inspect it before removal. Worktrees should be removed with Git, not by blindly deleting directories.

git worktree list
Tests failed

Nothing new is pushed by the controller. Open the retained workspace, reproduce the test command, and decide whether the spec, implementation, or test needs correction.

machinist status

Pocket checklist

Ready to make the first cut?

Check these off as you go. The guide remembers your checks in this browser.

Keep nearby

Full getting-started reference Operator runbook Harness support matrix Trust model