ml-os turns blocked AI agent approvals into a local gate inbox

The hidden queue in agent-assisted development

Autonomous coding agents can keep moving through a task until they reach a decision that needs a person. In the workflow documented by ml-os, those moments are /go gates: an approval of a plan or of code. The practical problem is not creating the gate. It is noticing it.

A gate can sit inside one terminal session while its operator works elsewhere. Multiply that by several projects and the human becomes the delayed component of the system. ml-os, from MuLIAICHI/ml-os, is built as a deliberately narrow answer: a local inbox showing what is waiting now.

The project is aimed at people running agents through ay-framework across more than one repository. Rather than attempting to orchestrate those agents itself, ml-os observes the files their workflow produces. Its promise is operational visibility, not another control plane.

A read-only view of pending gates

The central screen collects pending gates from registered repositories and orders them oldest first. Each entry includes its task title and a live waiting time. The README says stale items are escalated, helping a long-unnoticed approval stand out from one that just appeared.

A gate can represent either a plan approval or a code approval. ml-os also exposes each repository's task board and blockers, plus a trace of a task's plan, handoffs, and landed commits. That gives the operator a route from a single waiting prompt to the surrounding work rather than presenting approval requests as isolated alerts.

The application can notify the user when a gate changes into a pending state. It sends one notification per transition, and clicking that notification opens the inbox. A configured jump action can focus the terminal session that is waiting, with cmux supported out of the box according to the README. This keeps the dashboard from becoming a place where work must be duplicated: it is a way to find the relevant session quickly.

There is a fallback for imperfect workflow data. When a repository lacks a gate marker but a task lock appears stuck, ml-os can show an inferred gate. Importantly, the project labels that result as an inference rather than presenting it as certain. That is a useful interface choice for developer tooling: surface a potentially valuable signal, while preserving the distinction between observed state and a guess.

The filesystem is the integration boundary

ml-os reads gate markers at <repo>/.ay/tracking/gates/*.gate. A marker on disk denotes a /go cycle that is awaiting human input. Its JSON records the gate type and a timestamp; the repository's /go process removes the marker once the user responds.

The rest of the displayed context comes from the same .ay/ directory tree. Boards, blockers, plans, and commit logs are all rendered from those tracking files. In other words, ml-os does not require a special service connection to each watched repository. The filesystem layout is the seam between the viewer and the projects it watches.

That design has two clear consequences documented by the project. First, it makes the viewer structurally read-only with respect to watched repositories. The README states that the code has no write path toward a watched folder. This is more meaningful than a convention asking the application not to edit project state. A dashboard that is intended to inspect workflow status should avoid becoming an unexpected participant in that workflow.

Second, the same boundary supports fixture-based testing. The test suite uses golden .ay/ trees, meaning stored examples of expected tracking data, and injects clocks where waiting-time behavior matters. The README describes the resulting tests as deterministic and independent of live agents. For a tool that interprets files and elapsed time, this is a practical testing pattern: representative directory trees establish parsing and rendering behavior, while a controllable clock keeps time-sensitive assertions stable.

Local-first tradeoffs are explicit

ml-os has no database and no build step. Its documented runtime is Python's standard library plus one HTML file. The repository metadata identifies the project as Python, and the README specifies Python 3.11 or newer. That small footprint fits the project’s role as a local status surface: installation starts with cloning the repository, copying a TOML configuration template, registering repository paths, and running python3 -m mlos.server.

The viewer is not limited to macOS, but notifications are. The README says the viewer runs anywhere Python 3.11+ is available, while notifications require macOS and terminal-notifier, installed with Homebrew. This division is sensible for a local utility: the core status view remains portable, while a platform-specific convenience remains optional.

The security tradeoff is also called out plainly. The server is unauthenticated, and the /api/jump endpoint runs a command configured by the user. As a result, it binds to 127.0.0.1 by default. Binding to 0.0.0.0 is opt-in for checking gates from another device, such as a phone, and the README advises doing so only on a network where every device is trusted. Local-first software still needs an exposure model, and ml-os makes its default conservative.

A small tool for a specific bottleneck

The interesting idea in ml-os is not that it can display agent state. It is that it treats a human approval queue as first-class operational work. When agents proceed autonomously most of the time, the few transitions requiring attention can determine overall throughput. A visible, age-sorted inbox and a direct route back to the waiting terminal address that particular failure mode without taking ownership of the underlying repositories.

For builders using ay-framework's file-based tracking workflow, the project offers a compact example of a read-only companion tool: observe durable local artifacts, derive a useful status view, clearly mark uncertainty, and keep the action that changes state in its original home. Inspect the repository at github.com/MuLIAICHI/ml-os.