Guard your AI agents. Run them like a company.

Foreman (npm: foreman-agent) is a free, open-source (MIT) tool that runs on your own machine and does two jobs. First, it guards your AI agents: tool calls from Claude Code, Codex, Hermes, OpenClaw, ZeroClaw and any MCP agent go through one pipeline (policy.yaml, then risk rules, then your approval when it matters, then a local SQLite audit log) before they run. It fails closed: if Foreman can't decide, the call doesn't run. Second, it runs your agents like a company: an org chart of departments and roles, who reports to whom, what each role may do, budgets and reports.

Yes. That is Foreman Org. foreman org init --template startup (or software-team, solo) writes an org chart to org.yaml: departments, roles, and who each role reports to (reports_to). Any agent can fill any role. Foreman then enforces the chart: a manager can hand work to its reports (and further down with skip_levels), a report can go to its own manager, colleagues in a department can work together, and other departments are reached through their heads. A blocked hand-off says who to ask instead. Agents talk in team channels with the org_post and org_read tools, and report up with org_report. You stay at the top: risky actions still come to you for approval.

Use the role library. foreman org roles lists the ready-made roles: manager, developer, code-reviewer, researcher, writer, analyst, support and assistant. foreman org add-role reviewer --preset code-reviewer --department engineering adds one: it gets the preset's title, instructions and permissions, and a new Claude Code or Codex instance named after the role fills it. For your own role, describe it in your own words: foreman org add-role copywriter --runs-on claude-code --describe "Write launch posts in a short, friendly style.". Pass --agent <id> instead to give the role to an agent you already registered. The setup wizard (foreman setup) has the same as a picker in its last step, Your team.

Yes. Register Claude Code or Codex again under a name per role: foreman agent add backend --type codex, foreman agent add frontend --type codex, foreman agent add reviewer --type claude-code. Each instance is its own agent, with its own identity token, its own role, its own team channels and its own lines in the audit log and reports. When Foreman hands an instance work, it runs Codex or Claude Code as that instance and tells it its role, so the instances can talk to each other and hand work on through Foreman. Your own Claude Code and Codex config stays wired to the agent itself.

Yes. Each role can list what its agent may do with its own tools: read files, write files, run shell commands, reach the network. Set it with --can read,write,shell,network on foreman org add-role, or can: on the role in org.yaml. Foreman checks this before policy.yaml, so a code reviewer that may only read is refused a file write whatever the policy says. The ready-made roles come with sensible limits (a reviewer reads only; a developer reads, writes and runs commands). A role without can is limited only by policy.yaml, and a broken org.yaml that sets can fails closed.

Connect Telegram, Slack or Discord in foreman setup (or later with foreman notify), then run foreman service install. The background service runs the whole gateway at login, so approvals reach your chat with no terminal open: tap Allow or Deny. One Telegram bot is enough: it carries approvals, alerts and /foreman commands. Only if a chat agent such as Hermes or OpenClaw reads the same bot do you need a second bot for approvals (foreman notify approval-bot). For Slack and Discord, foreman notify slack-interactive (Socket Mode) and foreman notify discord-interactive (Gateway) add Allow / Deny buttons and /foreman; no public URL is needed, and only the user ids you list can act. Buttons carry an HMAC tag, the audit log names who decided, and a tap from anyone else is refused and audited.

Yes. Send your Telegram bot a plain message such as report me or what is claude-code doing?. Plain messages only read, and only from your own chat. Anything that changes something (stop, write, integration disable) runs only when you type it with /foreman. In Telegram, Slack or Discord, /foreman report marketing month gives a department's report, /foreman spend today's spend, and /foreman write codex … hands out work. When Foreman's own LLM is off, over budget or failing, report me still gives today's company report instead of an error.

foreman org report gives the whole company by department; foreman org report engineering week one department, role or agent. A report shows spend and tokens, finished and failed tasks, tool calls allowed and blocked, the latest results and budget use; it needs no LLM. foreman usage week --by agent shows spend at a glance. foreman org budget marketing 50 sets a monthly budget (--daily for a daily one) that alerts at 80% and 100%; --pause stops agents from handing the department new work once it is spent. For agents you start yourself, foreman usage env claude-code prints the settings that make them report their usage.

