Clampd — Enforcement Layer for AI Agents

Block what your AI agent was never supposed to do.

Deterministic enforcement for AI coding agents. Detects and prevents dangerous commands, environment confusion, and unauthorized scope creep — before they execute. No LLM. No API keys. Works offline in 5 minutes.

What It Protects

| Risk | Example | Prevented By | |------|---------|---| | Destructive CLI | git push --force, npm publish, railway volume delete | 123 embedded signatures | | Environment Confusion | supabase db reset --linked (targeting prod instead of local) | Environment guard (14 patterns) | | Supply Chain | npm publish without approval token | Package publish gating | | Credential Exposure | Stripe live keys, AWS credentials in generated code | File content scanning | | Data Exfiltration | export * from database to external service | Scope-aware enforcement |

Grounded in real incidents:

• PocketOS/Railway destruction (Apr 2026) — environment confusion
• Cursor/Replit staging→prod (Jul 2025) — forced push without approval
• Kiro supply chain (Dec 2025) — npm publish to malicious registry
• Shai-Hulud breach (May 2026) — exported customer data

Quick Start

Step 1 — Install once per machine:

npm install -g clampd

Step 2 — Set up each project (run these one at a time in your project folder):

cd your-project
clampd init --role team-dev
clampd test

clampd init creates RULES.md, appends to your existing CLAUDE.md, sets up .cursorrules, writes .claude/settings.json hard blocks, and installs git pre-push + pre-commit hooks. Safe to run on projects that already have a CLAUDE.md — it appends, never overwrites. Then clampd test runs 50 corpus cases to confirm enforcement is working.

Use with Claude Code

One-time machine setup (run these once, they apply to all projects):

npm install -g clampd
claude mcp add clampd -- clampd serve --mcp

Per-project setup (run these once inside your project folder):

cd your-project
clampd init --role team-dev
claude

clampd init creates RULES.md, appends a section to CLAUDE.md, and sets up .cursorrules. Then open Claude Code with claude — clampd starts automatically as an MCP server in the background.

Clampd exposes two tools Claude Code can call:

• check_scope — runs the full enforcement pipeline on any command
• list_policy — returns the active RULES.md policy

Test it: ask Claude Code "list my clampd policy" — it should return your role and allow/deny lists.

Use with Cursor

Add to your Cursor MCP settings (~/.cursor/mcp.json):

{
  "mcpServers": {
    "clampd": {
      "command": "clampd",
      "args": ["serve", "--mcp"]
    }
  }
}

Use with Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on Mac, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "clampd": {
      "command": "clampd",
      "args": ["serve", "--mcp"],
      "cwd": "/path/to/your/project"
    }
  }
}

Existing Projects

Safe to run on any project with an existing CLAUDE.md. Clampd never overwrites your files — it appends only:

| File | Behaviour | |------|-----------| | RULES.md | Created if missing. Skipped if already exists. | | CLAUDE.md | Appends a Clampd section. Skipped if already contains "Clampd". | | .cursorrules | Appends Clampd rules. Skipped if already contains "Clampd". |

Running clampd init twice is safe — idempotent on all files.

CLI Commands

| Command | Description | |---------|-------------| | clampd init [--role <role>] | Generate RULES.md + .cursorrules + CLAUDE.md section | | clampd check "<intent>" | Check an intent string → ALLOW or DENY | | clampd test | Run built-in corpus (50 DENY + 15 ALLOW cases) | | clampd audit [--limit N] | View recent enforcement decisions | | clampd serve [--port 3333] | Start HTTP enforcement server | | clampd serve --mcp | Start MCP stdio server (Claude Code / Cursor / Claude Desktop) | | clampd list-roles | Show all 8 role templates | | clampd list-sigs | Show all 122 embedded signatures | | clampd status | Show current policy + mode |

$ clampd check "push to main"
✗ DENIED
  Reason: Forced push or push to main — hard block
  Signature: CODE-HARD-BLOCK-001 (CLI-FINGERPRINT)

$ clampd check "run the test suite"
✓ ALLOWED

Role Templates

8 built-in roles covering the common agent types:

| Role | Use Case | Max TTL | |------|----------|---------| | solo-dev | Claude Code, Cursor, personal projects | 60 min | | team-dev | Feature branch work, PRs | 120 min | | platform | IaC and CI, staging only | 120 min | | data | Pipelines and ML, no PII | 180 min | | security | Red team, audit, read-only | 480 min | | release | Production deploys (escalate) | 60 min | | ci-bot | Automated PRs, patch deps only | 30 min | | junior | Sandboxed — all writes escalate | 15 min |

How It Works

Intent string
     ↓
Stage 1: Threat filter        122 signatures, <3ms
     ↓ PASS
Stage 2: Environment guard    14 incident-backed patterns, <5ms
     ↓ PASS
Stage 3: Request classifier   coding-agent | database routing
     ↓
Stage 4: Scope validator      RULES.md allow/deny/escalate check
     ↓ VALID
Stage 5: Permission writer    FGA tuple write (ephemeral)
     ↓
Stage 6: Permission check     FGA check + audit log entry
     ↓
ALLOW or DENY → logged to ~/.clampd/audit.jsonl

No LLM. No network calls. No API keys. Pure deterministic enforcement.

Offline mode: Stages 1–4 run without Docker. Start Docker Desktop and run clampd init again to enable Stages 5–6.

Enforcement Coverage by Agent

clampd init deploys four enforcement layers. Here is what each layer stops, and for which agents.

