machinist

README

The open source AI software factory for agentic coders.
Machinist is an open source software factory for repeatable and scalable AI coding workflows.

Website · Documentation · Configuration · Workflow examples

_{Machine section · supervised agent system · exploded assembly}

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.
• Keep the human gate. Machinist hands back a pull request. It does not decide what ships.

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

Configure an approved command:

# ~/.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"

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.

Scripts are intentionally opaque. Their internal stages appear in logs, but Machinist does not invent child runs, graphs, checkpoints, or resumable stages. A killed script restarts from the beginning unless the script owns checkpointing.

Go deeper

Guide	What it covers
Documentation	Choose the right setup and operations guide
Configuration	Commands, executors, workers, models, and repositories
Development	Build, test, and work on Machinist locally
VM deployment	Run the control plane and worker as services
Workflow examples	Repository-owned multi-step orchestration

Contributing

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

Machinist is released under the MIT License.