# Foreman

> Foreman (npm: foreman-agent) is a free, open-source (MIT), local-first tool for people who run AI agents. It does two jobs. It guards them: every tool call from Claude Code, Codex, Hermes, OpenClaw, ZeroClaw or any MCP agent goes through policy.yaml, risk rules, human approval when it matters (terminal UI, Telegram, Slack or Discord) and a local SQLite audit log, before it runs; it fails closed. And it runs them like a company: an org chart of departments and roles, reporting lines, delegation rules, per-role permissions, team channels, budgets and reports. Current release: 2.3.0 (2026-09-30).

Facts:

- Package: `foreman-agent` on npm; command: `foreman`. Requires Node.js 22.12+ (a standalone binary with Node built in is also published). MIT license. Free. Author: Fatih Tuzlu. Source: https://github.com/tuzlu07x/foreman
- Platforms: macOS and Linux (x64, arm64); Windows through WSL2 only.
- Install: `curl -fsSL https://raw.githubusercontent.com/tuzlu07x/foreman/main/install.sh | bash`, or `npm install -g foreman-agent`, or `brew tap tuzlu07x/foreman && brew trust --formula tuzlu07x/foreman/foreman-agent && brew install foreman-agent`. Check with `foreman --version` and `foreman doctor`.
- First run: `foreman init`, `foreman setup` (wizard: LLM providers with API key or subscription, Foreman's own model or none, agents and Claude Code's hook, chat apps, integrations, and your team of roles), `foreman service install` (the whole gateway at every login, so approvals reach your chat with no terminal open), `foreman start` (the terminal UI; attaches to the service). `foreman demo` shows it in a sandbox with no keys.
- Claude Code: `foreman agent add claude-code` (MCP entry + identity token) and `foreman agent hook install claude-code` (PreToolUse hook that checks Bash, Write, Edit, Read, WebFetch… before they run; `--project` for one project). Since 2.3.0 the hook blocks the call if it can't run; re-run `hook install` once after upgrading.
- Approvals from your phone: one Telegram bot carries approvals, alerts and `/foreman` commands; two-way Slack (Socket Mode) and Discord (Gateway) add Allow / Deny buttons. Plain messages to the bot are read-only questions (`report me`). A call nobody answers is denied.
- Company of agents (Foreman Org): `foreman org init --template startup|software-team|solo` writes org.yaml. Delegation follows the chart (manager to report, report to manager, same department, other departments through their heads). Role library: `foreman org roles`, `foreman org add-role <id> --preset researcher|developer|code-reviewer|manager|writer|analyst|support|assistant`, or your own role with `--describe "…"` and `--runs-on claude-code|codex`. Per-role permissions: `--can read,write,shell,network` (org.yaml `can:`), checked before policy.yaml. Several roles on one agent: `foreman agent add backend --type codex` adds another Codex instance with its own identity, role and audit trail. Reports: `foreman org report`, `/foreman report` from chat. Budgets: `foreman org budget <department> <usd>`.
- Optional LLM features (a second check of risky calls, summaries, narrated reports): Anthropic, OpenAI, Google Gemini, Ollama (local or remote) or any OpenAI-compatible endpoint. Decisions never need an LLM; an LLM verdict can only make Foreman stricter.
- Who it is for: developers and small teams running one or more AI coding or assistant agents who want one policy, human approval, an audit trail and a clear structure across all of them, without a cloud service.
- Not: a tracing dashboard, a cloud service, or a rollback tool. It decides before a call runs and does not undo calls you approved. No account, no telemetry.

## Docs

- [Home and FAQ](https://foreman-agent.com/): what Foreman does, guarding and running a company of agents, comparison, answers to common questions
- [Quick Start](https://foreman-agent.com/quickstart): the full guide in 13 numbered steps, from install to approvals on your phone to an org chart with roles, permissions, budgets and reports
- [Install](https://foreman-agent.com/install): install script (and exactly what it does), Homebrew, npm, standalone binary, WSL2, verify, upgrade, uninstall
- [CLI Reference](https://foreman-agent.com/cli): the main commands and flags, grouped
- [Changelog](https://foreman-agent.com/changelog): 2.3.0, 2.2.0, 2.1.1, 2.1.0 and 2.0.0 summarised, with links to the full notes

## Source documentation

- [README](https://github.com/tuzlu07x/foreman#readme): overview, install, quick start, supported integrations
- [CHANGELOG.md](https://github.com/tuzlu07x/foreman/blob/main/CHANGELOG.md): full release notes
- [Foreman Org](https://github.com/tuzlu07x/foreman/blob/main/docs/org.md): org.yaml, delegation rules, several roles on one agent, channels, escalation, spend, budgets
- [Policy reference](https://github.com/tuzlu07x/foreman/blob/main/docs/policy.md): policy.yaml rules, precedence, risk buckets
- [Detection](https://github.com/tuzlu07x/foreman/blob/main/docs/detection.md): risk rules and scoring (secrets, shell, network, prompt injection, loops)
- [Notifications](https://github.com/tuzlu07x/foreman/blob/main/docs/notifications.md): Telegram (one bot), Slack and Discord two-way, email, ntfy, webhook
- [MCP Hub](https://github.com/tuzlu07x/foreman/blob/main/docs/mcp-hub.md): mcp.yaml, access lists, tool pinning, OAuth servers, the local daemon, the background service (`foreman service`)
- [Agent lifecycle](https://github.com/tuzlu07x/foreman/blob/main/docs/agent-lifecycle.md): adding, wiring, identity tokens, removing agents
- [LLM providers](https://github.com/tuzlu07x/foreman/blob/main/docs/llm-providers.md): Foreman's own model on Anthropic, OpenAI, Gemini, Ollama or an OpenAI-compatible endpoint
- [Integrations](https://github.com/tuzlu07x/foreman/blob/main/docs/integrations.md): GitHub, GitLab, Jira & Confluence, Trello, Linear, Notion
- [TUI](https://github.com/tuzlu07x/foreman/blob/main/docs/tui.md): approval queue, console, inbox, how approvals time out
- [SECURITY.md](https://github.com/tuzlu07x/foreman/blob/main/SECURITY.md): threat model, known limits, reporting

## Optional

- [llms-full.txt](https://foreman-agent.com/llms-full.txt): the long version, with the full guide, commands, capabilities, comparison and FAQ in one file
- [npm package](https://www.npmjs.com/package/foreman-agent)
- [GitHub Releases](https://github.com/tuzlu07x/foreman/releases): tagged releases and standalone binaries with SHA256SUMS
- [Community](https://foreman-agent.com/community): Discord, Telegram, Reddit, contributing