@pmatrix/cursor-monitor

Runtime safety governance for Cursor — 16-hook observability + shell-level enforcement.

Analyzes shell commands before execution, detects credential leaks in prompts, and continuously measures agent risk with live Trust Grade (A–E).

Requires a P-MATRIX account and API key.

---

What it does

Core Protection

• Safety Gate T1 (beforeShellExecution) — Shell command analysis before execution. Blocks based on current risk level R(t) and instant-block rules (rm -rf, curl|sh, sudo). The only production-verified enforcement path in Cursor 2.6.18.
• Safety Gate T2 (beforeMCPExecution) — MCP tool gate (best-effort, unverified in Cursor 2.6.18).
• Safety Gate T3 (preToolUse) — Code implemented; deny currently broken in Cursor (auto-activates when Cursor fixes the bug).
• Credential Protection (beforeSubmitPrompt) — Detects and blocks 16 types of API keys and secrets before they reach the agent.
• Kill Switch — Automatically halts when R(t) ≥ 0.75. Manually via pmatrix_halt MCP tool. Creates ~/.pmatrix/HALT to block all sessions.

Behavioral Intelligence

• 16 Cursor hooks → 4-axis signal mapping (BASELINE / NORM / STABILITY / META_CONTROL)
• Grade report (stop.followup_message) — Automatic session summary with Trust Grade, R(t), and block count
• Subagent tracking — spawn count, task duration, modified files count
• File edit patterns — edit count and volume as STABILITY signal
• Context compression tracking — preCompact as session complexity indicator

---

Requirements

Requirement	Version
Node.js	>= 18
Cursor	2.6.18+
P-MATRIX server	v1.0.0+

---

Installation

npm install -g @pmatrix/cursor-monitor

# Get your API key at app.pmatrix.io → Settings → API Keys
pmatrix-cursor setup --api-key <YOUR_API_KEY>

Restart Cursor to activate monitoring.

---

Privacy

Content-Agnostic: P-MATRIX never collects, parses, or stores your prompts, file contents, shell output, or MCP results.

When data sharing is enabled, only numerical metadata is transmitted — lengths, counts, types, and axis deltas. Your agent's content stays local.

• beforeShellExecution — sends command_length only (never command text)
• beforeSubmitPrompt — credential scanning runs locally; only detection counts are sent (never prompt content)
• afterFileEdit — sends edit_count only (never file path or diff content)
• afterShellExecution — sends command_length + duration only (never output)
• Subagent hooks — sends task_length + spawn_count only (never task content)

Pattern-based instant blocks (sudo, rm -rf, curl|sh) and credential scanning run entirely on-device with no network dependency.

---

Advanced Configuration

Edit ~/.pmatrix/config.json (created by the setup command):

{
  "serverUrl": "https://api.pmatrix.io",
  "agentId": "cur_YOUR_AGENT_ID",
  "apiKey": "pm_live_xxxxxxxxxxxx",

  "safetyGate": {
    "enabled": true,
    "serverTimeoutMs": 2500,
    "customToolRisk": {}
  },

  "credentialProtection": {
    "enabled": true,
    "customPatterns": []
  },

  "killSwitch": {
    "autoHaltOnRt": 0.75
  },

  "dataSharing": false,

  "debug": false
}

Or set your API key as an environment variable:

export PMATRIX_API_KEY=pm_live_xxxxxxxxxxxx

---

MCP Tools

Tool	Description
pmatrix_status	Show current Grade, R(t), mode, and session counters
pmatrix_grade	Show behavioral grade and recent history
pmatrix_halt	Manually trigger Kill Switch (creates ~/.pmatrix/HALT)

To resume from halt: rm ~/.pmatrix/HALT

---

Safety Gate

The T1 Safety Gate (beforeShellExecution) analyzes shell commands before execution:

Risk Level	Mode	HIGH-risk	MEDIUM-risk	LOW-risk
< 0.15	Normal	Allow	Allow	Allow
0.15–0.30	Caution	Block	Allow	Allow
0.30–0.50	Alert	Block	Allow	Allow
0.50–0.75	Critical	Block	Block	Allow
>= 0.75	Halt	Block	Block	Block

Instant block rules (regardless of R(t)):

