Foreman is an agentic orchestrator TUI that supervises headless Claude Code agents through a gated software-delivery pipeline, designed for any repository. It addresses the challenge of making AI-driven development trustworthy and manageable by providing a human-in-the-loop interface for design phases and automated, guarded autonomy for builds, ensuring recoverability and reliability. This tool is beneficial for engineers, researchers, and power users seeking to integrate AI agents into their software development workflows.

How It Works

Foreman orchestrates local Claude CLI agents via stream-json mode, parsing their events to enforce budgets and drive a structured pipeline: plan → ADR/PRD → issues → TDD build → e2e. It features human review gates for design stages and guardrailed autonomy for builds. State is managed via human-readable files committed to the target repository, enabling crash-safe recovery without a database. Workers operate in isolated git worktrees, with their resource footprint managed by declared touches sets.

Quick Start & Requirements

• Install: pipx install . or uv tool install .
• Prerequisites: Python 3.11+, claude CLI installed and authenticated, Git, Linux/WSL2 (recommended).
• Demo: Run foreman --demo for a full pipeline simulation with a mocked agent backend, consuming zero tokens.
• Links: The README serves as the primary documentation.

Highlighted Details

• Gated Pipeline: Enforces a strict plan → ADR/PRD → issues → TDD build → e2e workflow with human review gates on design phases and hash-sealed approvals that auto-revert on document changes.
• Headless Agents & Guardrails: Manages local claude CLI execution, enforcing per-run/daily cost and time budgets. A PreToolUse deny hook prevents workers from writing their own verification.
• Crash-Safe State Management: All project state is stored in human-readable files within the repository (e.g., .foreman/, .claude/skills/), eliminating database dependencies and ensuring full recovery upon restart.
• Keyboard-Driven TUI: A Textual-based terminal user interface allows for comprehensive control over the entire workflow.
• Worktree Isolation: Parallel workers execute within isolated git worktrees, with resource contention managed by declared touches sets.
• Evals Flywheel: Tracks run outcomes to cluster recurring failures, generating skill/prompt patch proposals that require foreman bench validation before integration.

Maintenance & Community

Development is open at n1arash/foreman. Phases 1 (gated pipeline, TUI) and 2 (evals flywheel) are complete, with Phase 3 (hardening) planned. No specific community links (Discord/Slack) or notable sponsorships are mentioned.

Licensing & Compatibility

The project is licensed under the MIT license. It is developed and tested primarily on Linux/WSL2, with compatibility expected wherever the claude CLI, git, and Python 3.11+ are available.

Limitations & Caveats

The system is primarily developed and tested on Linux/WSL2; broader OS compatibility is not guaranteed. While core features are complete, planned hardening in Phase 3 suggests ongoing development. Foreman enforces all gates itself, never trusting agent self-reports.