For Claude Code, Codex, OpenCode, Pi, and Goose
AgentMachinist takes your coding agent from a plan you approve to a tested, reviewed local change you choose to accept.
uv tool install agentmachinist machinist rehearse
You need macOS or Linux, Python 3.12 to 3.14, Git, and uv. The rehearsal runs the whole loop with a fake agent, so it costs nothing.
Watch the 90-second tour Read the guide for unreleased features
The problem
The hard part is knowing what they'll change, and trusting what comes back. AgentMachinist puts a written plan in front of the work and an independent review behind it. Your agent still does the typing.
What you keep
Decision 1 · before any code
Your agent drafts a plan, called the Spec. AgentMachinist saves it as a Git commit, which you approve by its full commit hash. If the plan changes, you approve again before anything runs.
machinist approve --task T1 --spec-sha <full-spec-sha>
Decision 2 · before it lands
Read the Review findings and inspect the changes. Integration fast-forwards your clean branch to the exact candidate that was reviewed. AgentMachinist never merges automatically or remotely.
machinist integrate T1
How it works
Orange is you. Blue is the machine. Each machine step runs in the foreground after your command, and a failure stops so you can retry it.
01 · You
One objective in a clean Git checkout, with your real test command.
02 · Machine
Your tests pass on the current code. Then a read-only agent drafts the Spec, and AgentMachinist commits it.
03 · You
Read the plan, then approve its exact saved version.
04 · Machine
Your agent edits in an isolated Workshop. Your tests must pass, and AgentMachinist makes every commit.
05 · Machine
A separate read-only pass checks the diff against the Spec and the test evidence. Its findings are advisory.
06 · You
Fast-forward your branch, or open a GitHub pull request or GitLab merge request.
See who owns each step in the full diagram
These additions are unreleased and require a source checkout containing the new functionality. The published package uses the commands in Get started below.
Practice both decisions with machinist rehearse --guided. It pauses before approving the saved plan and accepting the result. A fake agent runs the workflow without model calls, and declining keeps the sample for inspection.
Correct the initial plan with machinist revise T1 --feedback "Keep the public API unchanged." before coding starts. It saves a new Spec for the same Task. Read it and approve its new exact commit. Real plan revisions use your agent's plan or API credits.
Inspect before accepting with machinist inspect T1. It puts the saved plan, exact changes, test results, Review findings, and next action together. The Review stays advisory.
Check a fresh checkout by adding --fresh-workshop to machinist doctor --local. It runs your project's checks in a disposable clone of committed files, with no Task or model call. Checks may download dependencies.
See saved local settings with machinist config show --local. Use config set with --local to update them for later commands.
Follow the guide for these unreleased tools, or read the local workflow reference for commands and recovery.
Watch
Coding agents can write a feature in minutes. The hard part is knowing what they'll change, and trusting what comes back.
AgentMachinist takes one small task from intent to a reviewed change, on your machine, with the coding agent you already use.
You describe the task. Your agent drafts a spec, and AgentMachinist commits it.
Then you approve that exact spec by its commit hash. If the spec changes, you approve again before anything runs.
The agent builds in an isolated workshop, away from your checkout. Your tests must pass, and AgentMachinist makes every commit.
Next, a separate read-only review checks the result against the spec and the test evidence.
You read the report, inspect the diff, and integrate with a fast-forward. Nothing merges behind your back.
Sharing is optional. One command opens a GitHub pull request or a GitLab merge request.
It works with Claude Code, Codex, OpenCode, Pi, and Goose.
Install it with uv, then run machinist rehearse to try the whole loop with a fake agent, for free.
Your agent does the typing. You make the two calls that matter. Start at agentmachinist.com.
Works with
claudecodexopencodepigooseAgentMachinist runs your agent's CLI under the login you already have. GitHub and GitLab are optional. Import an issue as a Task, or publish the reviewed result as a pull request or merge request.
Trust
Your agent edits files in an isolated Workshop, and AgentMachinist commits the result. Git checks after each run catch ordinary violations, such as an agent making its own commits.
Only the build step should change files. For OpenCode and Goose, read-only is advisory, so AgentMachinist's Git checks are the backstop.
Integration is a local fast-forward that you run yourself. Merging a pull request stays a human action on GitHub or GitLab.
You don't need a server or a forge. Your agent may still send code to a cloud model, so offline work needs a local model provider.
AgentMachinist is built for repositories and agents you already trust. Its checks detect violations after the fact, and they can't undo a side effect outside Git.
Get started
You need macOS or Linux, Python 3.12 to 3.14, Git, and uv. The rehearsal uses a fake agent, so you see every step before you spend anything.
Install AgentMachinist. If you don't have uv yet, install uv first.
uv tool install agentmachinistRun the whole loop with a fake agent, at no model cost.
machinist rehearseA real Task needs a clean, named Git branch and a coding agent you're logged in to. It runs that agent under your login, so it uses your plan or API credits like any other session.
Check Git, your agent login, and test command availability. This readiness check does not run your tests.
machinist doctor --localIn your own repository, name one small change and pass your project's own test command. It must prepare dependencies in a fresh checkout.
machinist start "<one small change>" --test-cmd "<your test command>"