Machinist CLI
A Go server that runs Claude Code or Codex on your machine or Kubernetes and delivers the work as a pull request after review
- 529 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- The agent writes code and opens pull requests as a GitHub App in the repositories you pick
- Agent commands run on your host under your Codex or Claude Code login
- Optional repository maintenance can merge documentation changes without a person
Install
- Works in
Manual install
git clone https://github.com/owainlewis/machinist.git && cd machinist && go build -o ./bin/machinist ./cmd/machinistGo 1.26.6, Git, GitHub CLI and a logged-in agent CLI are required. Then ./bin/machinist init and ./bin/machinist start, followed by connecting the GitHub App in the interface.
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The agent writes code and opens pull requests as a GitHub App in the repositories you pick
- Agent commands run on your host under your Codex or Claude Code login
- Optional repository maintenance can merge documentation changes without a person
This is third-party code. Review the repository files before installing.
What it does
Machinist runs coding agents on infrastructure you control: your own computer, a virtual machine or Kubernetes. A task is plain text or a GitHub issue link, and the result is a pull request, or a direct answer when no file changes were requested. The agent runs through its own CLI, Codex or Claude Code. A Go control plane and a React interface track execution, approvals, review and delivery. The standard pipeline is triage, an optional spec with approval, build and independent review. Findings return to the build on the same pull request, for up to three repair rounds. Single-agent mode carries a task to the end without a separate reviewer. Saved automations run on a cron schedule, and after delivery Machinist watches for failed checks and review comments and repairs them within the same task. The repository ships a machinist skill. It tells a coding agent how to create an issue with `gh issue create` and queue a task through `machinist run` or `machinist submit`. By the skill's rules the agent does not merge the pull request.
Who it is for. Teams and solo developers who hand tasks to agents through GitHub and want reviewed pull requests built on their own servers.
Good fit when
- An issue queue gets worked through overnight: the task goes to an agent and a pull request with review results waits in the morning
- Routine work should run on a schedule: issue and pull request triage, documentation fixes
- Code cannot go to a cloud service, so the agent must work on your own VM or cluster
- Checks failed on the agent's pull request and the repair should happen inside the same task
- A person approves the spec before the build starts
Not a fit when
- A single agent run in a terminal is enough: the server, GitHub App and interface are overkill
- You need a hosted service with no install: Machinist builds from source and runs under your control, with no cloud account
- Work happens outside GitHub: triggers, issues and delivery are built on a GitHub App and `gh`
- You need a provider other than Codex or Claude Code: Kubernetes ships with Codex subscription login only
Example request
Open an issue about the failing login test and queue it in Machinist: I want a pull request with the fix and an independent reviewLimitations
Installation is a source build: Go 1.26.6, Git, GitHub CLI and a logged-in agent CLI on the execution host are required, and publishing goes through a GitHub App you connect. Native-agent mode has no enforced spec approval or separate read-only checkout for review, and child-agent findings are advisory. Kubernetes supports Codex subscription login; other providers are not claimed. One control plane on SQLite owns the state, so a stale laptop copy must not run next to a cloud one.
How to disable. Stop the control plane, delete the built `bin/machinist` file and revoke the GitHub App in your organization settings. The skill goes away with its `skills/machinist` folder in the agent's project. State lives in the private runtime directory: back it up with the SQLite snapshot before deleting.
FAQ
How do I run Machinist locally?
Clone the repository, build with `go build -o ./bin/machinist ./cmd/machinist`, then run `./bin/machinist init` and `./bin/machinist start`. Open the printed address, connect the GitHub App, pick a project and agent and verify the PONG reply.
Do I need a subscription or a Machinist cloud account?
No cloud account is needed. The agent runs through its own CLI, Codex or Claude Code, under your login on the execution host.
What happens when checks fail or a review comment arrives?
Machinist watches delivered pull requests for failed checks, trusted review comments and confirmed merges. Repairs stay in the same task and the same pull request.
Can Machinist merge a pull request itself?
Normally a person decides. Optional repository maintenance merges a narrow class of low-risk documentation changes after independent review and under branch protection. Single-agent runs and unrelated pull requests never qualify.
Where do tasks run?
On the control-plane host, on a VM with its own worker or in Kubernetes, where each attempt is a separate Job under gVisor.
What does the machinist skill do?
It teaches an agent to queue work: create the issue, run `machinist run` or `machinist submit` and report status. The `machinist:requested` label on an issue sends it to the queue when a GitHub trigger is configured.
Discussion
No questions or reviews yet.
Related
CLI toolsOrchestrator for Claude Code, Codex and Gemini CLI: YAML workflows that loop until your own quality gates pass
A self-hosted control plane for running several agents: task dispatch, run review, spend tracking, connected via MCP, CLI or REST
Connects Claude Code, Cursor, Codex or OpenCode to Telegram, Slack and Discord: teammates message a bot, an agent replies
A CLI that loops Claude Code, Codex, OpenCode and other agents over a task list or PRD until everything is done
A CLI that takes tickets from GitHub, Linear or Jira, writes code through Claude Code and opens a pull request for your review
apra-fleet runs a fleet of AI agents across machines and models through MCP and drives multi-hour workflows
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| Machinist (this card) | no | 529 | ||
| Ralph Orchestrator | no | not required | 3,194 | loops different agents until a task is ready, without a GitHub App or pull request review |
| CLI Agent Orchestrator | no | 1,515 | a supervisor hands tasks to specialist agents, with no GitHub delivery |
README in short
The description opens with the idea: agents run on your infrastructure with GitHub as input and output. It continues with a quick start, running a job, automations, a table of execution targets (local, VM, Kubernetes) and a list of guides for configuration, VM, Kubernetes and GKE deployment.