A visual field guide for the 0.8 release

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.8.0 is available on PyPI. Install it directly below. If machinist --version still prints an older version, run uv tool upgrade agentmachinist.

Human actions use safety orangeMachine work uses blueprint blue

01PrepareGit, gh, uv, harness
02InstallCLI and project files
03Choose a modeWho writes the spec
04ConfigureHarness, tests, labels
05File the issueOne outcome, labeled
06SpecIssue becomes a draft PR
07ApproveBind consent to one SHA
08ReviewTests pass; you merge

Fast Track · The 60-Second Loop

For experienced CLI developers

Already authenticated with GitHub and your coding harness? Here is the entire issue-to-tested-PR sequence at a glance.

terminal / quick-run

# 1. Install, then answer init's setup questions in your repository:
$ uv tool install agentmachinist && machinist init

# 2. Review the generated files; verify:
$ machinist doctor && machinist sync-workflows --check
$ git status --short
$ git add machinist.yaml .machinist/specs/.gitkeep .gitignore
$ git add -p .github/workflows
$ git diff --cached
$ git commit -m "chore: configure AgentMachinist" && git push

# 3. File issue with 'agent-task', then generate draft spec PR:
$ machinist spec 42

# 4. Review spec and stamp approval (accepts PR #18 or issue #42):
$ machinist approve --issue 42

# 5. Implement spec, run test gate, and flip PR to ready:
$ machinist run 42

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

Claude Code

Anthropic coding CLI

claude auth login name: claude-code

OpenCode

Open-source agent

opencode auth login name: opencode

Codex

CLI sandbox agent

codex login name: codex

Pi

Lightweight agent

pi auth check --model <model> name: pi

AgentMachinist owns each adapter's sandbox and permission controls. Configure extra_args only for advanced provider options; adapter-owned safety flags are rejected.

Station 02 / install the controller

Install, then check the number.

Install the current release directly from PyPI.
Confirm the CLI reports 0.8.0.
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.8.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.

Route switching needs JavaScript. The recommended local route is shown below; the complete CI route is also documented in Getting Started.

LOCAL ROUTE

Your Mac owns both machine phases

Local setup

Run machinist init. Accept local at the dispatch question — it is the default.
Pick your harness and confirm the detected test command at the prompts (or edit machinist.yaml later).
Run machinist doctor, then start machinist watch.
Keep one watcher per repository. Local claims are not distributed locks.

Station 04 / initialize the project

Four lines deserve your attention.

machinist init creates the file — and in a terminal it now asks about each of these choices directly: dispatch mode, managed workflows, harness, test gate, and notifications, each with a one-line explanation and a safe default. Answer them once and the config below is correct on the first write.

# machinist.yaml
version: 1

harness:
  name: claude-code
  command: null
  model: null
  extra_args: []
  timeout_minutes: 30
  spec_timeout_minutes: 10
  spec: null
  execute: null

github:
  repo: null
  spec_source: local
  spec_install: pypi
  manage_workflows: true
  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. model is optional. AgentMachinist rejects adapter-owned safety flags in extra_args; keep other additions empty unless you have reviewed the final adapter command.

Keep ownership explicit

local is simplest for a first run. Changing dispatcher ownership requires machinist sync-workflows. manage_workflows: false means you own custom workflows and doctor intentionally skips managed drift checks.

Make tests real

When no named verification.gates exist, a null command skips verification. Configure either the command you trust before merging a human PR or named gates with the same standard.

This is an abridged first-run configuration. Before dispatch, use machinist config validate and machinist config show. Advanced configuration supports separate Spec/Execute harness profiles, bounded instruction overlays, ordered named verification gates, notifications, admission budgets, and change limits; the full reference is linked below.

terminal / initialize

$ machinist init
Configuring machinist.yaml — press Enter to accept a [default],
or rerun with --no-input to skip these questions.

Dispatch mode — who runs the Spec phase when you label an issue:
  local           this machine runs it via 'machinist watch'
  github-actions  GitHub CI runs it (requires an ANTHROPIC_API_KEY repository secret)
Spec dispatch [local]:

# … managed workflows, harness, and notifications questions follow …

Test gate — command that must pass before an implementation PR is
marked ready for review.
Use detected test command 'uv run pytest'? [Y/n]:

# Review the generated files, 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.

# Review every generated file before making setup durable:
$ git status --short
$ git add machinist.yaml .machinist/specs/.gitkeep .gitignore
$ git add -p .github/workflows
$ git diff --cached
$ git commit -m "chore: configure AgentMachinist"
$ git push

machinist init adds /.machinist/runs/ to .gitignore. Flags pre-answer questions and skip them: --spec-source, --harness, --test-cmd, and --notifications; --no-input (or any non-interactive shell) skips every question and keeps the silent defaults with test-command auto-detection. --no-workflows records manage_workflows: false for externally managed workflows; doctor then reports that its managed drift check was intentionally skipped.

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 Issue Prompt Template

### Summary
Add CSV export for filtered rows on the table.

### Acceptance Criteria
- [ ] Exports only the currently filtered rows
- [ ] Preserves visible column order
- [ ] Has a focused automated test

### Out of Scope
- Background email delivery

GITHUB ISSUEgood first input

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.

