What is Mecha

Mecha is a workflow engine that runs LLM agents inside Docker containers, managed by a single Go binary.

The Problem

You want multiple AI agents — a code reviewer, a bug triager, a doc writer — each with its own model, tools, and permissions. Without mecha, you manage each one manually: start containers, inject tokens, check health, clean up.

The Solution

Mecha gives you a YAML-driven lifecycle for LLM workers:

mecha worker add workers/reviewer.yml    # define it
mecha worker start reviewer              # run it (Docker container)
curl http://localhost:32768/task          # use it
mecha worker stop reviewer               # stop it

One binary. One YAML per worker. Docker handles isolation.

How It Works

Each worker is a Docker container running the Claude Agent SDK, with Codex available as an MCP tool. Mecha creates the container, mounts credentials, waits for health, and tracks state. You interact with workers via HTTP.

Current Status

Mecha is under active development. Worker, Task, and Event nouns are implemented.

Component	Status
Worker lifecycle (add/remove/start/stop/ls)	✅ Implemented
Docker container management	✅ Implemented
Secrets management	✅ Implemented
Health checks	✅ Implemented
mecha serve HTTP server	✅ Implemented
Task dispatch (create/dispatch/complete/fail)	✅ Implemented
GitHub webhooks (event → task)	✅ Implemented
GitHub write-back (comments, status, labels, commit suggestions)	✅ Implemented
Policy filtering (result write-back control)	✅ Implemented
GitLab + generic webhook sources	✅ Implemented
Disposable (one-shot) containers	✅ Implemented
Adapter workers (Ollama, OpenAI-compatible)	✅ Implemented

Five Nouns

The full system is built on five concepts:

• Event — something happened (webhook, schedule, API call)
• Worker — takes a prompt, returns a result (Docker container, adapter, or external endpoint)
• Task — an event matched to a worker
• Policy — what a result is allowed to contain
• Log — structured pipeline observations (every event, match, dispatch, write-back) exposed via GET /logs. Log observes the other four nouns but never mutates them.

Pipeline

All four nouns and the full pipeline are implemented. Events arrive via webhooks, match to workers, create tasks, get dispatched, pass through policy filtering, and complete with write-back to GitHub.