Repolode
Submit
thruwire

thruwire/foreman

A Python supervisor that watches coding agents like Codex and OpenCode with decision models, assessing completion, test sufficiency and stuck workers.

View on GitHubWebsite
Stars
812
Forks
69
Open issues
10
Last commit
23 days ago

What is it?

Foreman is a supervisor for AI coding agents. You give it a ticket, specification, or bug report, and it runs a worker such as Codex, OpenCode, Hermes, or LangChain's Deep Agents CLI. While the worker runs, Foreman periodically sends bounded evidence (job text, git status and diff, output tails, test results, and repository AGENTS.md instructions) to a decision model. The model returns probabilities for checks such as implementation completeness, requirements satisfaction, verification needs, and whether the worker is stuck or off track.

A deterministic Python policy turns those scores into actions: continue, steer the worker mid-turn (Codex App Server only), stop, retry, start a verifier, finish, or escalate to a human. Responsibilities are defined in TOML files with configurable thresholds, and custom checks can be added. Decision models can come from TypeSafe's Jev (the default) or OpenAI's Decisions API.

Foreman also supports attaching supervision to interactive sessions through hooks for Codex, Deep Agents, and Pi. A deterministic demo runs without API keys, and run state is stored locally under each repository's .foreman directory.

Key features

  • 01Runs Codex, OpenCode, Hermes, or Deep Agents as coding workers.
  • 02Assesses completion, requirements, test sufficiency, and worker health independently of the worker.
  • 03Can steer an active Codex turn or stop and retry a stuck worker.
  • 04Supports Jev and OpenAI decision model adapters.
  • 05Configurable responsibilities, thresholds, and external evidence commands in TOML.

Use cases

  • Keeping an unattended coding agent from looping or drifting off the ticket.
  • Adding an independent completion and test-coverage check before accepting agent output.
  • Supervising an interactive Codex or Pi session started by a developer.
  • Experimenting with semantic supervision of coding agents using custom checks.

Quick start

  1. 1

    Set the TYPESAFE_API_KEY environment variable for the default Jev decision model

  2. 2

    Run Foreman with the OpenCode worker backend on a project with a job description

    FOREMAN_WORKER_BACKEND=opencode foreman run --repo ./my-project --job "Add request retries"

Things to know

  • Foreman currently runs only one coding worker at a time.
  • Live steering into an active turn works only with the Codex App Server backend; other backends fall back to stop and retry.
  • The default decision model setup requires a TYPESAFE_API_KEY.

In collections

Open-source AI agent frameworks & appsAI coding assistants & agents

Topics

#ai-agents#coding-agent#llm#agent-supervision#code-review#automation#python#codex#jev#opencode

FAQ

What is foreman?
A Python supervisor that watches coding agents like Codex and OpenCode with decision models, assessing completion, test sufficiency and stuck workers. Foreman is a supervisor for AI coding agents. You give it a ticket, specification, or bug report, and it runs a worker such as Codex, OpenCode, Hermes, or LangChain's Deep Agents CLI. While the worker runs, Foreman periodically sends bounded evidence (job text, git status and diff, output tails, test results, and repository AGENTS.md instructions) to a decision model. The model returns probabilities for checks such as implementation completeness, requirements satisfaction, verification needs, and whether the worker is stuck or off track.
Is foreman free to use? What license does it have?
foreman is open source under the MIT license. Check the license terms before using it in commercial products.
Is foreman still maintained?
Actively maintained. The last commit to foreman was on Oct 15, 2026.
What can I use foreman for?
Keeping an unattended coding agent from looping or drifting off the ticket. Adding an independent completion and test-coverage check before accepting agent output. Supervising an interactive Codex or Pi session started by a developer. Experimenting with semantic supervision of coding agents using custom checks.
How do I install foreman?
Set the TYPESAFE_API_KEY environment variable for the default Jev decision model Run Foreman with the OpenCode worker backend on a project with a job description: FOREMAN_WORKER_BACKEND=opencode foreman run --repo ./my-project --job "Add request retries"
Where can I get foreman?
The source code and installation instructions are on GitHub: https://github.com/thruwire/foreman

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects