🛡️ .sentinel()

Tool-agnostic policy engine with Advanced Guardrails capabilities, Cost Auditing, Pluggable Observability, and Deep Post-execution Context Compaction.

✨ Key Features

1. 🛡️ Active Guardrails (Pre-execution):

   • Obfuscation Detection: Blocks shell commands containing suspicious hexadecimal encoding, eval, or base64 decoding.
   • Sensitive File Protection: Prevents unauthorized read/write to .env, .git/config, .ssh keys, and /etc/passwd.
   • Exfiltration Prevention: Prevents connections to known exfiltration hosts such as webhook.site and ngrok.io.

2. 📊 Cost & Token Auditing:

   • Consolidated statistics of bytes and tokens accumulated per AI session.

3. 🗜️ Context Compaction (Post-execution):

   • truncate: Reduces string size while preserving the beginning and appending a truncation warning.
   • extract: Filters properties from large JSON payloads using paths (e.g., data.results[].title).
   • json-minify: Removes null/empty keys and reduces excessively long arrays.
   • html-simplify: Removes scripts, styles, and tags from HTML scrapers, returning only clean text.
   • Credential Sanitization: Scans tool outputs and obfuscates private SSH keys, API tokens, and LLM keys (OpenAI, Anthropic, GitHub, AWS, Slack, Google) before returning them to the model.

4. 🖥️ Real-Time Web Dashboard:

   • Complete interactive visual report with auto-refresh every 3 seconds.

🚀 Getting Started (Step by Step)

Follow the guide below to install, configure, and view your metrics with Sentinel from scratch:

1. Prerequisites & Installation

Download the dependencies and build the source code:

# In the sentinel root folder
npm install
npm run build

Now, link the Sentinel binary globally on your machine to use the CLI command from anywhere:

npm link

2. Interactive Initialization

Go to the root folder of the project where your AI agent or IDE is configured and run:

sentinel init

The Sentinel interactive wizard will run and do two things:

1. Create the default rules file sentinel.config.json.
2. Ask which environment you want to integrate Sentinel with (select the option of your preference, such as Antigravity, Cursor, or Claude Code for automatic setup/instructions).

3. Configure Custom Rules

You can define your security and compaction rules in sentinel.config.json. Example:

{
  "guardrails": {
    "rules": [
      { "matcher": "Shell:.*rm -rf.*", "action": "deny", "reason": "Destructive command blocked!" }
    ]
  },
  "compaction": {
    "rules": [
      { "matcher": "MCP:large_json", "strategy": "json-minify" },
      { "matcher": "HTTP:fetch", "strategy": "html-simplify" }
    ]
  }
}

4. Run Server and Dashboard

Start the HTTP interceptor server that tracks the calls and serves the visual dashboard:

sentinel listen --port=3001

5. View Metrics and Reports

• Real-Time Dashboard: Open your browser and go to http://localhost:3001/sentinel to see the consumption, context savings, and monitored tools.
• Static Physical Report: To automatically generate and open a static HTML of a specific session (e.g., antigravity-sess-1), run:

  sentinel report --session=antigravity-sess-1 --web

6. Testing in Practice (Simulation)

Want to see the power of Sentinel in action before plugging it into your AI? Sentinel has a built-in simulator that injects safe and dangerous commands, and gigantic test payloads. Just run:

npx sentinel simulate

This will automatically generate and open a local report showing Guardrails blocking rm -rf and Compaction reducing token usage on the fly.

7. Advanced Tip for Developers (Custom Sessions)

If you are integrating Sentinel into your own agent or MCP client and want to separate the report by chats or tasks instead of mixing everything into a single session, just send the "sessionId" property in the JSON payload (e.g., "sessionId": "chat-id-123"). Sentinel will automatically create isolated files (like chat-id-123.json), allowing you to audit the cost and savings of each conversation individually on the Dashboard!

🔌 IDE / Agent Support Table

| Tool | Support | Integration Notes | | :--- | :---: | :--- | | Antigravity | ✅ Supported | Automated setup via .agents/config.json. | | Cursor | ✅ Supported | Configurable interception as command type MCP Server. | | Claude Code | ✅ Supported | Activation via global hook hookSpecificOutput.updatedToolOutput. | | Devin | ⚠️ MCP Proxy | No support for local native hooks. Requires MCP proxy. |

📊 Benchmark & Performance (Stress Test)

Sentinel was subjected to a high-load realistic stress test containing multiple common development scenarios. The results below reflect the context compaction gains and financial savings obtained with pricing based on the Claude 3.5 Sonnet model ($3.00/1M Input tokens, $15.00/1M Output tokens):

Results per Scenario

| Scenario | Strategy | Original Size | Compacted Size | Original Tokens | Compacted Tokens | Savings (%) | Latency (ms) | | :--- | :--- | :---: | :---: | :---: | :---: | :---: | :---: | | NPM Build Logs | regex-clean | 185.6 KB | 158.2 KB | ~47,510 | ~40,510 | 14.7% | 5.59ms | | JSON MCP Search | extract | 127.9 KB | 58.5 KB | ~32,752 | ~14,966 | 54.3% | 3.33ms | | Web Scraping | html-simplify | 15.1 KB | 4.0 KB | ~3,857 | ~1,028 | 73.4% | 1.51ms | | Repeated Call | dedupe | 5.4 KB | 0.1 KB | ~1,375 | ~19 | 98.7% | 1.52ms |

Consolidated Metrics (Stress Test Session)

• Original Output Volume: 339.33 KB (~86,869 tokens)
• Compacted Output Volume: 226.16 KB (~57,896 tokens)
• Overall Output Reduction: 33.4%
• Estimated Cost Without Sentinel: $1.3045
• Estimated Cost With Sentinel: $0.8699
• Total Financial Savings: $0.4346 (33.3% reduction in LLM costs)
• Average Latency per Interception: 2.65ms (Ultra-fast local performance)

How to run the stress test locally:

You can run the same stress suite and save the session by running:

npm run stress-test

And view the generated session (stress-test-session) by accessing the graphical interface: http://localhost:3001/sentinel?sessionId=stress-test-session