Silence is normal while the harness thinks: the CLI prints still working (2m 30s elapsed) every 30 seconds, and spec runs stop at ten minutes by default.

machinist watch --once

DRAFT PULL REQUESTmachine wrote the plan

07 / STAMP THE BLUEPRINT

Approve the PR number or the issue number.

Read the spec first. Run machinist approve --pr 18 for PR #18 (or machinist approve --issue 42 for issue #42), or copy the SHA-bound /machinist-execute <full-spec-commit-sha> command from the PR body. The positional form is accepted only when the number is unambiguous. Approval is bound to the authorized commit; edits make it stale.

machinist approve --pr 18

Want to revise or reject the Spec?

Regenerate a successful Spec on its existing branch and draft PR, then review and approve the new head:

machinist spec 42 --revise

# Or explicitly reject it and close the open draft PR:
machinist spec 42 --abandon --reason "requirements changed"

--reason is optional. Abandonment records the outcome and removes the trigger and approval labels; it never merges.

HUMAN GATEapproval names one commit

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 — iterating against your configured test gate until it passes — then runs the gate itself as the authoritative check, pushes with a lease, and marks the PR ready. You review and merge.

machinist run 42

What if the test gate fails?

The controller keeps the failed workspace instead of pushing bad code. Inspect it, then choose whether its edits belong in the next attempt:

machinist inspect 42

# Validate and continue the retained managed workspace:
machinist retry 42 --phase execute --run --resume

# Or start again from the approved head (the default):
machinist retry 42 --phase execute --run --fresh

READY FOR REVIEWcontroller delivered; human decides

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, .machinist/ edits, and deleted test files.
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.

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 <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 <pr>

A Task Run failed

Inspect the error and retained workspace first. Use --resume to validate and continue that managed workspace, or --fresh to provision another attempt from the approved head. Fresh is the default when neither flag is supplied.

machinist retry <issue> --phase execute --run --resume

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. Inspect the retained edits and test output, fix the underlying cause, then explicitly resume those edits or start fresh.

machinist retry <issue> --phase execute --run --fresh

A running task must stop

Request cooperative cancellation. The durable marker also blocks a later watcher dispatch; clear it only after inspecting the cancelled run and resolving the cause.

machinist cancel <issue> --reason "requirements changed"

The macOS watcher is quiet

Check whether its LaunchAgent is loaded, then read the bounded recent stdout and stderr. Service logs remain after stop or uninstall.

machinist service status
machinist service logs --lines 100

Pocket checklist

Ready to make the first cut?

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

Git, gh, uv, and one harness respond
machinist --version matches this guide
Harness, spec owner, and test command are set
machinist doctor has no FAIL checks
Generated files and the runtime ignore are reviewed, committed, and pushed
A small issue has acceptance criteria and agent-task
I know the machine never merges for me

Keep nearby

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

Quick Reference

Command Cheatsheet

Keep these core subcommands nearby for day-to-day work.

Command	What it does
`machinist init`	Set up `machinist.yaml`, `.machinist/`, workflows, and labels. Asks setup questions in a terminal (`--no-input` skips them); auto-detects test runners.
`machinist doctor`	Read-only diagnostics for Git, `gh`, harness binaries, test gate, and workflow drift.
`machinist config validate\|show\|schema\|set`	Validate, resolve, export, or atomically update `machinist.yaml`.
`machinist status [--local\|--all] [--json]`	Show GitHub state, local evidence, or every repository in the optional registry.
`machinist spec <n> [--dry-run\|--revise\|--abandon]`	Preview or generate a Spec, revise its existing draft PR, or abandon it. Add `--reason "text"` with abandonment.
`machinist approve [--issue <n>\|--pr <n>]`	Approve a draft PR by explicit issue or PR number, bound to its exact commit SHA.
`machinist run <n> [--retry]`	Execute implementation and run test gate for issue `<n>` (Phase 3).
`machinist amend <n> --feedback "text"`	Rework a ready PR from explicit feedback after fresh approval of its current head.
`machinist cancel <n> [--reason "text"\|--clear]`	Cooperatively stop or block an issue, or clear its durable cancellation marker.
`machinist retry <n> --phase execute --run [--resume\|--fresh]`	Retry Execute using retained edits or a new workspace. Fresh is the default when neither recovery flag is supplied.
`machinist clean [--issue <n>\|--all]`	Safely remove or prune retained worktrees under `workspace.root`.
`machinist inspect <n> [--offline] [--json]`	Display complete local history and, unless offline, GitHub and approval evidence.
`machinist runs [--issue <n>] [--json]`	Read current, historical, orphaned, and corrupt local Task Run records.
`machinist watch [--once] [--dry-run] [--max-tasks <n>]`	Preview eligibility or poll GitHub and dispatch only admitted Tasks.
`machinist queue pause\|resume\|defer\|allow\|show`	Persist global and per-issue controls over new watcher dispatches.
`machinist service install\|start\|restart\|stop\|status\|logs\|uninstall`	Manage the per-repository macOS launchd watcher and its retained logs.
`machinist repo add\|remove\|list`	Maintain the optional local repository portfolio used by `status --all`.
`machinist sync-workflows [--check]`	Project configuration into managed `.github/workflows/` files.