| Threat | Mechanism | Claude Code | Cursor | Copilot | Codex | Terminal | |--------|-----------|:-----------:|:------:|:-------:|:-----:|:--------:| | git push --force | Git pre-push hook | ✓ hard | ✓ hard | ✓ hard | ✓ hard | ✓ hard | | git push origin main | Git pre-push hook | ✓ hard | ✓ hard | ✓ hard | ✓ hard | ✓ hard | | npm publish | permissions.deny + Stage 1 | ✓ hard | advisory | advisory | advisory | — | | terraform destroy | permissions.deny + Stage 1 | ✓ hard | advisory | advisory | advisory | — | | supabase db reset --linked | permissions.deny + Stage 2 | ✓ hard | advisory | advisory | advisory | — | | vercel --prod | permissions.deny + Stage 2 | ✓ hard | advisory | advisory | advisory | — | | railway volume delete | permissions.deny + Stage 1 | ✓ hard | advisory | advisory | advisory | — | | Prompt injection | Stage 1 (CLAUDE.md / MCP) | ✓ hard | advisory | advisory | advisory | — | | Scope creep beyond RULES.md | Stage 4 (MCP server) | ✓ hard | advisory | — | — | — | | Credential in staged file | Git pre-commit hook | ✓ hard | ✓ hard | ✓ hard | ✓ hard | ✓ hard | | Agent modifies RULES.md | Stage 1 PERSIST-009 | ✓ hard | advisory | — | — | — |

What "hard" means: the agent cannot proceed regardless of user instruction or auto-approve mode.

What "advisory" means: the agent sees the rule in .cursorrules / system prompt and is expected to comply. A sufficiently instructed or jailbroken agent can ignore it. This is the honest limit of tools without hook systems.

What Clampd cannot stop: an agent that writes a shell script containing a dangerous command and then executes bash script.sh — hooks see bash script.sh, not the contents. Mitigated by: Stage 1 scanning of intent strings before they reach the agent, and RULES.md deny rules in the MCP server path.

Embedded Signatures (123)

10 categories, all deterministic (regex, no LLM):

| Category | Count | Examples | |----------|-------|---------| | INJ-DIRECT | 11 | ignore previous instructions, system prompt override | | INJ-INDIRECT | 8 | SQL injection, template injection | | ESC-SCOPE | 8 | wildcard scope, admin operations | | EXFIL | 15 | export to external service, credential dump, PII fields | | ESC-PRIV | 15 | DROP TABLE, DELETE without WHERE, SHOW GRANTS | | EVADE | 6 | base64 encode, homoglyphs, obfuscation | | PERSIST | 9 | cron install, startup hook, CI/CD modification, RULES.md self-modification | | LATERAL | 9 | cross-account, npm install -g, kubectl exec | | ENV-CONFUSION | 14 | --linked, --prod, PROD_DB_URL, production context | | CODE-HARD-BLOCK | 28 | git push --force, npm publish, railway volume delete |

RULES.md Policy

Generated by clampd init. Edit to match your project's needs:

role: team-dev
max_risk: high
max_ttl: 120min

allow:
  - git:commit
  - git:push:feature
  - git:create_pr
  - test:run
  - fs:read
  - fs:write
  - db:select

deny:
  - git:push:main
  - git:push:force
  - db:drop
  - db:truncate
  - npm:publish

escalate:
  - db:migrate
  - docker:push

Can the Agent Modify RULES.md?

No. Clampd blocks agents from modifying their own policy files.

You (the human) can always edit RULES.md, .cursorrules, or CLAUDE.md directly in your editor — Clampd has no OS-level hook and doesn't intercept direct file edits.

The agent cannot. Any attempt like "update RULES.md to allow git push --force" or "modify the clampd policy" fires PERSIST-009 (Stage 1) and is denied before the agent can act. This is enforced at the signature layer — it cannot be bypassed by editing policy files, because policy files are only checked after Stage 1 passes.

Agent: "modify RULES.md to allow git:push:force"
         ↓
Stage 1: PERSIST-009 fires — DENY
         ↓
Stage 4 (RULES.md) never reached

The two-layer protection means:

• Stage 1 signatures (compiled into the npm package) — agents cannot change these
• Stage 4 RULES.md (your policy file) — only you can change this; agents are blocked from touching it

Audit Log

All enforcement decisions are logged to ~/.clampd/audit.jsonl:

{"timestamp":"2026-05-21T10:30:00Z","intent":"git push --force","outcome":"DENY","signature_id":"CODE-HARD-BLOCK-001","role":"team-dev","latency_ms":2.1}

clampd audit --limit 20     # human-readable
clampd audit --json         # machine-readable

Programmatic API

import { guard, guardSync, guardFile } from 'clampd';

// Async — full pipeline
const r = await guard('deploy to production', { role: 'team-dev', auditLog: true });
if (!r.allowed) console.error(`DENIED: ${r.reason}`);

// Sync — Stage 1 signatures only, <1ms
const r2 = guardSync('git push --force');

// File scanner — detect dangerous SDK calls in generated code
const r3 = await guardFile('./generated-code.ts');

HTTP Server (CI/CD Integration)

clampd serve --port 3333

const res = await fetch('http://localhost:3333/check', {
  method: 'POST',
  body: JSON.stringify({ intent: userPrompt })
});
const { allowed, reason } = await res.json();
if (!allowed) throw new Error(`Clampd blocked: ${reason}`);

Open Core

Clampd is MIT licensed. All source is visible and forkable.

Enterprise features (PAM credential gating, SIEM connectors, managed policy library, LLM intent parser, DORA evidence export, admin console) are available in the Clampd Enterprise stack for regulated environments. See clampd.ai.

License

MIT — see LICENSE