foreman

---

🦫 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

Other ways to install — Homebrew · npm

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

Install script options — pin a version, custom prefix, uninstall

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).

Action-mediation transport — how each integration is wired (#552 / #445)

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

---