The Problem

Teams adopting agentic coding tools (Codex, Claude Code) hit three problems quickly: prompts and workflows are ad-hoc and unrepeatable, each agent holds its own credentials and repository access, and there's no audit trail connecting a request to a merged PR. Machinist addresses this by giving agentic workflows a controlled entrypoint, a durable event log, and a human gate before anything ships.

What This Does

Machinist is a Go control plane plus managed workers that run agent CLIs as named, approved commands. The CLI entry point is cmd/machinist/main.go, backed by internal/cli/ and internal/config/config.go, which loads ~/.machinist/config.toml. The control plane HTTP server lives in internal/controlplane/server.go with a React web UI under internal/controlplane/web/. Workers execute jobs through internal/managedworker/worker.go and client.go; internal/runner/runner.go spawns the actual agent executables, streaming stdout/stderr and applying a single timeout. Scheduled work is handled by internal/triggers/cron.go.

The project ships example workflows in examples/workflows/ — code-audit, issue-to-pr, multi-review, and a flow example — plus a GitHub Actions intake example and skills/machinist/SKILL.md for agent tooling.

How It Is Wired

The repo's internal call graph was not mapped in this analysis, so the wiring below is traced from entry points and file responsibilities rather than a confirmed module graph.

Execution starts at cmd/machinist/main.go. For a direct run, the CLI resolves a named command from config, uses --repo as the working directory, renders the prompt, and sends it on stdin to the configured executable. internal/runner/runner.go owns process spawning, streaming, timeout, and exit-code handling — the widest blast radius, since every command, direct or managed, routes through it. The managed path adds internal/controlplane/server.go as the HTTP API, internal/managedworker/ for worker registration and job submission, and internal/protocol/protocol.go for wire types. internal/triggers/cron.go schedules jobs on a timer. The control plane persists run events and artifacts via internal/controlplane/store.go; the web UI reads that state through the server's API.

The README is explicit that scripts are opaque: Machinist does not model child runs, checkpoints, or resumable stages — a killed script restarts from the beginning. That is a deliberate simplicity trade-off.

How To Use It

From the README, verbatim:

git clone https://github.com/moses-y/machinist.git
cd machinist
mkdir -p ./bin && go build -o ./bin/machinist ./cmd/machinist
./bin/machinist init

Configure an approved command in ~/.machinist/config.toml:

[commands.foreman]
executor = "codex"
prompt_file = "prompts/foreman.md" # optional
timeout = "45m"

Run it directly:

./bin/machinist run --command=foreman --repo=/path/to/repo --prompt="Implement issue 42"

Deployment options include systemd units in deploy/systemd/ and a VM setup script at scripts/setup-vm.sh.

Real-World Use

A team wants a nightly code audit on a shared repository. They configure a cron trigger, point it at the code-audit workflow in examples/workflows/code-audit/, and the worker runs the audit prompt against the configured agent CLI. The control plane records the run; the result comes back as a PR for a human to review and merge. The GitHub Actions example (examples/github-actions/machinist-comment-intake.yml) shows comment-driven intake as an alternative trigger.

Code Health & Issues

No measured analysis block was provided, so findings are structural observations.

  • Low — Built frontend assets are committed under internal/controlplane/web/dist/; acceptable for static hosting but adds noise to diffs.
  • Low — Repo is a fork (0 stars vs. 353 upstream) and README labels it early access; expect API churn.
  • Positive — 30 test files including an integration test (internal/controlplane/github_cli_integration_test.go), CI on GitHub Actions, dependabot, MIT license, and security policy are all present.

The Bottom Line

Machinist is a well-scoped answer to a real problem: making agentic coding workflows repeatable, auditable, and human-gated without centralizing credentials. The Go codebase is clean and test-covered, and the "scripts are opaque" stance keeps the execution model honest. Teams already invested in Codex or Claude Code should evaluate this; anyone expecting orchestration with checkpoints and resumability should not.