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: ```sh 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: ```toml # ~/.machinist/config.toml [commands.foreman] executor = "codex" prompt_file = "prompts/foreman.md" # optional timeout = "45m" ``` Run it directly: ```sh ./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](docs/README.md) | Choose the right setup and operations guide | | [Configuration](docs/configuration.md) | Commands, executors, workers, models, and repositories | | [Development](docs/development.md) | Build, test, and work on Machinist locally | | [VM deployment](docs/vm-deployment.md) | Run the control plane and worker as services | | [Workflow examples](examples/workflows/README.md) | Repository-owned multi-step orchestration | ## Contributing Read [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and pull-request expectations. Security issues should follow [SECURITY.md](SECURITY.md). Machinist is released under the [MIT License](LICENSE).