Foreman

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

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

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

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

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. --agent cursor installs for Cursor only.

Gemini CLI — native hooks, feedback loop included

cd your-project
foreman init

Adds Foreman to .gemini/settings.json per the Gemini CLI hooks reference: 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

cd your-project
foreman init

Drops a plugin into .opencode/plugins/ (auto-loaded per the OpenCode plugin API) 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:

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:

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

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

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

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:

// 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:

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

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:

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

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/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

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
• Source: rohitkumarmanne-442/foreman
• License: MIT

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