Install Foreman and run foreman setup: pick Claude Code and answer yes (the default) when it asks to check Claude Code's own tools before they run, which adds Foreman's PreToolUse hook. From the command line, foreman agent add claude-code and foreman agent hook install claude-code do the same (add --project to cover one project only). Keep Foreman running (foreman service install, or foreman start) so approvals reach you. The hook checks Claude Code's Bash, Write, Edit, Read and other built-in tool calls before they run. Foreman's shell rules score what a command does, not how it is spelled: rm -rf, rm -r -f, find -delete, xargs rm, deletes inside bash -c or behind sudo / env, and Python or Node one-liners that delete files all ask for approval under the default policy, and a recursive delete of /, ~ or $HOME scores critical. A call nobody answers is denied (after 10 minutes for the hook, by default). Foreman decides before a call runs; it does not undo a call you approved.

Every call Foreman sees is stored with its decision, who or what decided it, the matching rule and the risk factors, in a local SQLite database with FTS5 full-text search. foreman log tail --follow streams it, foreman log search "<text>" searches it, foreman log show <id> explains one call, and foreman inbox lists what needed your attention. foreman org messages shows what your agents said to each other. Secrets are masked, the files are owner-only and nothing is uploaded.

Yes. Foreman's MCP Hub runs locally: agents connect to foreman mcp-stdio and you add upstream servers once (foreman mcp add github, from a curated catalog of 19 or your own stdio / HTTPS server). Every call goes through policy, risk rules, approval and audit. Each server can have an access list (agents, departments) and allow / ask / confirm / deny rules per tool. Tool descriptions are scanned for poisoning and pinned, a tool that changes later is withheld until you trust it again (rug-pull detection), and results are redacted for secrets. Credentials stay in Foreman's encrypted store, not in agent configs.

No. Foreman runs on your machine with no account and no telemetry. Its policy, org chart, encrypted secret store and audit log stay in local, owner-only files. It only talks to what you connect: your agents, the MCP servers and integrations you add, the chat channels you enable, and an LLM provider if you turn on its optional LLM features (a local Ollama server keeps that on your machine too).

Agents: Claude Code (MCP and the PreToolUse hook), Codex, Hermes, OpenClaw, ZeroClaw and any MCP agent. Claude Code and Codex can also run as several instances, one per role. Platforms: macOS and Linux on x64 or arm64, and Windows through WSL2. The npm package needs Node.js 22.12 or later; a standalone binary with Node built in is published for macOS and glibc Linux.

No. Decisions come from policy.yaml, the org chart and deterministic risk rules. Foreman's optional LLM features (a second check of risky calls, daily summaries, the narrated report me) can use Anthropic, OpenAI or Google Gemini with your own key or subscription, a local or remote Ollama server, or any OpenAI-compatible endpoint (DeepSeek, OpenRouter, Groq, vLLM, LM Studio, LiteLLM, …). An LLM verdict can only make Foreman stricter, never relax a gate.

Yes, with the background service. foreman service install runs the whole headless gateway at every login (a LaunchAgent on macOS, a systemd user unit on Linux and WSL2 with systemd): the local daemon for agents and the Claude Code hook, approvals to your chat channels and your taps back, /foreman from chat, schedules, the daily digest and budget alerts. foreman start then attaches to it and shows the TUI only; quitting the TUI leaves the service running. foreman service status and foreman doctor say which process runs the gateway. Run foreman service install again after upgrading Node or Foreman.

It fails closed. If Foreman's hook can't run at all (for example Foreman isn't on the PATH Claude Code uses), the call is blocked with "Foreman's hook could not run". Hook errors block the call, and if the daemon stops during a call the hook blocks it and an MCP call gets an error. With neither the service nor foreman start running, nobody is shown an approval, so a call that needs one is denied when it times out (60 seconds for MCP agents, 10 minutes for the Claude Code hook; FOREMAN_APPROVAL_TIMEOUT changes both) and foreman inbox lists what was missed.

Built-in permission prompts cover one agent each, in that agent's own UI. Foreman applies one policy and one audit trail across several agents, lets you approve from your phone, checks MCP tools for poisoning and silent changes, and organises agents into an org chart with roles, permissions, delegation rules and budgets. Tracing and observability tools record what happened; Foreman decides before a call runs.

Yes. Foreman is open source under the MIT license and free to use. The source is at github.com/tuzlu07x/foreman and the package is foreman-agent on npm.