machinist

A better way to put coding agents to work.

Give agents a task. Review the result.

Read the documentation View on GitHub

Start with an issue link or a description. Choose a workflow, track its progress, and review the saved files. Run one agent or split the work into steps with approvals.

Hand-drawn sectional elevation of a compact CNC milling machine with dimensions and numbered parts
SECTION A–ASCALE 1:5
⊕Local firstWorkers use your repositories
□Supervised by designAgents act under policies
＋Open and extensibleBring your own harness
○Precision toolsReliable, repeatable work
WHY MACHINIST

Agentic coding needs a process.

A single agent can write code. A reliable system also needs to define the work, review the result, handle failures, run checks, and keep a record of what happened.

01 / PROOF

Require proof

Keep results, files and execution history together. Add test and review steps to your workflow so you can inspect the evidence before continuing.

02 / FREEDOM

Change models without changing the workflow

Configure Codex, Claude Code, or another command-line harness on the worker. Choose a model for each task with a local alias.

03 / LEARNING

Improve the process

Prompts, command definitions, and model aliases live in files. Change them in Git and use focused evaluations to check the result.

HOW IT WORKS

One task. Clear steps. Saved results.

A workflow is an ordered list of agent prompts or scripts. Steps run automatically until one needs attention. Add an approval before building, or use a merge policy that sends higher-risk changes back for human review.

Architectural plan of a supervised coding-agent system with orchestration, execution, governance, and review layers
SUPERVISED AGENT SYSTEMCONTROL / REQUEST / REVIEW
DEFINED

Configuration in files

Prompts, commands, and models use TOML and Markdown that you can review and version.

REVIEWABLE

Approve or request changes

Review a stage’s saved result. Approve the next step or send feedback and review a revised version.

PERSISTENT

Files that follow the task

Each step reads and writes a shared task folder. Machinist saves snapshots, keeps earlier versions, and lets you view text files or download any output.

A WORKFLOW YOU CAN START WITH

Plan, review, then build.

Planning saves plan.md. You review it before build starts. Both stages use the same task folder; there are no file-input mappings to wire up.

  1. 01

    Plan

    Agent writes plan.md

  2. 02

    Your approval

    Approve or request changes

  3. 03

    Build

    Agent reads the plan and implements it

config.toml · using your configured commands
[workflows.plan_then_build]
steps = ["plan", { command = "build", approval = "before" }]

Prefer one agent? Use one step. Want automatic merging? The optional classify-then-merge example only auto-merges small, low-risk documentation changes after checks pass. Other changes require approval; missing checks or a changed reviewed commit block merging.

Set up your first task workflow
EVALUATION AND IMPROVEMENT

Measure the workflow before you change it.

Machinist stores ordered events, terminal outcomes, duration, and reported token use. It also includes a focused evaluation for the GitHub issue lifecycle. Broader outcome scoring and configuration comparison are planned, but are not part of the product yet.

  • ✓ Capture ordered events, outcomes, duration, and token use
  • ✓ Run a deterministic issue-lifecycle evaluation today
  • ✓ Version prompts and factory configuration in Git
  • → Build toward outcome scoring without auto-applying changes
Explore the evaluation suite
Exploded hand-drawn isometric of a precision linear rail and carriage assembly
EXPLODED DETAILRAIL + CARRIAGE ASSEMBLY
MODELS AND HARNESSES

Use Codex, Claude Code, or another CLI.

Machinist runs command-line executors configured on your worker. The worker maps model aliases to real model names and keeps credentials on the machine that runs the task.

C
CodexIncluded configuration
READY
CL
Claude CodeIncluded configuration
READY
$
Your CLI harnessConfigure any executable
OPEN
~/.machinist/worker.tomlLOCAL ONLY
# Bring your own harness and model aliases
[executors.codex]
command = ["codex", "exec", "--json", "--model={{machinist.model}}", "--sandbox", "danger-full-access", "-"]
models = { fast = "gpt-5.6-luna", deep = "gpt-5.6-sol" }

[executors.your_agent]
command = ["your-agent", "run", "--model={{machinist.model}}"]
SETUP

Build Machinist. Start with one issue.

One Go binary contains the CLI, local control plane, managed worker, SQLite history, and browser interface. No hosted account is required.

  1. 01

    Build

    Compile one local binary from the open-source repository.

  2. 02

    Initialize

    Create editable defaults for commands, executors, and your local worker.

  3. 03

    Run

    Send a narrow GitHub issue through the supervised production line.

OPEN SOURCE · MIT LICENSE

Run Machinist on a real issue.

Start with a small issue that has a clear result. Machinist will plan it, build it, review it, wait for checks, and hand the pull request back to you.

Read the setup guide Read the docs