# Foreman

> An open-source Python runtime that supervises coding agents such as Codex and OpenCode using TypeSafe's Jev model to decide whether to continue, steer, stop, verify, or finish.

Foreman is an open-source agent supervisor from ThruWire that watches coding workers with TypeSafe AI's Jev decision model. Given a ticket, specification, bug report, or free-form software job, a Codex, OpenCode, or Hermes worker does the engineering while Foreman independently assesses progress. The latest release listed is v0.4.4.

## What It Is

Foreman is a native Python asyncio runtime that runs two concurrent loops: the coding agent's own reason/tool/observe loop and a separate Foreman loop that watches, assesses, decides, and intervenes. It does not replace the worker or choose its individual tools or files. Worker output and lifecycle events flow into a debounced observation loop while the worker subprocess keeps running.

## How Supervision Works

Each observation is compact and bounded. It includes the original job, worker summaries and output tails, git status and a bounded diff, repository AGENTS.md instructions when present, verification results, and recent events. Pluggable responsibilities own Jev yes/no checks, such as implementation_complete, requirements_satisfied, tests_sufficient, needs_verification, worker_stuck, work_off_track, agents_md_drift, and needs_human. All checks are sent to Jev in one parallel request.

Responsibilities propose directives, and a deterministic Python arbiter selects one: continue, start worker, start verifier, steer worker, stop worker, retry worker, finish, or escalate. Thresholds are defined in TOML files per responsibility and can be overridden centrally. Live steering into an active turn is available with the Codex App Server backend; other backends degrade to stop/retry.

## Setup Path

Install with pip as foreman-core, which provides the foreman command. Real runs need Python 3.11 or newer, a TypeSafe API key, and the chosen worker CLI on PATH. A deterministic demo needs no API key or network. Run history is stored locally as state.json and events.jsonl and can be inspected through the CLI. A hook command lets Foreman supervise interactive Codex, Pi, or Pi Durable sessions, with a Codex plugin published through the ThruWire marketplace.

## Tradeoffs to Know

The README states that Jev assessment accuracy is unproven for this use case and scores need calibration, so false positives can stop useful workers and false negatives can let bad work continue. Workers run with local permissions without isolation, and Foreman currently runs one coding worker at a time. The Codex App Server protocol is described as experimental.

## Features
- Continuous semantic supervision of coding agents
- Parallel Jev checks for completion, verification, worker health, AGENTS.md drift, and human escalation
- Deterministic arbiter selecting continue, steer, stop, retry, verify, finish, or escalate
- Live steering of active Codex App Server turns
- Worker backends for Codex, OpenCode, and Hermes
- TOML-defined responsibilities with central overrides
- Pluggable evidence providers including external CLI commands
- Attached-session hooks for Codex, Pi, and Pi Durable
- Local run state and event timeline with inspect commands
- Deterministic offline demo

## Integrations
TypeSafe Jev, Codex, OpenCode, Hermes Agent, Pi, Pi Durable

## Platforms
API, DEVELOPER_SDK, CLI

## Pricing
Open Source

## Version
v0.4.4

## Links
- Website: https://thruwire.ai
- Documentation: https://github.com/thruwire/foreman#documentation
- Repository: https://github.com/thruwire/foreman
- EveryDev.ai: https://www.everydev.ai/tools/foreman