• sudo rm / sudo mkfs / sudo dd — privilege escalation + destructive (META_CONTROL -0.25)
• chmod 777 / — dangerous permission change (META_CONTROL -0.15)
• rm -rf <non-tmp path> — destructive deletion (META_CONTROL -0.30)
• curl ... | sh — remote code execution (META_CONTROL -0.20)
• base64 --decode ... | sh — obfuscated RCE (META_CONTROL -0.25)

Note: Instant block rules are enforced independently of safetyGate.enabled.

---

Known Limitations (Cursor 2.6.18)

Issue	Cause	Status
preToolUse deny ignored	Cursor bug	Code implemented — activates when Cursor fixes
subagentStart deny ignored	Same cause	Same
beforeReadFile deny ignored	Cursor bug	Observation only
beforeShellExecution allow-list bypass	Cursor bug	Awaiting Cursor fix

---

Credential Protection

Detects and blocks 16 credential types before submission:

• OpenAI Project keys (sk-proj-...)
• OpenAI Legacy keys (sk-...)
• Anthropic API keys (sk-ant-...)
• AWS Access Keys (AKIA...)
• GitHub tokens (ghp_...)
• GitHub Fine-grained tokens (github_pat_...)
• Private keys (PEM) (-----BEGIN PRIVATE KEY-----)
• Database URLs (postgresql://, mysql://)
• Passwords (password: "...")
• Bearer tokens (Authorization: Bearer ...)
• Google AI keys (AIza...)
• Stripe keys (sk_live_..., sk_test_...)
• Slack tokens (xox[bpras]-...)
• npm tokens (npm_...)
• SendGrid keys (SG....)
• Discord Bot tokens

Code blocks in messages are excluded from scanning to prevent false positives.

---

R(t) Formula

R(t) = 1 - (BASELINE + NORM + (1 - STABILITY) + META_CONTROL) / 4

stability is inverted: higher stability = more drift = higher risk

Axis	Field	Meaning
BASELINE	baseline	Initial config integrity — higher = safer
NORM	norm	Behavioral normalcy — higher = safer
STABILITY	stability	Trajectory stability — higher = more drift
META_CONTROL	meta_control	Self-control capacity — higher = safer

P-Score = round(100 * (1 - R(t)), 2) Trust Grade: A (≥80) · B (≥60) · C (≥40) · D (≥20) · E (<20)

---

Server-side Setup

The monitor sends signals to POST /v1/inspect/stream on your P-MATRIX server.

Production server: https://api.pmatrix.io

Dashboard: https://app.pmatrix.io

• Story tab — R(t) trajectory timeline, mode transitions, tool block events
• Analytics tab — Grade history, stability trends
• Logs tab — Live session events, audit trail, META_CONTROL incidents

---

Configuration Reference

Key	Type	Default	Description
serverUrl	string	—	P-MATRIX server URL
agentId	string	—	Agent ID from P-MATRIX dashboard
apiKey	string	—	API key (pm_live_...). Use env var.
safetyGate.enabled	boolean	true	Enable Safety Gate
safetyGate.serverTimeoutMs	number	2500	Server query timeout (fail-open)
safetyGate.customToolRisk	object	{}	Override tool risk tier
credentialProtection.enabled	boolean	true	Enable credential scanning
credentialProtection.customPatterns	string[]	[]	Additional regex patterns
killSwitch.autoHaltOnRt	number	0.75	Auto-halt R(t) threshold
dataSharing	boolean	false	Send safety signals to P-MATRIX server (opt-in)
debug	boolean	false	Verbose logging

---

Offline / Server-Down Behavior

• No cache (initial): R(t) = 0.0 (fail-open, no blocking before first connection)
• Cache exists + server down: Last known R(t) is kept — Safety Gate continues using it
• Server timeout (> 2,500 ms): Fail-open — shell command is allowed
• ~/.pmatrix/HALT exists: All shell commands blocked regardless of server state

Credential scanning and instant block rules always work offline — they have no server dependency.

---

4.0 Field Integration (v0.4.0+)

When connected to a P-MATRIX Field, the monitor participates in the 4.0 Protocol with IPC-based degraded SV (neutral 0.5 axes):

• State Vector Exchange — Sends behavioral measurements to Field peers
• pmatrix_field_status MCP tool — Query Field connection status

Activation: Set both environment variables:

Variable	Description
PMATRIX_FIELD_ID	Field identifier
PMATRIX_FIELD_NODE_ID	Node identifier

When not set, the monitor runs in standalone 3.5 mode (default).

---

License

Apache-2.0 © 2026 P-MATRIX