{"id":50499523,"url":"https://github.com/tuzlu07x/foreman","last_synced_at":"2026-06-02T10:03:21.760Z","repository":{"id":361700457,"uuid":"1237667612","full_name":"tuzlu07x/foreman","owner":"tuzlu07x","description":"Your local AI agents talk to each other. You should know what they're saying. A terminal-first guardian that mediates every MCP call, scores it for risk, and asks before anything dangerous happens.","archived":false,"fork":false,"pushed_at":"2026-05-31T22:23:28.000Z","size":2377,"stargazers_count":1,"open_issues_count":13,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-31T23:09:01.138Z","etag":null,"topics":["ai-agents","audit","ink","local-first","mcp","security","sqlite","terminal","typescript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tuzlu07x.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/security-report.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-13T11:51:05.000Z","updated_at":"2026-05-31T22:23:32.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tuzlu07x/foreman","commit_stats":null,"previous_names":["tuzlu07x/foreman"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/tuzlu07x/foreman","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tuzlu07x%2Fforeman","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tuzlu07x%2Fforeman/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tuzlu07x%2Fforeman/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tuzlu07x%2Fforeman/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tuzlu07x","download_url":"https://codeload.github.com/tuzlu07x/foreman/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tuzlu07x%2Fforeman/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33789013,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-01T02:00:06.963Z","response_time":115,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","audit","ink","local-first","mcp","security","sqlite","terminal","typescript"],"created_at":"2026-06-02T10:03:21.111Z","updated_at":"2026-06-02T10:03:21.750Z","avatar_url":"https://github.com/tuzlu07x.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"https://raw.githubusercontent.com/tuzlu07x/foreman/main/assets/mascot/foreman-beaver-256.png\" alt=\"Foreman the Beaver\" width=\"160\" /\u003e\n\n\u003cimg src=\"https://raw.githubusercontent.com/tuzlu07x/foreman/main/assets/foreman-banner.svg\" alt=\"FOREMAN\" width=\"520\" /\u003e\n\n### Your local AI agents talk to each other. You should know what they're saying.\n\nA terminal-first guardian that **mediates every call** between the AI agents on your\nmachine, **scores each request for risk**, and **asks you** before anything dangerous happens.\n\n\u003cbr/\u003e\n\n[![npm](https://img.shields.io/npm/v/foreman-agent?color=FF8C42\u0026label=foreman-agent\u0026logo=npm)](https://www.npmjs.com/package/foreman-agent)\n[![website](https://img.shields.io/badge/website-foreman--agent.com-FF8C42?logo=readthedocs\u0026logoColor=white)](https://foreman-agent.com)\n[![license](https://img.shields.io/badge/license-MIT-FF8C42)](./LICENSE)\n[![node](https://img.shields.io/badge/node-%E2%89%A520-00D084?logo=node.js\u0026logoColor=white)](https://nodejs.org)\n[![platform](https://img.shields.io/badge/platform-macOS%20%C2%B7%20Linux%20%C2%B7%20WSL2-4D9DE0)](#install)\n[![PRs welcome](https://img.shields.io/badge/PRs-welcome-FFC542)](./CONTRIBUTING.md)\n\n\u003cbr/\u003e\n\n**[Website](https://foreman-agent.com)** · **[Install](#install)** · **[Quick start](#quick-start)** · **[Docs](#documentation)** · **[Integrations](#supported-integrations)** · **[Roadmap](#roadmap)**\n\n\u003c/div\u003e\n\n\u003c!-- asciinema cast placeholder — drop in once recorded via `examples/phishing-scenario/` --\u003e\n\u003c!-- [![asciicast](https://asciinema.org/a/PLACEHOLDER.svg)](https://asciinema.org/a/PLACEHOLDER) --\u003e\n\n---\n\n## 🦫 What is this?\n\nWhen your machine runs Claude Code, Hermes, OpenClaw and friends side by side, they call\neach other and reach for your files, your network, and your shell — and nobody is watching.\nForeman sits in the middle of all of it.\n\n|                |                                                                                                    |\n| -------------- | -------------------------------------------------------------------------------------------------- |\n| 🛡️ **Mediate** | Every MCP call between your agents and their tools flows through Foreman.                          |\n| 📊 **Score**   | Heuristic rules flag secret-file access, outbound network, shell exec, and cross-agent calls.      |\n| 🙋 **Ask**     | When a request crosses the threshold, you decide in the terminal: `[a]llow / [d]eny / [r]emember`. |\n| 📝 **Log**     | Every request hits a local SQLite store with full-text search (FTS5) for audit.                    |\n\n\u003e If a phishing email tells your assistant agent to share your `.env`, Foreman sees it,\n\u003e scores it **80/100**, and asks before anything leaves your machine.\n\n---\n\n## Install\n\nThe fastest path — also installs Node 20 LTS via `nvm` if you don't already have it:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/tuzlu07x/foreman/main/install.sh | bash\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eOther ways to install\u003c/b\u003e — Homebrew · npm\u003c/summary\u003e\n\n\u003cbr/\u003e\n\n**Homebrew** (macOS / Linuxbrew):\n\n```bash\nbrew tap tuzlu07x/foreman\nbrew install foreman-agent\n```\n\n**npm** (if you already manage Node yourself, `\u003e= 20` required):\n\n```bash\nnpm install -g foreman-agent\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eInstall script options\u003c/b\u003e — pin a version, custom prefix, uninstall\u003c/summary\u003e\n\n\u003cbr/\u003e\n\n| Variable / flag          | Effect                                                     |\n| ------------------------ | ---------------------------------------------------------- |\n| `FOREMAN_VERSION=0.1.0`  | Pin a specific release                                     |\n| `FOREMAN_INSTALL_PREFIX` | Use a non-default npm prefix                               |\n| `FOREMAN_SKIP_NVM=1`     | Refuse the nvm bootstrap path                              |\n| `--uninstall`            | Remove the global package (`~/.foreman/` is left in place) |\n\n\u003c/details\u003e\n\n\u003e **🪟 Windows:** Foreman runs through **WSL2** (Ubuntu 22.04) today — it assumes a POSIX\n\u003e shell, so native PowerShell / `npm install` on Windows isn't supported yet. Full\n\u003e walkthrough and the WSL2-specific quirks are in [`docs/windows-wsl2.md`](docs/windows-wsl2.md).\n\u003e Native Windows lands in **v0.2+**.\n\n---\n\n## Quick start\n\n```bash\nforeman init                 # create ~/.foreman/ (db, keypair, policy.yaml)\nforeman start                # launch the TUI gateway\n\n# Point an agent at Foreman's stdio MCP transport\nforeman mcp-stdio\n```\n\nWire an agent (**Claude Code** example):\n\n```jsonc\n// ~/.config/claude-code/mcp.json\n{\n  \"mcpServers\": {\n    \"foreman\": { \"command\": \"foreman\", \"args\": [\"mcp-stdio\"] },\n  },\n}\n```\n\nThen watch it work:\n\n```bash\nforeman log tail --follow    # live request stream\nforeman agent list           # registered agents\nforeman policy show          # active rules\n```\n\n**Per-agent recipes:**\n\n- [`examples/claude-code/`](examples/claude-code/) — Anthropic's terminal coding agent\n- [`examples/hermes-integration/`](examples/hermes-integration/) — Nous Research's personal assistant (Telegram + Discord) with a phishing-safe policy\n- [`examples/openclaw-integration/`](examples/openclaw-integration/) — OpenClaw with a skill-compromise policy (CVE-2026-25253, Koi Security advisory)\n- [`examples/mock-agent/`](examples/mock-agent/) — minimal MCP client that exercises the gateway end-to-end\n\n---\n\n## ▶️ 5-minute demo\n\nA scripted phishing scenario walks through the boot banner → idle dashboard → ⚠ approval\nmodal → inspect → remember → audit log:\n\n```bash\ncd examples/phishing-scenario\n./run-demo.sh\n```\n\nSee [`examples/phishing-scenario/STORYBOARD.md`](examples/phishing-scenario/STORYBOARD.md)\nfor the scene-by-scene script, and\n[`docs/scenario-pazartesi-sabahi.md`](docs/scenario-pazartesi-sabahi.md) for the longer\nproduct narrative that pins Foreman as a **pre-execution gate** (it stops a `.env` leak\n_before_ the call runs — it doesn't undo afterwards).\n\n---\n\n## Supported integrations\n\nForeman ships three bundled catalogs that drive the wizard, the TUI management pages, and\nthe CLI. Tier-1 entries below; see the linked guides for setup walkthroughs.\n\n| Category                                              | Integrations                                                                                                                   |\n| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |\n| **🤖 Agents** ([guide](docs/agent-lifecycle.md))      | Claude Code · Codex · Hermes · OpenClaw · ZeroClaw · Generic MCP                                                               |\n| **🧠 LLM providers** ([guide](docs/llm-providers.md)) | Anthropic · OpenAI · Google Gemini · Ollama (local) · Custom OpenAI-compatible (Groq / Together / OpenRouter / vLLM / LiteLLM) |\n| **🔌 Services** ([guide](docs/services.md))           | Telegram · Discord · Slack · GitHub · Atlassian (Jira / Confluence) · Notion                                                   |\n\nAnthropic + OpenAI can also be authenticated by signing in with your Claude or ChatGPT\nsubscription — `foreman llm login \u003cprovider\u003e` ([details](docs/llm.md#subscription-oauth-claude--codex)).\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eAction-mediation transport\u003c/b\u003e — how each integration is wired (#552 / #445)\u003c/summary\u003e\n\n\u003cbr/\u003e\n\nEvery integration falls into one of three categories Foreman handles uniformly.\n\n| Transport                             | Agents                                                                                    | How it works                                                                                                                                                                                                                                                       |\n| ------------------------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| **Bridge (JSON-RPC stdio)**           | Codex (`codex exec-server`), Hermes / OpenClaw / ZeroClaw (`\u003cbinary\u003e 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. |\n| **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.                                                                                       |\n| **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.                                                                                                            |\n\nAudit which transport each agent uses via `foreman agents show \u003cid\u003e`. The wizard surfaces\nit at install time; `foreman doctor` flags missing ACP binaries.\n\n\u003c/details\u003e\n\nAdding entries to the bundled catalogs is documented in\n[`docs/registry-maintenance.md`](docs/registry-maintenance.md). A user-editable upstream\nregistry URL is on the v0.2 roadmap.\n\n---\n\n## How is this different from…?\n\nTracing tools tell you _what happened_. Foreman decides _what's allowed to happen_ —\nlocally, before the call lands.\n\n|                              | Foreman          | LangSmith / Helicone | Vanilla MCP               |\n| ---------------------------- | ---------------- | -------------------- | ------------------------- |\n| Runs on your machine         | ✅ local-first   | ☁️ cloud SaaS        | ✅ local                  |\n| Mediates agent-to-agent      | ✅               | tracing only         | direct calls, no mediator |\n| Asks before risky calls      | ✅ in terminal   | post-hoc dashboard   | no approval layer         |\n| Audit log under your control | ✅ SQLite + FTS5 | their cloud          | no audit                  |\n| Identity per agent           | ✅ Ed25519       | n/a                  | n/a                       |\n| Open source                  | ✅ MIT           | proprietary          | spec                      |\n\nThe closest mental model: a personal-scale gateway with an audit log, for the multi-agent\nsetups people now run at home.\n\n---\n\n## Roadmap\n\n- ✅ **v0.1 — Today.** Single-machine gateway, heuristic risk scoring, Ink TUI, SQLite audit, MCP stdio.\n- 🔜 **v0.2 — Cross-machine mesh.** `foreman link`, optional Tailscale, master/child keys, primary-device approval.\n- 🧠 **v0.3 — Smart risk.** Optional Llama Prompt Guard 2, intent classification, token budget enforcement.\n- 🧩 **v0.4 — Ecosystem.** Plugin API, Cedar policy support, official Hermes / OpenClaw adapters.\n\n---\n\n## Documentation\n\n📖 **Hosted docs: [foreman-agent.com](https://foreman-agent.com)** — the guides below, nicely rendered and searchable.\n\n| Doc                                                              | What's inside                                                 |\n| ---------------------------------------------------------------- | ------------------------------------------------------------- |\n| [`FOREMAN.md`](./FOREMAN.md)                                     | Full design doc — architecture, services, schema              |\n| [`FOREMAN-TUI.md`](./FOREMAN-TUI.md)                             | TUI / brand spec — palette, mascot, layout, screens           |\n| [`docs/architecture.md`](./docs/architecture.md)                 | Runtime behavior — mediator pipeline, approval flow, sessions |\n| [`docs/agent-lifecycle.md`](./docs/agent-lifecycle.md)           | Install / disable / enable / block / remove agents            |\n| [`docs/llm-providers.md`](./docs/llm-providers.md)               | LLM provider catalog reference                                |\n| [`docs/services.md`](./docs/services.md)                         | Service catalog + setup walkthroughs                          |\n| [`docs/registry-maintenance.md`](./docs/registry-maintenance.md) | Adding entries to the bundled catalogs                        |\n\n---\n\n## Contributing\n\nPRs and issues welcome. Start with [`CONTRIBUTING.md`](./CONTRIBUTING.md) and the\n[Code of Conduct](./CODE_OF_CONDUCT.md).\n\n**Website:** [foreman-agent.com](https://foreman-agent.com) ·\n**Repo:** [github.com/tuzlu07x/foreman](https://github.com/tuzlu07x/foreman) ·\n**Issues:** [`/issues`](https://github.com/tuzlu07x/foreman/issues)\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**[MIT](./LICENSE)** © 2026 Fatih Tuzlu\n\n\u003csub\u003eBuilt for developers running more than one agent. 🦫 Foreman the Beaver is watching.\u003c/sub\u003e\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftuzlu07x%2Fforeman","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftuzlu07x%2Fforeman","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftuzlu07x%2Fforeman/lists"}