Machinist

Machinist turns a task or GitHub issue into an implemented, independently reviewed, and checked pull request. It never merges the pull request.

Core model

• A task is one GitHub issue in the target repository, or a plain description.
• Assigning a task means starting machinist run or queuing machinist submit.
• Assign the same issue again to continue interrupted work. The task-to-pr command reuses an existing branch, worktree, and pull request for the task.
• When MACHINIST_RUN_ID is set, the agent is already inside a Machinist run. Follow the assigned task and do not start or submit another run.

Create a task

Reuse a supplied issue when it is open and belongs to the current repository. Otherwise create one issue with gh issue create. Keep it focused on one observable outcome and preserve the user's constraints. Do not invent implementation details that the request does not decide.

gh issue create --title "<short outcome>" --body "<problem, outcome, constraints, and acceptance evidence>"

Use the issue URL returned by GitHub for every later command.

Assign a task

Use direct mode for immediate local work. Pass an absolute Git worktree path:

machinist run \
  --command=task-to-pr \
  --repo=/absolute/path/to/repository \
  --prompt="Complete https://github.com/owner/repository/issues/123"

Use managed mode when the control plane and worker are already running. Pass the logical repository name from worker.toml:

machinist submit \
  --command=task-to-pr \
  --repo=repository-name \
  --prompt="Complete https://github.com/owner/repository/issues/123"

submit prints a job ID. Follow managed work in the local control-plane UI.

When the shared configuration defines a [triggers.github.<name>] trigger, adding its configured input label, normally machinist:requested, delegates that issue through the managed queue. Machinist verifies the label event and actor, admits the job durably, then replaces the input label with machinist:queued. The label has no effect when that GitHub trigger or its repository is not configured. machinist:requested and machinist:queued are intake labels; they do not report progress after the job starts.

Report status

Check the run in the control-plane UI or the machinist run output, then the linked pull request and its checks. The command finishes as completed, blocked, or failed with a short summary.

• For blocked work, fix the reported cause or answer the question, then assign the same issue again.
• For completed work, hand the pull request to a person. Never merge unless that person explicitly decides to do so.

When reporting status, include the issue URL, job ID when managed, pull request URL when created, checks, and blocker or next human action.