Model-agnostic agentic coding runtime with TUI control plane.
Foreman orchestrates AI agents to execute software engineering tasks autonomously — bug fixes, feature implementations, refactoring, code reviews, and more. It supports multiple LLM providers, enforces safety policies, learns from past sessions, and integrates with GitHub, Linear, and Slack.
# Install
npm install && npm run build
# Run a task
foreman "Fix the login bug in src/auth.ts"
# Force a specific model
foreman --task "Add dark mode" --model architect
# Watch for GitHub/Linear/Slack tasks
foreman --watch
# Autopilot: scan codebase and auto-fix issues
foreman --autopilot-once --no-tui
# Claude Code sidecar (policy + learning via hooks)
foreman --hooks-setup && foreman --hooks --api
# Auto-decompose complex tasks into parallel subtask DAGs
foreman --decompose "Implement full authentication with JWT and OAuth"Requirements: Node.js >= 20.0.0
┌──────────────────────────────────────────────────────────────────┐
│ CLI / TUI │
│ foreman "Fix bug" │ --watch │ --autopilot │ --hooks │ --api │
└──────────────┬───────────────────────────────────────────────────┘
│
┌──────────────▼───────────────────────────────────────────────────┐
│ Orchestrator │
│ Task queue │ Session mgmt │ Learning │ Decomposition │
├──────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌──────────────┐ ┌──────────────────────┐ │
│ │ Model Router │ │ Policy Engine │ │ Task Decomposer │ │
│ │ capability │ │ protected │ │ DAG → parallel │ │
│ │ cost │ │ blocked │ │ batches │ │
│ │ speed │ │ diff limits │ └──────────────────────┘ │
│ └──────┬──────┘ └──────────────┘ │
│ │ │
│ ┌──────▼──────────────────────────────────────────────────┐ │
│ │ Agent Runtime │ │
│ │ AgentLoop (built-in) │ ClaudeCode CLI │ MultiAgent DAG │ │
│ │ Context Manager │ Recovery Manager │ SubAgent Spawner │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ Providers: Anthropic │ OpenAI │ Ollama (local) │ Custom │ │
│ └───────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────┐ ┌──────────┐ ┌────────┐ ┌──────────┐ ┌────────┐ │
│ │ EventBus │ │ Learning │ │ Skills │ │ Autopilot│ │ Hooks │ │
│ └──────────┘ └──────────┘ └────────┘ └──────────┘ └────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ Integrations: GitHub │ Linear │ Slack │ HTTP API │ WS │ │
│ └───────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────┘
| Feature | Description |
|---|---|
| Multi-Provider | Anthropic, OpenAI, Ollama — swap models without changing code |
| Smart Routing | Routes tasks to the right model by complexity, cost, or speed |
| Agent Runtime | Multi-turn tool-calling loop with context management and recovery |
| Policy Engine | Protected paths, blocked commands, diff limits, approval workflows |
| Sandboxes | Docker, local, or cloud (Fly.io, Daytona) isolation |
| Integrations | Watch GitHub Issues, Linear tickets, Slack messages for tasks |
| Autopilot | 8 codebase scanners with auto-ticketing and auto-remediation |
| Learning | Cross-session knowledge, AGENTS.md conventions, skills registry |
| Claude Code Hooks | Run as a sidecar for policy enforcement and telemetry |
| Task Decomposition | Break complex tasks into parallel subtask DAGs |
| HTTP API + WebSocket | Full REST API with real-time event streaming |
| Event System | Typed event bus connecting all components |
[models.coder]
provider = "anthropic"
model = "claude-sonnet-4-5-20250929"
role = "code generation"
max_tokens = 4096Or just run foreman "task" with no config — sensible defaults are used automatically.
Full documentation is in docs/:
| Page | Description |
|---|---|
| Getting Started | Installation, first run, basic usage |
| Configuration | Complete foreman.toml reference |
| CLI Reference | All flags, examples, exit codes |
| Architecture | System design, component map, data flow diagrams |
| Model Providers | Anthropic, OpenAI, Ollama, custom providers |
| Model Routing | Routing strategies, complexity scoring, budget caps |
| Agent Runtime | Execution loop, context management, recovery, caching |
| Tools | All 17 agent tools with full schemas |
| Policy Engine | Safety rules, protected paths, approval workflows |
| Sandbox | Docker, local, and cloud isolation |
| Integrations | GitHub, Linear, Slack watchers and clients |
| Autopilot | 8 scanners, scheduling, auto-remediation |
| Learning System | KnowledgeStore, AGENTS.md, skills registry |
| HTTP API | REST endpoints, WebSocket, Prometheus metrics |
| Claude Code Hooks | Sidecar mode, hook protocol, setup |
| Orchestration | Task decomposition, DAGs, parallel execution |
| Event System | Typed event bus, all event types |
| Programmatic Usage | Using Foreman as a library |
| Development Guide | Project structure, testing, contributing |
npx vitest run # 374 tests, 22 suites
npx vitest # Watch mode
npx vitest run --coverageMIT