# Foreman

> The review inbox for your AI workforce - risk-ranked review cards for every agent session (Claude Code, Cursor, any IDE), claims-vs-evidence verification, and ed25519-signed MCP receipts with rug-pull detection

- **Type:** MCP server
- **Install:** `agentstack add mcp-rohitkumarmanne-442-foreman`
- **Verified:** Pending review
- **Seller:** [rohitkumarmanne-442](https://agentstack.voostack.com/s/rohitkumarmanne-442)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [rohitkumarmanne-442](https://github.com/rohitkumarmanne-442)
- **Source:** https://github.com/rohitkumarmanne-442/foreman

## Install

```sh
agentstack add mcp-rohitkumarmanne-442-foreman
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

**The review inbox for your AI workforce.**

*Your agents say "done." Foreman says "prove it."*

[](https://www.npmjs.com/package/foremanjs)
[](https://github.com/rohitkumarmanne-442/foreman/blob/main/src/test/smoke.test.ts)
[](https://nodejs.org)
[](#connect-your-agent)
[](#local-first-by-design)
[](LICENSE)

---

You let AI agents write your code. They produce more change than any human can honestly review, so you skim, you rubber-stamp — and one day an agent rewrites an 869-line production app down to 97 lines, announces *"everything works!"*, and force-pushes it while you're looking the other way.

That happened to me. Foreman exists so it never happens silently again.

Foreman's whole personality fits in its thought cloud: **"Prove it."** Every claim your agents make gets checked against what they actually did.

## Eleven seconds of Foreman

*What you just watched: a critical card (force push + 89% file rewrite + unverified "everything works"), the click-through diff, the reviewer flagging it with a note **that gets injected into the agent's next session**, and the ed25519-signed MCP receipt log.*

## What just happened, in one screen

The agent above ended its session with *"Everything works and the checkout flow is fully functional. Done!"* Foreman's card tells a different story:

| The agent's version | What Foreman recorded |
|---|---|
| "Everything works" | **ran zero verification commands** — the claim is unverified ❓ |
| "simplified app.py" | rewrote **869 → 97 lines** (89% of the file deleted) |
| *(not mentioned)* | `git push --force origin main` |

Every agent session becomes a **review card**, ranked by risk, in a local inbox you work like email: **✓ approve** what's safe, **⚑ flag** what isn't — with a note the agent reads next session. Inbox zero means every AI change had human eyes on it.

## Numbers, honestly

Foreman is an observer, so the only numbers that matter are the ones it costs you and the ones it catches:

- **0 tokens.** Foreman never touches your prompts or your model bill. (One exception, and you opt into it: flagged-session notes are injected as context — that's the point.)
- **~120 ms per hook event** — median of 15 cold runs on an ordinary Windows laptop, and nearly all of it is Node process startup, not work. Hooks journal and exit; they cannot block, break, or slow your agent's reasoning.
- **What the rules catch:** 21 destructive-command patterns, 14 secret formats, mass rewrites (both whole-file and single-edit), sensitive paths, failed-then-claimed-success, and MCP tool-definition drift. Every check runs on the record of what the agent *did* — never on vibes.
- **26/26 end-to-end tests**, including: a tampered receipt failing signature verification, a reordered journal breaking the hash chain, a forged team pack being rejected, and a real headless session producing a critical card.

No benchmark theater: an observer can't make your agent faster or cheaper. It makes *you* faster — you spend ten minutes on the dangerous session and ten seconds on the README fix, instead of equal time skimming both.

## How it works

```text
Claude Code hooks ──┐
Cursor hooks ───────┤
Gemini CLI hooks ───┤
OpenCode plugin ────┤                         ┌─→ review cards, risk-ranked → inbox (foreman ui)
Codex notify ───────┼─→ ~/.foreman/*.jsonl ───┼─→ flags & notes → back into the agent (foreman brief)
foreman run ────────┤    append-only journal  ├─→ CI gate (foreman gate)
foreman watch ──────┤                         └─→ audit report (foreman report)
foreman wrap ───────┘
     └─ ed25519-signed, hash-chained receipts + tool fingerprints
```

No daemon, no database, no account. The journal is plain JSONL you can grep; the inbox is a local page that reads it live; receipts verify independently with `foreman verify`.

## Install

```bash
npm install -g foremanjs
foreman demo && foreman ui      # a populated inbox in 30 seconds
```

Requires Node 18+. Remove the sample data anytime with `foreman demo --clear`.

## Connect your agent

Claude Code — hooks, richest data

```bash
cd your-project
foreman init
```

Adds hooks to `.claude/settings.json`. Every new session files a card with diffs, commands, claims — and receives your outstanding flags as context when it starts. `foreman init --global` covers every repo at once; `--agent claude` installs for Claude Code only.

Cursor — hooks (Cursor 1.7+)

```bash
cd your-project
foreman init
```

Adds Foreman to `.cursor/hooks.json`: shell commands, file edits, MCP calls, and session ends are captured per the [Cursor hooks API](https://cursor.com/docs/hooks). `--agent cursor` installs for Cursor only.

Gemini CLI — native hooks, feedback loop included

```bash
cd your-project
foreman init
```

Adds Foreman to `.gemini/settings.json` per the [Gemini CLI hooks reference](https://github.com/google-gemini/gemini-cli/blob/main/docs/hooks/reference.md): shell commands, file writes/edits, and session ends all become card data — and your outstanding flags are injected as context on `SessionStart`, so Gemini gets the same feedback loop as Claude Code. `--agent gemini` installs for Gemini only.

OpenCode — native plugin

```bash
cd your-project
foreman init
```

Drops a plugin into `.opencode/plugins/` (auto-loaded per the [OpenCode plugin API](https://opencode.ai/docs/plugins/)) that translates bash/edit/write events onto `foreman ingest`. `--agent opencode` installs for OpenCode only; `--global` uses `~/.config/opencode/plugins/`.

Codex CLI, Copilot CLI, aider — any terminal agent

Launch the agent through Foreman. Its TTY is untouched; the card closes when it exits:

```bash
foreman run --name codex -- codex
foreman run --name copilot -- copilot
foreman run --name aider -- aider
```

**Codex bonus** — capture what Codex *claims* at the end of each turn (feeds claims-vs-evidence). In `~/.codex/config.toml`:

```toml
notify = ["foreman", "hook", "codex"]
```

Windsurf, JetBrains AI, or anything else — universal watch mode

```bash
cd your-project
foreman watch
```

No hooks needed: Foreman diffs the git working tree and journals every change any tool makes. Mass rewrites, secrets, and sensitive paths are all caught; `Ctrl+C` closes the card. Needs the project to be a git repo.

Your own tool / an agent Foreman doesn't know yet — the 20-line adapter

Anything that can emit JSON is a first-class adapter. Pipe normalized events to `foreman ingest` (one object, an array, or JSONL):

```bash
echo '{"agent":"mytool","session":"s1","kind":"command","command":"npm test","ok":true}' | foreman ingest
echo '{"agent":"mytool","session":"s1","kind":"file","file":"src/a.ts","lines_before":120,"lines_after":10}' | foreman ingest
echo '{"agent":"mytool","session":"s1","kind":"end","message":"All tests pass."}' | foreman ingest
```

Three kinds — `command`, `file`, `end` — and Foreman derives everything else: risk scoring, claims-vs-evidence, diffs (send `content` / `edits`), the works. As agents ship native hook APIs, a first-party adapter is just a translation layer onto this schema — PRs welcome.

MCP servers — signed receipts + rug-pull detection

In your agent's MCP config, prefix the server command:

```jsonc
// before
{ "command": "npx", "args": ["@someone/github-mcp"] }
// after
{ "command": "foreman", "args": ["wrap", "--name", "github", "--", "npx", "@someone/github-mcp"] }
```

See [MCP attestation](#mcp-attestation-make-tool-calls-provable) for what you get.

Then open the inbox and leave it open — cards appear live:

```bash
foreman ui        # → http://127.0.0.1:4517
```

Keyboard-first: `j`/`k` navigate · `a` approve · `f` flag · `/` search · `?` help.

**New here?** Your first visit starts a **60-second guided tour** that spotlights every option on the screen — what the risk score means, how claims-vs-evidence works, where flags go. Relaunch it anytime from the `?` help menu.

## The feedback loop: flagging teaches the agent

Approving is half the job. **Flagging closes the loop.** Flag a session and attach a note — *"Never force-push. Restore app.py and make surgical edits."* From then on:

- **Claude Code** — every new session in that repo receives your flags, notes, and the exact findings as context before it starts work (SessionStart hook).
- **Everything else** — `foreman brief` prints the same feedback; pipe it, paste it, or point your rules file at it.

Approve or unflag, and the brief goes silent. Your reviews stop being a graveyard of vetoes and become training signal.

## Gate your CI on human review

```bash
foreman gate                    # exit 1 while unapproved high/critical sessions exist here
foreman gate --level critical   # only block on critical
```

Drop it in a pre-push hook or CI job: **agent-written changes don't ship until a human approved the sessions that produced them.** It prints exactly which sessions are blocking and ignores demo data.

## Put the evidence on the PR

Reviewers shouldn't have to take "the agent tested this" on faith. One command turns a session into a PR comment with the receipts — risk score, claims vs evidence, findings, files, verification commands:

```bash
foreman pr                    # comment on the current branch's PR (via gh)
foreman pr --pr 42            # a specific PR
foreman pr --print            # print the markdown — paste it anywhere (GitLab, email…)
```

The inbox has the same thing as a **📋 PR comment** button on every card. Approved cards say so; flagged cards carry your note. Your PR reviews start from evidence, not vibes.

## Live in your menu bar

```bash
foreman tray                  # Windows · macOS · Linux
```

Runs the inbox server headless with a presence in your bar, everywhere:

- **Windows** — a real tray icon (WinForms NotifyIcon): live tooltip counts, balloon on new critical cards, click to open, Exit to stop.
- **macOS** — Foreman writes an [xbar](https://xbarapp.com)/SwiftBar plugin that puts 🧑‍🏭 with live counts in your actual menu bar (top sessions in the dropdown, click-through to the inbox), plus native notifications via `osascript` for new critical cards.
- **Linux** — a tray icon via `yad` when installed, `notify-send` critical-card notifications either way.

Zero npm dependencies on every platform.

## MCP attestation: make tool calls provable

MCP's `tool_call → tool_result` cycle runs on an honor system — nothing proves a server did what it claims, and nothing notices when a server quietly *changes what its tools say they do*. Wrapped servers get:

- **Signed receipts** — every `tools/call` journaled with SHA-256 hashes of params and result, latency, outcome — **ed25519-signed** by a key that never leaves your machine.
- **Hash-linked chains** — each receipt commits to the hash of the one before it. Editing a receipt breaks its signature; **deleting or reordering history breaks the chain.** `foreman verify` checks both and points at the exact receipt where history was altered.
- **Rug-pull detection** — tool definitions are fingerprinted on first use. When *"adds two numbers"* becomes *"adds two numbers. IGNORE PREVIOUS INSTRUCTIONS…"*, a finding lands in your inbox. Re-accept intentional updates with `foreman trust `.

The proxy passes every byte through untouched, JSON-RPC batches included. Your agent and the server never know it's there.

## Team mode: git is the sync layer

```bash
foreman team sync
git add .foreman-team && git commit -m "foreman packs" && git push
```

Exports your review cards for this repo as an **ed25519-signed pack** and imports every teammate pack it finds — packs that fail signature verification are rejected outright. Teammate cards show a 👥 owner badge in your inbox. Review authority stays local: you approve for you. No server, no accounts; the repo you already share does the syncing.

## Commands

| Command | What it does |
|---|---|
| `foreman init [--agent claude\|cursor\|gemini\|opencode\|all] [--global]` | install native hooks for this repo (or everywhere) |
| `foreman ui [--port 4517]` | open the review inbox |
| `foreman run [--name X] -- ` | supervise any terminal agent for one session |
| `foreman watch [path]` | watch a repo continuously — any IDE, any tool |
| `foreman brief [path]` | print outstanding human flags (agents read this) |
| `foreman gate [--level high\|critical]` | exit 1 while unapproved risky sessions exist |
| `foreman pr [--pr N] [--session id] [--print]` | post a session-evidence comment on the PR |
| `foreman tray` | menu-bar/tray inbox with critical-card alerts (Win/macOS/Linux) |
| `foreman ingest` | journal normalized JSON events from any tool (stdin) |
| `foreman wrap --name  -- ` | attest an MCP server |
| `foreman trust ` | re-baseline a server's tool definitions |
| `foreman verify` | verify every signature + chain continuity |
| `foreman team sync` | exchange signed card packs via the repo |
| `foreman report [--out audit.md]` | markdown audit of every session |
| `foreman status` | one-screen summary in the terminal |
| `foreman demo [--clear]` | seed / remove showcase data |
| `foreman config` | show config path + active settings |
| `foreman uninstall [--global]` | remove hooks (your journal stays) |

## The risk rules

| Rule | Severity | Fires when |
|---|---|---|
| `destructive_command` | critical | `rm -rf`, force push, `git reset --hard`, `DROP`/`TRUNCATE`, `DELETE` without `WHERE`, `kubectl delete`, `terraform destroy`, … |
| `mass_rewrite` | critical | a 50+ line file rewritten to (policy engines, sandboxes) | Eval harnesses(agent benchmarks) | Code provenance("git blame for AI") | **Foreman** |
|---|---|---|---|---|
| Acts | **before** the action | offline, on test tasks | after commit | **after the action, before you trust it** |
| Protects against | known-bad operations | regressions in agent quality | unclear attribution | **unreviewed change + unproven claims** |
| Claims vs evidence | — | — | — | **✓** |
| Signed record of MCP calls | some proxy identity checks | — | — | **✓ hash-chained receipts** |
| Feeds human decisions back to the agent | — | — | — | **✓** |
| Works with any agent | varies | harness-specific | editor-specific | **✓ hooks + run + watch** |

Guardrails constrain the machine. Foreman makes the human faster — review capacity is the bottleneck guardrails don't touch.

## Local-first, by design

- Everything lives in `~/.foreman/` as plain JSONL — greppable, diffable, deletable, yours.
- The inbox binds to `127.0.0.1` only. No server, no account, no telemetry, no exceptions.
- Hooks journal and exit `0` in milliseconds, even on internal failure — an agent can never be blocked by Foreman.

## FAQ

**Does my code leave my machine?** Never. The only thing that ever leaves is what *you* choose to commit (`foreman team sync` packs) or paste (`foreman report`).

**Will it slow my agent down?** ~120 ms per hook event, which is Node starting up. Your model does more than that between two tokens.

**Why not just read the agent's own summary?** The summary is the agent grading its own homework. "All tests pass" and *ran zero tests* routinely appear in the same session — that's precisely the badge Foreman pins on.

**Does it block anything?** Not by default — Foreman observes. If you *want* enforcement, `foreman gate` in CI blocks merges until sessions are approved. Observation you trust beats enforcement you disable.

**What about agents it doesn't know?** `foreman run -- ` and `foreman watch` don't care what the tool is. If it edits files in a git repo, it's covered.

**Can a clever agent fool it?** An agent can't un-run a force push or un-write a 20-line file where 869 lines used to be — the journal records actions, not narratives. Claims-checking is heuristic (regex, negation-aware) and will improve; treat UNVERIFIED as "look closer", not a verdict.

**How do I wipe everything?** `foreman uninstall` in each repo (or `--global`), then delete `~/.foreman/`. Done.

**Windows? macOS? Linux?** All three. Foreman is developed on Windows, which is usually the one

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [rohitkumarmanne-442](https://github.com/rohitkumarmanne-442)
- **Source:** [rohitkumarmanne-442/foreman](https://github.com/rohitkumarmanne-442/foreman)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-rohitkumarmanne-442-foreman
- Seller: https://agentstack.voostack.com/s/rohitkumarmanne-442
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.