Your local AI agents talk to each other. You should know what they're saying.

A terminal-first guardian that mediates every call between the AI agents on your machine, scores each request for risk, and asks you before anything dangerous happens.

Website · Install · Quick start · Docs · Integrations · Roadmap

🦫 What is this?

When your machine runs Claude Code, Hermes, OpenClaw and friends side by side, they call each other and reach for your files, your network, and your shell — and nobody is watching. Foreman sits in the middle of all of it.

| | | | -------------- | -------------------------------------------------------------------------------------------------- | | 🛡️ Mediate | Every MCP call between your agents and their tools flows through Foreman. | | 📊 Score | Heuristic rules flag secret-file access, outbound network, shell exec, and cross-agent calls. | | 🙋 Ask | When a request crosses the threshold, you decide in the terminal: [a]llow / [d]eny / [r]emember. | | 📝 Log | Every request hits a local SQLite store with full-text search (FTS5) for audit. |

If a phishing email tells your assistant agent to share your .env, Foreman sees it, scores it 80/100, and asks before anything leaves your machine.

Install

The fastest path — also installs Node 20 LTS via nvm if you don't already have it:

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

Homebrew (macOS / Linuxbrew):

brew tap tuzlu07x/foreman
brew install foreman-agent

npm (if you already manage Node yourself, >= 20 required):

npm install -g foreman-agent

| Variable / flag | Effect | | ------------------------ | ---------------------------------------------------------- | | FOREMAN_VERSION=0.1.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/ is left in place) |

🪟 Windows: Foreman runs through WSL2 (Ubuntu 22.04) today — it assumes a POSIX shell, so native PowerShell / npm install on Windows isn't supported yet. Full walkthrough and the WSL2-specific quirks are in docs/windows-wsl2.md. Native Windows lands in v0.2+.

Quick start

foreman init                 # create ~/.foreman/ (db, keypair, policy.yaml)
foreman start                # launch the TUI gateway

# Point an agent at Foreman's stdio MCP transport
foreman mcp-stdio

Wire an agent (Claude Code example):

// ~/.config/claude-code/mcp.json
{
  "mcpServers": {
    "foreman": { "command": "foreman", "args": ["mcp-stdio"] },
  },
}

Then watch it work:

foreman log tail --follow    # live request stream
foreman agent list           # registered agents
foreman policy show          # active rules

Per-agent recipes:

• examples/claude-code/ — Anthropic's terminal coding agent
• examples/hermes-integration/ — Nous Research's personal assistant (Telegram + Discord) with a phishing-safe policy
• examples/openclaw-integration/ — OpenClaw with a skill-compromise policy (CVE-2026-25253, Koi Security advisory)
• examples/mock-agent/ — minimal MCP client that exercises the gateway end-to-end

▶️ 5-minute demo

A scripted phishing scenario walks through the boot banner → idle dashboard → ⚠ approval modal → inspect → remember → audit log:

cd examples/phishing-scenario
./run-demo.sh

See examples/phishing-scenario/STORYBOARD.md for the scene-by-scene script, and docs/scenario-pazartesi-sabahi.md for the longer product narrative that pins Foreman as a pre-execution gate (it stops a .env leak before the call runs — it doesn't undo afterwards).

Supported integrations

Foreman ships three bundled catalogs that drive the wizard, the TUI management pages, and the CLI. Tier-1 entries below; see the linked guides for setup walkthroughs.

| Category | Integrations | | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | 🤖 Agents (guide) | Claude Code · Codex · Hermes · OpenClaw · ZeroClaw · Generic MCP | | 🧠 LLM providers (guide) | Anthropic · OpenAI · Google Gemini · Ollama (local) · Custom OpenAI-compatible (Groq / Together / OpenRouter / vLLM / LiteLLM) | | 🔌 Services (guide) | Telegram · Discord · Slack · GitHub · Atlassian (Jira / Confluence) · Notion |

Anthropic + OpenAI can also be authenticated by signing in with your Claude or ChatGPT subscription — foreman llm login <provider> (details).

Every integration falls into one of three categories Foreman handles uniformly.

| Transport | Agents | How it works | | ------------------------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Bridge (JSON-RPC stdio) | Codex (codex exec-server), Hermes / OpenClaw / ZeroClaw (<binary> acp — ACP standard) | Foreman spawns the agent as a child process and mediates every approval it emits over JSON-RPC. Bidirectional: Foreman injects user directives via session/prompt (ACP) or turn/start (codex). Risk rules fire before each shell / file / network action runs. | | Wrap (synthetic Telegram updates) | Reserved for hypothetical chat-only daemon agents | Replaces the agent's Telegram poller with a Foreman-controlled wrap process that injects synthetic owner-originated updates. Documented + tested; no current agent needs it. | | Legacy hybrid | Claude Code (via PreToolUse hook), Generic MCP | PreToolUse hook for claude-code; chat-post relay for everything else. Pre-bridge baseline that still works for agents without a programmable transport. |

Audit which transport each agent uses via foreman agents show <id>. The wizard surfaces it at install time; foreman doctor flags missing ACP binaries.

Adding entries to the bundled catalogs is documented in docs/registry-maintenance.md. A user-editable upstream registry URL is on the v0.2 roadmap.

How is this different from…?

Tracing tools tell you what happened. Foreman decides what's allowed to happen — locally, before the call lands.

| | Foreman | LangSmith / Helicone | Vanilla MCP | | ---------------------------- | ---------------- | -------------------- | ------------------------- | | Runs on your machine | ✅ local-first | ☁️ cloud SaaS | ✅ local | | Mediates agent-to-agent | ✅ | tracing only | direct calls, no mediator | | Asks before risky calls | ✅ in terminal | post-hoc dashboard | no approval layer | | Audit log under your control | ✅ SQLite + FTS5 | their cloud | no audit | | Identity per agent | ✅ Ed25519 | n/a | n/a | | Open source | ✅ MIT | proprietary | spec |

The closest mental model: a personal-scale gateway with an audit log, for the multi-agent setups people now run at home.

Roadmap

• ✅ v0.1 — Today. Single-machine gateway, heuristic risk scoring, Ink TUI, SQLite audit, MCP stdio.
• 🔜 v0.2 — Cross-machine mesh. foreman link, optional Tailscale, master/child keys, primary-device approval.
• 🧠 v0.3 — Smart risk. Optional Llama Prompt Guard 2, intent classification, token budget enforcement.
• 🧩 v0.4 — Ecosystem. Plugin API, Cedar policy support, official Hermes / OpenClaw adapters.

Documentation

📖 Hosted docs: foreman-agent.com — the guides below, nicely rendered and searchable.

| Doc | What's inside | | ---------------------------------------------------------------- | ------------------------------------------------------------- | | FOREMAN.md | Full design doc — architecture, services, schema | | FOREMAN-TUI.md | TUI / brand spec — palette, mascot, layout, screens | | docs/architecture.md | Runtime behavior — mediator pipeline, approval flow, sessions | | docs/agent-lifecycle.md | Install / disable / enable / block / remove agents | | docs/llm-providers.md | LLM provider catalog reference | | docs/services.md | Service catalog + setup walkthroughs | | docs/registry-maintenance.md | Adding entries to the bundled catalogs |

Contributing

PRs and issues welcome. Start with CONTRIBUTING.md and the Code of Conduct.

Website: foreman-agent.com · Repo: github.com/tuzlu07x/foreman · Issues: /issues

MIT © 2026 Fatih Tuzlu

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