vigilante

Runtime instrumentation that makes any app visible to LLMs — via MCP.

Built by @retamayo

Vigilante hooks into a running application with zero changes to your code. It records every HTTP request, function call, return value, object mutation, and error — then exposes it all to any MCP-capable LLM so it can autonomously debug your app.

Language-agnostic design. The MCP server speaks a universal event format. Per-language adaptors handle instrumentation. Node.js adaptor included, with plans to develop Rust, PHP, and Python adaptors.

Quick start

# 1. Clone and install
git clone https://github.com/retamayo/vigilante.git
cd vigilante
npm install

# 2. Run your app with instrumentation
node --require ./vigilante/adapters/node.js your-app.js

# 3. Add to your .mcp.json (Claude Code / Claude Desktop)

{
  "mcpServers": {
    "vigilante": {
      "command": "node",
      "args": ["path/to/vigilante/vigilante/server.js"]
    }
  }
}

Then tell the LLM: "the cart total is wrong" — it will query Vigilante and trace the runtime to find the bug.

Related MCP server: ai-dev-analytics

How it works

Your App --> Adaptor (hooks functions) --> Events File (JSON) --> MCP Server --> LLM

The Node.js adaptor installs two hooks before your app runs:

Events go into a ring buffer (keeps the last 2000 events) flushed to a temp file. The MCP server reads it on demand. Queries return up to 500 events at a time.

Sensitive data is automatically redacted — passwords, tokens, secrets, and authorization headers are replaced with [redacted] before being written to the event buffer.

MCP interface

Connect any MCP client to node vigilante/server.js (stdio transport).

Resources

Tools

vigilante_help — Returns a reference guide for all resources, query params, and recommended workflow. Call this first.

vigilante_query — Query runtime events with composable filters:

Example queries

"what errors occurred?"                          -> keyword filter
{ spanId: "http-3" }                             -> all events from one request
{ track: "user.balance" }                        -> follow balance through mutations
{ dataflow: "user.balance" }                     -> trace: read -> pass -> mutate -> return
{ diff: ["http-1", "http-3"] }                   -> compare working vs broken request
{ since: 42 }                                    -> incremental polling from last seen
{ spanId: "http-5", format: "tree" }             -> nested call tree for one request

Event format

{
  "id": 42,
  "timestamp": "2026-04-06T06:05:45.601Z",
  "type": "call",
  "spanId": "http-3",
  "depth": 0,
  "source": { "module": "./lib", "fn": "checkout" },
  "data": { "args": [{"balance": 500, "cart": [...]}, "alice", "HALF"] }
}

Event types: call, return, error, mutation, io_start, io_end

File structure

vigilante/
  context.js           -- ring buffer, span tracking, disk persistence
  server.js            -- MCP server (language-agnostic)
  register.js          -- backwards-compat entry point
  adapters/
    node.js            -- Node.js instrumentation adaptor
package.json
README.md
LICENSE

Adding a new language

Write an adaptor that:

1. Hooks function calls in the target language

2. Writes events to the same temp file in the universal format above

3. The MCP server works unchanged — it just reads the file

Security

Vigilante is a development-only debugging tool. It should not be used in production.

• Authorization headers are redacted automatically

• Passwords, tokens, secrets, and API keys in request bodies and function arguments are redacted

• The events file is written to the OS temp directory

• No data is sent over the network — the MCP server reads a local file via stdio

Philosophy

Vigilante records faithfully and analyzes nothing. The buffer is the source of truth. The LLM draws its own conclusions.