foreman

---

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

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] -- <cmd…>	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 <srv> -- <cmd…>	attest an MCP server
foreman trust <srv>	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 <40% of its size — whole-file or single edit (thresholds configurable)
secret_in_code	critical	AWS · Anthropic · Stripe · GitHub · GitLab · Google · Slack · SendGrid · npm keys, private keys, JWTs, hardcoded passwords
failed_verification	critical	the agent claimed success after its own checks failed
unverified_claims	high	the agent claimed success and never ran anything that could prove it
sensitive_path	high	.env, secrets, auth, migrations, CI workflows, .ssh, .npmrc touched
mcp_tool_drift	high	an MCP server changed its tool definitions vs the trusted baseline
untested_change	medium	code changed, nothing was ever executed

Claim detection is negation-aware: "tests fail" and "should now work" are never counted as success claims. Findings deduplicate, and a success claim with no code change behind it scores lower (it's probably just Q&A).

Tune it

~/.foreman/config.json (foreman config shows the path and live values):

{
  "port": 4517,
  "ignore": ["node_modules/", "dist/", "*.lock", "generated/"],  // never track these paths
  "disable_rules": ["untested_change"],                           // rules you don't want
  "mass_rewrite_min_lines": 50,
  "mass_rewrite_ratio": 0.4,
  "notify_command": "powershell -c \"[console]::beep(880,300)\""  // runs when a NEW critical card appears
  // notify_command env: FOREMAN_SESSION, FOREMAN_LEVEL, FOREMAN_SCORE, FOREMAN_REPO
}

How Foreman compares

Adjacent tools solve adjacent problems — most teams will want more than one of these:

	Guardrails (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 -- <anything> 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 that breaks.

Uninstall

foreman uninstall            # remove hooks from this repo
foreman uninstall --global   # remove user-level hooks
npm uninstall -g foremanjs   # remove the CLI
# your data: delete ~/.foreman/ whenever you like — it's just JSONL

uninstall only removes hook entries Foreman itself added; the rest of your settings files are left untouched.

Development

git clone https://github.com/rohitkumarmanne-442/foreman
cd foreman
npm install
npm test        # builds + runs the 19 end-to-end tests

Zero runtime dependencies — TypeScript, Node's stdlib, and one static HTML file for the inbox. The test suite spawns real child processes for hooks, drives a fake MCP server through the proxy, git-inits throwaway repos for the watcher, and forges a team pack to prove it gets rejected. PRs welcome; keep that bar.

Roadmap

• Claude Code + Cursor + Codex adapters · foreman run · universal watch mode
• Approve/flag workflow, diff viewer, risk engine, audit reports
• Feedback loop — flag notes injected into the agent's next session
• Hash-linked receipt chains · team packs · CI gate · critical-card notifications
• PR write-back — foreman pr posts the session's evidence on the pull request
• Generic adapter API (foreman ingest) — any tool becomes an adapter in 20 lines
• Native adapters: Claude Code · Cursor · Gemini CLI · OpenCode · Codex notify
• Menu-bar/tray on Windows, macOS (xbar/SwiftBar), and Linux (yad) with critical-card alerts
• More native adapters as more agents ship hook APIs (each is a thin layer on foreman ingest)

License

MIT — do whatever you want, just keep the notice.