Run a whole crew of AI agents. Safely. On your own machine.

Foreman is the security gateway and foreman for Claude Code, Codex, Gemini CLI, Hermes, OpenClaw and any MCP agent. Every tool call is mediated, scored, approved by you when it matters, and audited, and your agents are organised like a company, with departments, reporting lines and least-privilege access.

Website · Install · Quick start · MCP Hub · Foreman Org · Security · Roadmap

Why

People now run several agents side by side: a coding agent in the editor, an assistant on Telegram, a few MCP servers wired into both. Each one can read your files, run commands, spend money and talk to the others. The failure modes are no longer theoretical:

• Prompt injection and tool poisoning. A web page, an email or an MCP tool description tells the agent to send your .env or SSH key somewhere.
• Destructive commands. An rm -rf expanded from an empty variable runs before anyone looks.
• Supply chain. An MCP server or skill silently changes after you trusted it.
• Runaway cost. Dozens of tool definitions sit in every context window, and agents delegate to agents in loops.

Foreman sits in the path of every call and handles all four locally, before anything runs.

What you get

| | | | --- | --- | | 🛡️ Mediate every call | MCP tools, Claude Code's built-in tools (PreToolUse hook), Codex and ACP agents (Gemini CLI, Hermes, OpenClaw, ZeroClaw) all go through one pipeline: policy.yaml, then risk rules, then your approval, then an audit log. It fails closed: if Foreman can't decide, the call doesn't run. | | 🧰 MCP Hub | foreman mcp add github once, and every agent gets it, mediated. There is a curated catalog of 19 servers (GitHub, filesystem, Playwright, Notion, Stripe, Sentry, Brave, Exa, Discord, X, YouTube, App Store / Google Play, …). Secrets stay in Foreman's encrypted store, never in agent configs. | | 🧪 Tool-poisoning & rug-pull defence | Tool descriptions are scanned for hidden instructions. Definitions are pinned on first use, and a tool that changes later is withheld until you trust it again. Results are redacted for secrets and flagged for injected instructions. | | 🏢 Foreman Org | foreman org init --template startup sets up a CEO, CTO, CMO, CFO and teams, each role filled by the agent you choose. Delegation follows reporting lines, and each department sees only the tools it needs. | | 🖥️ A terminal you can run your crew from | A live dashboard, a queue for every agent waiting on you, an inbox of everything you missed, and a : console: write codex …, assign marketing …, approve. No chat app required. | | 📱 Approve from anywhere | Decide in the TUI, or with one tap in Telegram, Slack or Discord. Buttons carry HMAC-tagged tokens and reach Foreman over connections only it holds (your Telegram bot, Slack Socket Mode, the Discord Gateway), so no agent can approve for you. One Telegram bot is enough: ask it report me in plain words, or send /foreman status, /foreman write codex … there, in Slack or in Discord. Alerts and digests also go to email and ntfy phone push. | | 💸 Fewer tokens | Lazy tool discovery cut the listing for the official filesystem server from ~2,000 tokens to ~190. Descriptions are clipped, oversized results truncated, and routine roles can run on cheaper models. | | 🔒 Tamper protection | An agent that tries to edit Foreman's database, policy, keys or its own hook/MCP wiring is caught as a critical risk. | | 📝 Local audit | Every decision is stored in SQLite with full-text search. Secrets are masked; files are owner-only. No cloud, no telemetry. |

Install

Needs Node 22.12+ on macOS or Linux (x64 or arm64, glibc or musl); on Windows, use WSL2. See supported platforms. The installer sets up Node 22 LTS through nvm if you don't have it:

curl -fsSL https://raw.githubusercontent.com/tuzlu07x/foreman/main/install.sh | bash

brew tap tuzlu07x/foreman && brew install foreman-agent   # macOS / Linuxbrew
npm install -g foreman-agent                              # Node >= 22.12

