Machinist: a local software factory for coding-agent CLIs

The gap Machinist fills between an agent CLI and a repeatable job

Running a coding agent by hand is a one-off. You open a terminal, type a prompt, watch it scroll, and lose the record when the window closes. Machinist targets the point where that stops being acceptable: when the same prompt needs to run against the same repository on a schedule, or when several people need to trigger the same agent workflow without each of them holding repository credentials on their own laptop. The README describes it as an open source software factory for repeatable and scalable AI coding workflows, and the design choices back that framing. Workers expose named commands and repositories rather than arbitrary shell text or machine-local paths, so a caller picks a name, not a command line. The stated audience is teams already using agentic coders who want the work recorded from request to handoff, and who want the human gate kept: Machinist hands back a pull request and does not decide what ships. It is written in Go, MIT licensed, and the README labels it early access software subject to change.

Named commands, approved repositories, and one fixed executable

The mechanism is narrower than the phrase software factory suggests, and that is the interesting part. A command in the configuration maps a name to an executor, an optional prompt file, and a timeout. When you run it directly, Machinist resolves that name to a fixed executable and uses the path you passed with --repo as the working directory. When a submission is managed instead, it resolves an approved repository name from the worker configuration rather than accepting a path from the caller. Either way the sequence is the same: render the prompt, send it on standard input, stream stdout and stderr, and apply one overall timeout and cancellation. Success is exit code 0; every non-zero exit code is a failure. That is the whole contract. There is no intermediate state machine to reason about, which also means there is no place for Machinist to hide behaviour you did not configure.

Where the authority sits, and why that constrains the caller

Machinist keeps repository access, credentials, model aliases, and executor configuration on the worker. A caller submits a command name and an approved repository name. It never supplies a shell string or a machine-local path. This is the security boundary, and it is also the main source of friction: anything you want to run has to be declared in the worker configuration first, by someone with access to that file. The README frames the same property as bring your own harness, meaning any executable that accepts a prompt on standard input can sit behind a command. A test runner, a shell script, or repository-owned orchestration all qualify on the same terms as Codex and Claude Code. The trade-off is explicit. You get a controlled entrypoint and local authority; you give up the ability to fire an ad hoc command at a repository that was never registered.

Getting it running: build, init, config, run

The quick start is four steps. Clone the repository, build the binary into ./bin, and initialize: git clone https://github.com/owainlewis/machinist.git, then cd machinist, mkdir -p ./bin && go build -o ./bin/machinist ./cmd/machinist, then ./bin/machinist init. Configuration lives at ~/.machinist/config.toml. The README gives this example for an approved command: a [commands.foreman] table with executor = "codex", an optional prompt_file = "prompts/foreman.md", and timeout = "45m". A direct run then looks like ./bin/machinist run --command=foreman --repo=/path/to/repo --prompt="Implement issue 42". Note that the prompt is supplied at invocation time while the prompt file is optional configuration, so the two can coexist and the precedence is not spelled out in the material available here; check docs/configuration.md before relying on one overriding the other. The timeout is a single overall budget for the run, not a per-stage limit, which matters once you point a command at a long agent session.

Scripts are opaque, and that is a deliberate limitation

This is the sentence in the README worth reading twice: scripts are intentionally opaque, and Machinist does not invent child runs, graphs, checkpoints, or resumable stages. Internal stages of a script appear in logs, but the tool does not promote them into first-class objects. The consequence is blunt. A killed script restarts from the beginning unless the script itself owns checkpointing. If your workflow is a multi-hour pipeline with a costly middle stage, Machinist will not save you from paying for that stage twice. If you need resumable DAG execution with per-node retry, this is the wrong tool and no amount of configuration will change it. The repository-owned workflow examples under examples/workflows/ are where multi-step orchestration is meant to live, which pushes the checkpointing responsibility into the scripts you write rather than into Machinist. That is a defensible boundary, but it should be a decision you make knowingly rather than discover at the first timeout.

Observability: what you actually get to inspect

The README lists streamed output, durable events and artifacts, and tracking of terminal outcomes, duration, and reported token use. The word reported is doing work there: token figures come from whatever the executor reports, so they are only as accurate as the harness behind the command. Duration and exit status, by contrast, are observed directly by Machinist because it owns the process. For a direct run the working directory is the --repo path you supplied; for a managed submission it is the approved repository resolved from worker configuration. That distinction determines where artifacts land and which repository a run is attributed to, so it is worth confirming in docs/configuration.md before mixing direct and managed runs in the same environment. What the material does not describe is retention policy, storage location, or rotation for those durable events, so treat long-term retention as unverified.

How this differs from running agents through CI

The obvious alternative is a general CI system such as GitHub Actions, where a workflow file in the repository triggers a job on a runner and the agent CLI is just another step. The difference in approach is about where authority lives. In CI, the trigger comes from the repository and the runner is typically ephemeral and hosted, with credentials injected as secrets at run time. In Machinist, the trigger comes from a caller naming a command, and the repositories, credentials, model aliases, and executor configuration stay on the worker. CI gives you a mature ecosystem of triggers, matrices, caching, and artifact storage; Machinist gives you a much smaller surface where the set of runnable things is enumerated in one config file on a machine you control, and the human gate is a pull request rather than a merge button. If your agents already run fine as CI steps and you trust the runner, Machinist adds a second control plane for little gain. If the blocker is that credentials or model aliases must not leave your hardware, the CI comparison stops being close.

Release cadence, licence, and what to verify before adopting

Three releases are listed: v0.2.0 and v0.3.0 in late August 2026, then v0.4.0 on 31 August 2026, with the last push to main on 9 September 2026. That is a tight window and a 0.x version line, which is consistent with the README's own early access warning. Plan for configuration churn between minor versions and read the release notes before upgrading rather than assuming config compatibility. The licence is MIT, which permits commercial use and modification provided the copyright notice and permission notice are retained; this is a description of the licence text, not legal advice, and if you redistribute Machinist inside a product you should have your own counsel read the LICENSE file. On cost, the material supports two observations. Upgrades are cheap in the sense that there is no server component described beyond the control plane and worker in docs/vm-deployment.md, and expensive in the sense that an opaque script restarting from zero after a timeout burns whatever your executor charges per run. Verify your executor's stdin behaviour first, since that is the single requirement every command depends on.

Editorial conclusion

Adopt Machinist if you already run Codex or Claude Code by hand and want a single controlled entrypoint that keeps credentials on the worker and hands back a pull request. Skip it if you need resumable multi-stage pipelines, because the README states Machinist does not invent child runs, graphs or checkpoints, and a killed script restarts from the beginning unless the script owns checkpointing. Before committing, verify three things: that your executor accepts a prompt on standard input, that the timeout you set in ~/.machinist/config.toml matches how long your longest agent run actually takes, and that the repository-owned workflow examples under examples/workflows/ match the orchestration you intend to run.

Official sources

1. License: MIT
2. owainlewis/machinist on GitHub
3. Project website
4. README
5. Releases