thruwire/foreman

What it solves

Foreman is an architectural experiment designed to solve the problem of supervising slow, stateful coding agents. It introduces a fast decision model (Jev) to act as a supervisor that independently assesses whether a coding agent is making progress, is stuck, or has completed the requirements without requiring the coding agent to stop its work.

How it works

Foreman operates as a native Python asyncio runtime with two concurrent loops: a coding agent loop (where a worker like Codex performs the actual engineering) and a Foreman loop (the supervisor).

While the worker is active, Foreman collects "factory evidence"—including git status, bounded diffs, worker history, and output tails—and sends this compact state to the Jev model. Jev returns probabilistic scores for nine different dimensions (e.g., implementation_complete, worker_stuck, needs_human). A deterministic Python policy then translates these probabilities into actions such as continuing, steering the worker with guidance, stopping a stuck process, or launching an independent verifier.

Who it’s for

Developers and AI researchers interested in agentic software engineering and the concept of "semantic supervision," where a fast, specialized model monitors the rest of the software factory floor.

Highlights

• Concurrent Supervision: The supervisor monitors the worker in real-time without interrupting the worker's reason-tool-observe loop.
• Probabilistic Assessment: Uses Jev to evaluate multiple supervisory questions independently and in parallel.
• Live Steering: Supports sending guidance into an active Codex turn via the App Server protocol.
• Safety-First Policy: Implements a deterministic hierarchy of interventions (e.g., prioritizing human escalation over continued work).
• Deterministic Demo: Includes a simulation mode that allows testing the runtime and policy without requiring API keys or the Codex CLI.