Agent Sentinel
TARGETMCP & Local Agents
WIREstdio (FD 0 / FD 1)
TELEMETRYJSON-RPC 2.0

The local flight recorder on the stdio wire for MCP & custom agents.

Agent Sentinel sits between your AI coding agent and its MCP servers. It intercepts raw JSON-RPC frames, measures tool execution latency, and halts dangerous commands before they touch your filesystem.

Star on GitHub
Single Go binaryLocal Cockpit :8848100% Loopback · Zero CloudOpen source · MIT
Fig. 01 · stdio wire architectureTransparent Wire Proxy
Client RuntimeAI Agent / Local LLM

Ollama, DeepSeek, Qwen, vLLM, custom agents, or Cursor & Claude Code.

  • • Channel: stdio (fd 0/1)
  • • Framing: JSON-RPC 2.0
On The WireSentinel Local Proxy

Transparent Go proxy intercepting all frames before execution.

  • • Inspect: Raw JSON-RPC frames
  • • Record: Append-only JSONL
  • • Profile: Per-tool ms latency
  • • Gate: Human approval on risky calls
Machine TargetMCP Tools & FS

@modelcontextprotocol filesystem, Postgres, Git, Bash PTY, APIs.

  • • Executes only if approved
  • • Returns output back upstream
Intercepted Wire Frames (Sample Trace)stdio pipe stream
ALLOWtools/call: read_filepath: "src/config.ts"8 ms · passed
BLOCKEDtools/call: read_filepath: ".env.production" (dotenv-access)0 ms · halted
HELDtools/call: run_shellcmd: "git push --force origin main"waiting ⌘↵
Agent Sentinel cockpit · localhost:8848
The Agent Sentinel cockpit. A timeline of an agent's tool calls: inspecting payload arguments, execution latency, policy verdicts, and held operations waiting for approval.
Live local cockpit at http://localhost:8848 — powered by the wire proxy.

The stdio black box vs. Sentinel on the wire.

When you build with local open-weight models (Ollama, vLLM, DeepSeek, Qwen) or custom agent scripts, MCP tools communicate silently over stdio pipes. You have zero visibility into what payload was passed, which tool is hanging, or what file is being touched.

Execution VectorDirect stdio (Without Sentinel)Sentinel Local Proxy (On The Wire)
Tool Call PayloadsOpaque JSON-RPC. Invisible unless instrumented in code.Intercepted & inspected frame-by-frame in real-time.
Hallucinations & LoopsExecutes destructive calls or burns CPU in silent loops.Policy engine catches secret leaks and holds risky commands.
Execution LatencyNo timing data. Impossible to identify slow MCP servers.Per-call millisecond telemetry logged on every turn.
Session HistoryLost in terminal buffer as soon as process exits.Saved to ~/.sentinel/sessions/*.jsonl for offline replay.

Every wire frame, recorded and measurable.

Sentinel sits on the wire as a transparent stdio proxy or hook supervisor. It logs every event to append-only JSONL files so you know exactly why an agent succeeded or failed.

No cloud SaaS subscriptions, no sending your codebase or prompts to third-party dashboards. Everything is stored locally on your machine.

  • Raw JSON-RPC Inspector

    Wire level

    Every tools/call, tools/list, request payload, and response is intercepted and displayed in real time in the cockpit. No guesswork.

  • Latency & Traffic Telemetry

    Performance

    Track precise millisecond execution times per tool call. Spot lagging servers, token spikes, and runaway loops before they drain machine resources.

  • JSONL Flight Recorder & Replay

    Offline replay

    Every session is saved locally to ~/.sentinel/sessions/*.jsonl. Replay any past debugging session with 'sentinel ui session.jsonl'.

  • Execution Boundary & Fallback

    Safety net

    When an unaligned or small model tries to wipe a directory, access .env secrets, or run git force-push, Sentinel holds or blocks it on the wire.

mcp:fs:read_filepath: "src/config.ts"24 ms
mcp:fs:read_filepath: ".env.production"dotenv-access BLOCKED
git push --force origin main

HELDgit-force-pushsmall model requested remote history overwrite

Rejected automatically in 2:00

What the agent receives over the wire

Interactive sample of the cockpit approval dock. Control held calls straight from your browser.
A safety net when models hallucinate.
Small and custom models lack defensive alignment. When an agent ventures into destructive operations, Sentinel intercepts the call before execution.
Approve with one keypress or reject with corrective feedback that gets injected right back into the model's tool response.
  • ⌘↵ approve
  • Esc reject
  • JK navigate
  • ⌘K search frames
One binary. Zero configuration.
Use Sentinel as an MCP stdio proxy, run it alongside Cursor or Claude Code, or replay saved JSONL sessions from the command line.
1. Install the binary
$ git clone https://github.com/zaninifrancesco/agent-sentinel
$ cd agent-sentinel && make install
Or download a prebuilt binary for macOS or Linux from the releases page.
2. Choose how to run
$ sentinel mcp --ui -- npx -y @modelcontextprotocol/server-filesystem .
Wraps any stdio MCP server as a transparent proxy. Automatically launches the cockpit at http://localhost:8848.
Local by design, transparent about limits.
Private on your machine
  • Runs 100% locally on your machine. Zero cloud, no telemetry sent to third parties.
  • Single self-contained Go binary with Vite web cockpit embedded.
  • Sessions saved on disk as plain JSONL files in ~/.sentinel/sessions/.
  • Inspect raw MCP JSON-RPC frames without altering server code.
  • One-click standalone offline HTML audit report export.
Limits, stated plainly
  • Cost and tokens are estimates derived from tool traffic byte sizes, not LLM API tokens.
  • Open source binaries for macOS and Linux are unsigned/unnotarized.
  • macOS and Linux only (Windows has not been tested).
  • In Cursor hook mode, file edits are flagged after writing since the IDE emits post-save events.
  • Native lifecycle hook support verified for Claude Code and Cursor Agent.
Give your models autonomy. Keep complete visibility.
Free, open source, and everything stays on your machine.
Star on GitHub
SETUP WITH YOUR AI AGENT
Paste this prompt into Cursor, Claude Code, or your terminal LLM. Your agent will read the official AGENTS.md playbook, install the binary, configure background supervision, and guide you through each check step-by-step.
Install and set up Agent Sentinel for this project.

Follow the official setup playbook at https://github.com/zaninifrancesco/agent-sentinel/blob/master/AGENTS.md:
1. Verify system prerequisites (Go 1.22+ and Node.js). Clone the repo and run 'make install' to compile the binary to ~/.sentinel/bin/sentinel.
2. Start the local background supervisor ('~/.sentinel/bin/sentinel serve') and verify with curl that http://127.0.0.1:8848/api/config responds with approvals enabled.
3. Configure the hooks for my environment (ask me whether I use Cursor or Claude Code, or if I want to wrap an MCP server via 'sentinel mcp').
4. Run a synthetic hook verification to prove that commands are intercepted and appear on the local cockpit timeline.
5. Guide me step-by-step through what you did, explain what Sentinel is intercepting on my machine, and show me how to open http://localhost:8848 in my browser.