| Variable / flag | Effect | | ------------------------ | ---------------------------------------------------------- | | FOREMAN_VERSION=2.4.0 | Pin a specific release | | FOREMAN_INSTALL_PREFIX | Use a non-default npm prefix | | FOREMAN_SKIP_NVM=1 | Refuse the nvm bootstrap path | | --uninstall | Remove the global package (Foreman's data is left in place) |

No Node? Every release has a standalone binary for macOS (darwin-arm64, darwin-x64) and Linux (linux-x64, linux-arm64), with SHA256SUMS. It is one ~130 MB file with Node.js built in:

target=linux-x64   # or linux-arm64, darwin-arm64, darwin-x64
base=https://github.com/tuzlu07x/foreman/releases/latest/download
curl -fsSLO "$base/foreman-$target" && curl -fsSLO "$base/SHA256SUMS"
grep " foreman-$target\$" SHA256SUMS | shasum -a 256 -c -   # or: sha256sum -c -
chmod +x "foreman-$target" && sudo mv "foreman-$target" /usr/local/bin/foreman

See docs/install.md for how it differs from the npm install.

Windows: run Foreman inside WSL2. See docs/windows-wsl2.md.

Quick start

See it first, in a sandbox:

foreman demo

A made-up company of agents (a CEO, a CTO, an engineer, a CMO and a CFO) works through a day while you watch the real TUI. You'll see:

• department messages, and a task handed down the org chart;
• an agent reaching for .env (press a or d);
• a poisoned instruction (pipe a script into bash) caught and turned into an approval request you can deny;
• marketing going over its daily budget;
• the CEO's report landing in your inbox.

The agents are stand-ins with canned answers, and they're the only agent CLIs on the demo's PATH. Everything lives in a throwaway folder with its own FOREMAN_HOME, and no keys are needed. Your real agents, your files and your own Foreman home are never touched.

Then set up your own in about 5 minutes:

foreman quickstart

It connects Claude Code and Telegram, then sends a real approval card to your phone, so you see Foreman stop an agent before you trust it with anything.

For other agents, Slack or Discord, use the full setup:

foreman init            # identity, policy, encrypted secret store, audit DB
foreman start           # guided setup on first run, then the live TUI

Keep foreman start running: it is what shows approvals and sends them to your phone. A call that needs your approval waits, and is denied if nobody answers in time: 60 seconds for MCP agents and 10 minutes for Claude Code's hook (FOREMAN_APPROVAL_TIMEOUT, in seconds, changes both). See how approvals work.

Connect Claude Code. foreman setup wires its MCP connection and, unless you say no, the PreToolUse hook that gates its built-in tools (Bash, Read, Write, WebFetch, …). From the CLI:

foreman agent add claude-code            # MCP entry + identity token in ~/.claude.json
foreman agent hook install claude-code   # its own tools go through Foreman too

Give every agent GitHub, safely:

foreman mcp add github && foreman secrets add github-pat
foreman mcp tools github          # scan, pin, show token cost

Organise your agents:

foreman org init --template startup --company "Acme"
foreman org show
foreman org assign marketing "draft the launch post for Friday"

Get alerts on your phone:

foreman notify ntfy-setup         # or configure Telegram for tap-to-approve

Run it from the terminal. In foreman start, press : and type what you'd type in chat:

› status
› assign engineering add rate limiting to the public API
› codex write tests for src/rate-limit.ts
› approve

n opens your inbox (on Keys, Providers and Services it means "new"), and Tab moves between pages. From any shell, foreman inbox shows the same notifications. See docs/tui.md.

Then watch it work: foreman log tail --follow, foreman doctor, foreman policy show.

How it works

 you ── TUI · Telegram · Slack · Discord (approve + command) · email · ntfy (alerts)
  │
  ▼
┌───────────────────────────── FOREMAN (local) ─────────────────────────────┐
│  policy.yaml ─► risk rules ─► approval ─► audit (SQLite + FTS5)           │
│      ▲            secret paths · shell · network · injection ·            │
│      │            loops · responsibility · tamper protection              │
│  org.yaml: departments · reporting lines · per-department MCP access      │
│  MCP Hub: catalog · poisoning scan · pins · result guard · token budget   │
└───────▲──────────────────▲──────────────────▲─────────────────▲───────────┘
        │ MCP (stdio)      │ PreToolUse hook  │ ACP / codex     │ upstream MCP
   any MCP agent      Claude Code      Hermes · OpenClaw ·   GitHub · Notion ·
                                        ZeroClaw · Codex      Stripe · …

Foreman is a pre-execution gate. It decides before a call runs; it does not undo side effects afterwards. See docs/architecture.md.

Supported integrations

| Category | Integrations | | --- | --- | | Agents (guide) | Claude Code · Codex · Gemini CLI · Hermes · OpenClaw · ZeroClaw · any MCP agent | | Work tools (integrations) | GitHub · GitLab · Jira & Confluence · Trello · Linear · Notion: add once, pick which agents may use each, read-only by default | | MCP servers (hub) | GitHub · Filesystem · Memory · Playwright · Chrome DevTools · Notion · Sentry · Stripe · Brave · Exa · Firecrawl · Context7 · Figma · Resend · Discord · X · YouTube · App Store Connect · App Store + Google Play · your own (stdio or HTTPS) | | Channels (guide) | Telegram, Slack and Discord (tap-to-approve, /foreman commands) · Email (SMTP) · ntfy · Webhook (signed) · OS notifications | | LLM providers (guide), for Foreman's optional smart features | Anthropic · OpenAI · Google Gemini · Ollama (local) · any OpenAI-compatible endpoint |

How is this different from…

| | Foreman | Agent built-in permissions | MCP gateways / registries | Tracing / observability | | --- | --- | --- | --- | --- | | Covers several agents at once | ✅ | ❌ one agent each | ✅ MCP only | ✅ | | Human approval before risky calls | ✅ TUI + phone | ✅ in that agent's UI | rarely | ❌ after the fact | | Tool poisoning + rug-pull checks | ✅ | ❌ | some | ❌ | | Agent-to-agent delegation rules (org chart) | ✅ | ❌ | ❌ | ❌ | | Runs locally, no account | ✅ | ✅ | varies | usually cloud |

Documentation

| Doc | What's inside | | --- | --- | | docs/tui.md | The TUI: approvals queue, command console, inbox, keys | | docs/integrations.md | Integrations: GitHub, GitLab, Jira, Trello, Linear, Notion — add, scope, review | | docs/mcp-hub.md | MCP Hub: catalog, mcp.yaml, security, token budget | | docs/org.md | Foreman Org: departments, roles, delegation, upgrades | | docs/notifications.md | Telegram, Slack, Discord, email, ntfy, webhook | | docs/architecture.md | Mediator pipeline, approval flow, data model | | docs/policy.md | policy.yaml reference: rules, conditions, precedence | | docs/detection.md | Risk rules and scoring | | docs/agent-lifecycle.md | Install / disable / block / remove agents | | docs/install.md | Install, upgrade, uninstall | | SECURITY.md | Threat model, limits, reporting | | CHANGELOG.md | What changed |

Roadmap

• ✅ Shipped: the mediator across MCP, hooks, ACP and codex · risk engine with tamper protection, and shell rules that score what a command does rather than how it is spelled (2.1.1) · MCP Hub with a curated catalog, OAuth for hosted servers, access lists, confirm rules, tool-poisoning and rug-pull defence · integrations for GitHub, GitLab, Jira / Confluence, Trello, Linear and Notion, managed from the TUI, the CLI and chat · a local daemon while foreman start runs (one upstream per server, ~30 ms hooks) · per-agent identity tokens · Foreman Org with department channels, cost reports, budgets and approval escalation along the org chart · TUI control surface (approval queue, command console, inbox, model picker) · approvals and /foreman from Telegram, Slack and Discord · email / ntfy alerts · lazy tool discovery · the daemon as a login service (foreman service) · Ollama and OpenAI-compatible endpoints as Foreman's own model · Claude Code's PreToolUse hook added by the setup wizard.
• 🧭 Later: a desktop / menu-bar app · cross-machine mesh · a local classifier model (Prompt Guard) for borderline calls.

Contributing

PRs and issues are welcome. Start with CONTRIBUTING.md, the agent contribution guide and the Code of Conduct. Every PR runs the verify check.

MIT © 2026 Fatih Tuzlu

Built for people running more than one agent. 🦫 Foreman the Beaver is watching.