machine

machine lets you define a coding-agent workflow as a JSON state machine, which an agent then runs by calling MCP tools. The server validates every call against the machine and rejects any disallowed move, while a local web UI shows the run live. It is published by backnotprop under the FSL-1.1-MIT license and requires Bun 1.3+.

What It Is

machine is a workflow-enforcement server for coding agents. A machine is JSON describing states and the events that move between them. States come in four kinds: task and decision (moved by the agent), wait (moved by a person in the UI), and final. States can declare typed outputs, run inputs, preflight requirements and credential slots.

How a run works

Publishing a machine writes a SKILL.md the agent loads, containing the machine's instructions and exact tool calls, and stores the definition the server enforces. The agent drives the run through MCP tools: preflight, begin, transition, note, fail, get, request and credential. The server rejects and records invalid events, human-only events picked by the agent, missing or mistyped output, unfinished preflight, unbound credentials, and moves on blocked, waiting or finished runs. Accepted transitions and rejections are stored in SQLite, and the UI shows the graph with the current state, a timeline, and inputs and outputs. When a run reaches a wait state, a person picks the event in the UI and a fresh agent session can resume.

Authoring and credentials

Machines can be drawn in a visual editor or described to an agent that drafts the graph. Credential slots are bound by the team to stored credentials such as a GitHub App, npm token, AWS keys or a bearer token. Agents use them without seeing them, via a CLI command that leases the credential into one command's environment or via the server-side request tool. Stored values are encrypted.

Setup path

Local mode runs with bun install, build and a serve command on localhost:7420 with no sign-in. Machines are added and published as skills, and the MCP server is registered with Claude Code. Hosted mode adds WorkOS sign-in, teams and API keys for agents. An evals suite asserts on run history in SQLite.