# vigilante

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

> Runtime instrumentation that makes any app visible to LLMs — via MCP.
>
> Built by [@retamayo](https://github.com/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

```bash
# 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)
```

```json
{
  "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.

---

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

| Hook | What it captures |
| --- | --- |
| `Module._load` | Wraps exported functions of user-land modules (`require('./...')`) |
| `http.createServer` | Intercepts HTTP requests/responses, creates spans per request |

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

| URI | Description |
| --- | --- |
| `vigilante://spans` | Summary of all request spans — method, path, status, event count |
| `vigilante://events` | Full event buffer |
| `vigilante://context/stack` | Current / last-known call stack |

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

| Param | Type | Description |
| --- | --- |---|
| `question` | string | Natural language filter, or "all" to skip keywords |
| `spanId` | string | Filter to one request span (e.g. "http-3") |
| `since` | number | Events after this ID (incremental polling) |
| `from` / `to` | string | ISO timestamp range |
| `track` | string | Follow a key path through runtime (e.g. "user.balance") |
| `dataflow` | string | Trace data flow chain for a key path |
| `diff` | [string, string] | Compare two spans structurally |
| `format` | string | `flat` (default) or `tree` (nested call tree) |
| `limit` | number | Max events per query (default 50, max 500) |

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

```json
{
  "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.