machinist

Machinist is an open-source software factory implementation. It runs on your machine, keeps repository access and credentials local, and records the work from request to handoff. Commands can invoke Codex, Claude Code, another agent CLI, a test runner, a shell script, or repository-owned orchestration.

Please note: this is early access software and subject to change.

Why Machinist

• One controlled entrypoint. Workers expose named commands and repositories, never arbitrary shell text or machine-local paths.
• Bring your own harness. Use any executable that accepts a prompt on standard input.
• Keep authority local. Repositories, credentials, model aliases, and executor configuration stay on the worker.
• Inspect every run. Stream output, retain durable events and artifacts, and track terminal outcomes, duration, and reported token use.
• Choose where to approve. Pause before a step, review its files, and approve or request changes. Optional merge policies can automate narrowly defined low-risk changes.

Quick start

Build and initialize Machinist:

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

init writes ~/.machinist/config.toml with two commands, task-to-pr and audit. Each is a prompt, an executor, and a timeout:

# ~/.machinist/config.toml
[commands.task-to-pr]
executor = "codex"
prompt_file = "prompts/task-to-pr.md" # optional
timeout = "120m"

Run it directly:

./bin/machinist run --command=task-to-pr --repo=/path/to/repo --prompt="Complete https://github.com/owner/repo/issues/42"

How execution works

For a direct run, Machinist maps the configured command name to a fixed executable and uses the path supplied with --repo as the working directory. Managed submissions instead resolve an approved repository name from the worker configuration. In both cases, Machinist renders the prompt, sends it on standard input, streams stdout and stderr, and applies one overall timeout and cancellation. Exit code 0 succeeds; every non-zero exit code fails.

Inside each command, scripts are intentionally opaque. Their internal stages appear in logs, but Machinist does not infer their internal stages. A killed script restarts from the beginning unless the script owns checkpointing.

For explicit steps, configure a workflow:

[workflows.deliver]
steps = ["task-to-pr"]

Workflow tasks retain results and saved files, support approval and feedback, and keep earlier attempts in history. Each stage can read and write {{task.output_dir}}; Machinist restores and saves the shared folder between stages.

Start with your first task workflow: create a task from an issue or spec, follow it on the board, and review the result. The classify-then-merge example adds independent risk assessment and a conservative merge policy.

Go deeper

Contributing

Read CONTRIBUTING.md for development setup and pull-request expectations. Security issues should follow SECURITY.md.

Machinist is released under the MIT License.