Machinist

Run a local team of coding agents that turns GitHub issues into reviewed pull
requests.

Machinist is an open-source runtime and control plane for supervised coding work.
Give its foreman an issue. It plans the work, dispatches fresh agents to build
and review the change, waits for the repository's checks, and hands you a pull
request to merge.

GitHub issue -> plan -> build -> independent review -> CI -> pull request
                                                            ^
                                                      you decide to merge

Machinist runs on your machine, in your repositories, with the coding tools you
already use. Agent prompts and workflows are files you can read, change, and
version. The control plane records what ran without trying to guess whether an
agent's prose means the job is done.

Why Machinist?

• One request, a complete workflow. The foreman coordinates planning,
  implementation, review, repair, and CI instead of stopping after one coding
  session.
• Review before handoff. A fresh agent reviews the exact change. Failed
  checks and valid findings go back through a bounded repair loop.
• Your tools and models. Machinist launches configured executors such as Codex
  or Claude. Model aliases let you choose per task without hard-coding provider
  details into prompts.
• Local by default. Repository paths, credentials, and executor commands
  stay on the worker. Managed results and event logs are copied only to the
  loopback control plane's local SQLite database.
• A human owns the merge. The shipped foreman can prepare and verify a pull
  request. It never merges one.

Machinist also ships a read-only audit agent that inspects a repository,
independently verifies possible bugs, and opens evidence-backed issues for the
ones it can prove.

Quick start

You need macOS or Linux, Go 1.26.6 or newer, Git, an authenticated
GitHub CLI, and an authenticated
Codex CLI. The default foreman uses
Codex and its native subagents.

1. Build and initialize

From a Machinist source checkout:

mkdir -p ./bin
go build -o ./bin/machinist ./cmd/machinist
./bin/machinist init

machinist init creates editable configuration and agent prompts in
~/.machinist. It keeps existing files unchanged when you run it again.

2. Give the foreman an issue

./bin/machinist run \
  --agent=foreman \
  --repo=/absolute/path/to/your-repository \
  --prompt="Complete https://github.com/your-org/your-repo/issues/123"

Use a small, well-defined issue for the first run. Machinist streams the agent's
output and saves an ordered event log and terminal result under
~/.machinist/worker/runs/.

3. Review the pull request

The foreman leaves the issue and pull request ready for a person to review. It
does not merge.

To inspect a repository without changing it:

./bin/machinist run \
  --agent=audit \
  --repo=/absolute/path/to/your-repository \
  --prompt="Audit the request handling and persistence code"

Run the local control plane

Direct mode is the fastest way to try Machinist. When you want a queue, durable
run history, and a browser UI, add a repository to
~/.machinist/worker.toml:

[repositories.my-project]
path = "/absolute/path/to/my-project"

Then start the server and worker in separate terminals:

./bin/machinist start

./bin/machinist worker start

Open http://127.0.0.1:7331, choose a repository and
agent, and submit a work request.

You can also queue managed work from the CLI. Use the repository name from
worker.toml, not its local path:

./bin/machinist submit \
  --agent=foreman \
  --prompt="Complete https://github.com/your-org/your-repo/issues/123" \
  --repo=my-project

machinist run executes immediately and never contacts the control plane.
machinist submit validates the selection with the control plane, queues it, and
prints the admitted job ID. machinist worker run remains available as the
worker-namespaced direct path for a single agent.

Documentation

• Getting started: requirements, installation, and
  first runs
• How Machinist works: direct runs, managed runs,
  supervision, and artifacts
• Configuration: agents, executors, models, prompts,
  and pipelines
• Local control plane: server, workers, security, and
  failure recovery
• Development: build, test, and project layout
• Migration guide: clean installation,
  renamed interfaces, and rollback
• Architecture: source of truth, dependency direction,
  execution flows, trust boundaries, and persistence
• Control-plane design: the detailed V1 design
  and invariants
• Warp Factories product review:
  lessons, readiness gates, and recommended product order
• Runner-managed skills: why coding-agent skills
  stay native to the configured runner

Project status

Machinist is early software. It currently targets trusted local automation on
macOS and Linux. The control plane intentionally accepts only loopback listeners;
remote deployment needs a separate authentication and TLS boundary.

The opt-in Python eval under evals/ runs the complete default workflow against
a dedicated scratch repository and verifies its issue-label lifecycle. It is separate
from just check because it creates real GitHub issues and pull requests.

License

MIT