Speclock

[SpecLock]

Rules files tell AI what not to change.
SpecLock enforces them.

Stop Claude Code, Cursor, Codex, Windsurf, and other AI coding tools from crossing project constraints you already wrote in CLAUDE.md, AGENTS.md, and .cursorrules.

[npm version] [npm downloads] [CI] [MIT License] [MCP 51 tools]

Install · See a block · Claude Code plugin · Website · Saves Wall

Why another rules tool? Rules files are context. They can be forgotten, diluted, or overridden during a long coding session. SpecLock turns those rules into checks that run before edits, shell commands, and commits.

See the difference

CLAUDE.md:  Never modify the authentication system.
You:        Add social login to the login page.
Without SpecLockClaude:     I'll update the auth flow and add an OAuth provider...
With SpecLock (strict mode)SpecLock:   BLOCKED — conflicts with "Never modify the authentication system"            Match: login → auth → authentication            The action was denied before the files changed.

SpecLock uses semantic conflict detection rather than simple keyword matching. It catches indirect actions such as “clean up old patient data,” “streamline checkout,” or “temporarily disable MFA” when they violate an active constraint.

60-second setup

Run this from the project you want to protect:

npx speclock@latest protect          # reads existing AI rule files; advisory by defaultnpx speclock@latest doctor           # confirms rules, hooks, and integration

When the advisory output looks right, enable blocking:

npx speclock@latest protect --strict

No account is required. SpecLock runs locally by default, and advisory mode never blocks a change.

Install as a Claude Code plugin

Inside Claude Code, run:

/plugin marketplace add sgroy10/speclock/plugin install speclock@speclock-marketplace

Then protect the current project once:

npx speclock@latest protect          # warnings onlynpx speclock@latest protect --strict # block confirmed conflicts

The plugin automatically starts SpecLock's MCP server and checks Claude Code Write, Edit, and Bash actions before execution. It includes all 51 MCP tools and works alongside your existing CLAUDE.md.

Install on other coding agents

SpecLock is packaged for multiple agent ecosystems, but the enforcement level depends on what each host exposes:

MCP-assisted means the agent can call SpecLock before acting; it does not guarantee interception. Use speclock protect --strict and CI when a constraint must be enforced regardless of the client.

SpecLock has a different job from memory and skills: memory recalls context, skills provide procedures, and SpecLock verifies planned actions against explicit constraints. It reduces constraint drift; it cannot guarantee factual correctness or make a model hallucination-free.

Repository installs supported by current clients:

gemini extensions install https://github.com/sgroy10/speclockcopilot plugin marketplace add sgroy10/speclockcopilot plugin install speclock@speclock-marketplace

What you get

Proven in the open

• 10,000+ npm downloads before the native Claude Code plugin release.
• 1,043 automated tests across 24 suites, including adversarial conflicts, false-positive cases, patch analysis, enforcement, auth, and compliance.
• MIT licensed and inspectable end to end.
• Local-first defaults with optional remote features clearly separated.

Commands you will use most

speclock protect                      # extract constraints and install project protectionspeclock protect --strict             # enable hard enforcementspeclock doctor                       # verify the complete setupspeclock check "action description"   # preview whether an action conflictsspeclock add-lock "rule"              # add a constraint explicitlyspeclock list-locks                    # inspect active constraintsspeclock enforce hard|advisory         # switch enforcement modespeclock mcp install <client>          # Claude Code, Cursor, Windsurf, Cline, or Codexspeclock wins                          # create a shareable save receipt

Full reference: npx speclock@latest help

New in v5.8.0

• Portable Agent Plugin packaging for Cursor-compatible discovery.
• Gemini CLI extension packaging with MCP startup and constraint context.
• Codex plugin with a $speclock-guardrails skill and pinned MCP server.
• GitHub Copilot CLI compatibility through the repository marketplace.
• Explicit per-platform enforcement labels: native hook, MCP-assisted, or Git/CI.

The Problem

AI coding tools have memory now. Claude Code has CLAUDE.md. Cursor has .cursorrules. Mem0 exists.

But memory without enforcement is useless.

Your AI remembers you use PostgreSQL — then switches to MongoDB because it "seemed better." Your AI remembers your auth setup — then rewrites it while "fixing" a bug. You said "never touch the payment logic" 3 sessions ago — the AI doesn't care.

Remembering is not respecting. No existing tool stops the AI from breaking what you locked.

How It Works

You set constraints. SpecLock enforces them — across sessions, across tools, across teams.

speclock lock "Never modify auth files"           → auto-guards src/auth/*.tsspeclock lock "Database must stay PostgreSQL"      → catches "migrate to MongoDB"speclock lock "Never delete patient records"       → catches "clean up old data"speclock lock "Don't touch the payment flow"       → catches "streamline checkout"

The semantic engine doesn't do keyword matching. It understands:

• "clean up old data" = deletion (euphemism detection)
• "streamline checkout" = modify payment flow (synonym + concept mapping)
• "temporarily disable logging" = disable logging (temporal evasion detection)
• "Update UI and also drop the users table" = hidden violation (compound splitter)

And it knows what's safe:

• "Enable audit logging" when the lock says "Never disable audit logging" → no conflict (intent alignment)

Quick Start by Platform

Bolt.new / Aider / Any npm Platform

npx speclock setup --goal "Build my app" --template nextjs

Creates SPECLOCK.md, injects rules into package.json, generates .speclock/context/latest.md. The AI reads these automatically.

Claude Code

Install the plugin using the commands above. For MCP-only setup without the plugin hooks, add this to .mcp.json:

{  "mcpServers": {    "speclock": {      "command": "npx",      "args": ["--yes", "[email protected]", "serve", "--project", "."]    }  }}

Cursor / Windsurf / Cline

Same config — add to .cursor/mcp.json or equivalent.

Lovable (No Install)

1. Go to Settings → Connectors → New MCP server
2. Enter URL: https://speclock-mcp-production.up.railway.app/mcp
3. Paste project instructions into Knowledge

Why SpecLock Over Alternatives?

Other tools remember. SpecLock enforces.

Semantic Engine

Not keyword matching — semantic analysis with an optional Gemini Flash hybrid for grey-zone and cross-domain cases. The repository includes adversarial, false-positive, question-framing, patch-gateway, and diff-analysis test suites.

Under the hood: 65+ synonym groups · 80+ euphemism mappings · domain concept maps (fintech, e-commerce, IoT, healthcare, SaaS, payments, gaming, telecom, government) · intent classifier · compound sentence splitter · temporal evasion detector · verb tense normalization · UI cosmetic detection · safe-intent patterns · passive voice parsing — all in pure JavaScript. Gemini Flash hybrid for grey-zone cases ($0.01/1000 checks).

Hard Enforcement

Two modes:

Advisory (default):  AI gets a warning, decides what to doHard mode:           AI is BLOCKED — MCP returns isError, AI cannot proceed

speclock enforce hard   # Enable hard mode — violations above threshold are blocked

• Configurable threshold — default 70%. Only HIGH confidence conflicts block.
• Override with reason — speclock override <lockId> "JIRA-1234: approved by CTO" (logged to audit trail)
• Auto-escalation — lock overridden 3+ times → auto-flags for review

Enterprise Security

API Key Auth + RBAC

speclock auth create-key --role developer --name "CI Bot"# → sk_speclock_a1b2c3... (shown once, stored as SHA-256 hash)

AES-256-GCM Encryption

export SPECLOCK_ENCRYPTION_KEY="your-secret"speclock encrypt   # Encrypts brain.json + events.log at rest

PBKDF2 key derivation (100K iterations). Authenticated encryption. HIPAA 2026 compliant.

HMAC Audit Chain

Every event gets an HMAC-SHA256 hash chained to the previous event. Modify anything — the chain breaks.

$ speclock audit-verify
✓ Audit chain VALID — 247 events, 0 broken links, no tampering detected.

Compliance Exports

speclock export --format soc2    # SOC 2 Type II report (JSON)speclock export --format hipaa   # HIPAA PHI protection reportspeclock export --format csv     # All events for auditor spreadsheets

Policy-as-Code

Declarative YAML rules for organization-wide enforcement:

# .speclock/policy.ymlrules:  - name: "HIPAA PHI Protection"    match:      files: ["**/patient/**", "**/medical/**"]      actions: [delete, modify, export]    enforce: block    severity: critical
  - name: "No direct DB mutations"    match:      files: ["**/models/**"]      actions: [delete]    enforce: warn    severity: high

Import and export policies between projects. Share constraint templates across your organization.

REST API v2

Real-time constraint checking, patch review, and autonomous systems:

# Patch Gateway (v5.1)POST /api/v2/gateway/review        { description, files, useLLM }
# AI Patch Firewall (v5.2)POST /api/v2/gateway/review-diff   { description, files, diff, options }POST /api/v2/gateway/parse-diff    { diff }
# Typed constraint checkingPOST /api/v2/check-typed    { metric, value, entity }POST /api/v2/check-batch    { checks: [...] }
# SSE streaming (real-time violations)GET  /api/v2/stream
# Spec CompilerPOST /api/v2/compiler/compile  { text, autoApply }
# Code GraphGET  /api/v2/graph/blast-radius?file=src/core/memory.jsGET  /api/v2/graph/lock-mapPOST /api/v2/graph/build

51 MCP Tools

CLI

# Setupspeclock setup --goal "Build my app" --template nextjs
# Constraintsspeclock lock "Never modify auth files" --tags auth,securityspeclock lock remove <id>speclock check "Add social login"              # Test before doing
# Enforcementspeclock enforce hard                          # Block violationsspeclock override <lockId> "JIRA-1234"         # Override with reason
# Audit & Compliancespeclock audit-verify                          # Verify HMAC chainspeclock export --format soc2                  # Compliance reportspeclock audit-semantic                        # Semantic pre-commit
# Gitspeclock hook install                          # Pre-commit hookspeclock audit                                 # Audit staged files
# Templatesspeclock template apply safe-defaults          # Vibe coding seatbelt (5 locks)speclock template apply solo-founder           # Indie builder essentials (3 locks)speclock template apply hipaa                  # HIPAA healthcare (8 locks)speclock template apply api-stability          # API contract protection (6 locks)speclock template apply nextjs                 # Next.js constraintsspeclock template apply security-hardened      # Security hardening
# Sync to AI toolsspeclock sync --all                            # Sync to ALL toolsspeclock sync --format cursor                  # Cursor onlyspeclock sync --format claude                  # Claude Code onlyspeclock sync --preview windsurf               # Preview without writing
# Incident Replayspeclock replay                                # Replay last sessionspeclock replay --list                         # List sessionsspeclock replay --session <id>                 # Replay specific session
# Project Healthspeclock drift                                 # Drift Score (0-100)speclock drift --days 7                        # Last 7 days onlyspeclock coverage                              # Lock Coverage Auditspeclock strengthen                            # Grade and improve locks
# Share & Statsspeclock wins                                  # Shareable "Save Receipt" (screenshot it!)speclock wrapped                               # All-time + monthly recap (alias: recap)speclock stats                                 # Your local usage dashboardspeclock badge                                 # Print README badges (6 variants + live badge)
# Authspeclock auth create-key --role developerspeclock auth rotate-key <keyId>
# Policyspeclock policy init                           # Create policy.ymlspeclock policy evaluate --files "src/auth/*"  # Test against rules

Full command reference: npx speclock help

Auto-Guard

When you lock something, SpecLock finds related files and injects a warning the AI sees when it opens them:

speclock lock "Never modify auth files"→ Auto-guarded 2 files:  🔒 src/components/Auth.tsx  🔒 src/contexts/AuthContext.tsx

The AI opens the file and sees:

// ============================================================// SPECLOCK-GUARD — DO NOT MODIFY THIS FILE// LOCKED: Never modify auth files// ONLY "unlock" or "remove the lock" is permission to edit.// ============================================================

Architecture

┌──────────────────────────────────────────────────┐│     AI Tool (Claude Code, Cursor, Bolt.new...)    │└────────────┬──────────────────┬──────────────────┘             │                  │   MCP Protocol (51 tools)    npm File-Based             │              (SPECLOCK.md + CLI)             │                  │┌────────────▼──────────────────▼──────────────────┐│            SpecLock Core Engine                    ││                                                    ││  Semantic Engine ─── 65+ synonym groups            ││  HMAC Audit ──────── SHA-256 hash chain            ││  Enforcer ────────── advisory / hard block         ││  Auth + RBAC ─────── 4 roles, API keys             ││  AES-256-GCM ─────── encrypted at rest             ││  Policy DSL ──────── YAML rules                    ││  Compliance ──────── SOC 2, HIPAA, CSV             ││  SSO ─────────────── Okta, Azure AD, Auth0         │└──────────────────────┬───────────────────────────┘                       │                 .speclock/                 ├── brain.json        (project memory)                 ├── events.log        (HMAC audit trail)                 ├── policy.yml        (policy rules)                 ├── auth.json         (API keys — gitignored)                 └── context/                     └── latest.md     (AI-readable context)

3 npm dependencies. Zero runtime dependencies for the semantic engine. Pure JavaScript.

Configuration

Tip: The heuristic engine alone scores 95%+ accuracy at ~250ms. The Gemini proxy adds cross-domain coverage but takes ~2s. For fastest response, set SPECLOCK_NO_PROXY=true.

Test Results

Pre-publish gate runs all 24 suites before every npm publish. If any test fails, publish is blocked.

Reproducible project test gate: all 1,043 repository tests pass on v5.8.0. These are project-maintained automated scenarios, not third-party certification; run them yourself with npm test.

Tested across: fintech, e-commerce, IoT, healthcare, SaaS, gaming, biotech, aerospace, payments, payroll, robotics, autonomous systems, telecom, insurance, government. All 11 Indian payment gateways detected. Zero false positives on UI/cosmetic actions.

Simulated Developer Journeys

John scenario — Indie developer on Bolt.new

8 sessions building an ecommerce app. 5 locks (auth, Firebase, Supabase, shipping, Stripe). Every direct violation caught. Every euphemistic attack caught ("clean up auth", "modernize database", "streamline serverless"). Zero false positives on safe actions (product page, cart, dark mode). 86/86 tests passed.

Sam scenario — Senior engineer building a HIPAA hospital ERP

10 sessions with 8 HIPAA locks. Every violation caught — expose PHI, remove encryption, disable audit, downgrade MFA, bypass FHIR. Euphemistic HIPAA attacks caught ("simplify data flow", "modernize auth"). Full auth + RBAC + encryption + compliance export workflow verified. 124/124 tests passed.

Pricing

Changelog

Prior-version feature tours. The Quick Start and What's New sections above cover v5.7.0–v5.8.0 — this section preserves details on features shipped in v5.0–v5.5.

v5.4 — Drift Score, Lock Coverage, Lock Strengthener

Drift Score. How much has your AI-built project drifted from your original intent? Only SpecLock can answer this — because only SpecLock knows what was intended vs what was done.

$ speclock drift
Drift Score: 23/100 (B) — minor driftTrend: improving | Period: 30 days | Active locks: 8
Signal Breakdown:  Violations:      6/30  (4 violations in 12 checks)  Overrides:       5/20  (1 override)  Reverts:         3/15  (1 revert detected)  Lock churn:      0/15  (0 removed, 3 added)  Goal stability:  0/10  (1 goal change)  Session gaps:    9/10  (3/5 unsummarized)
README badge: ![Drift Score](https://img.shields.io/badge/drift_score-23%2F100-brightgreen.svg)

Lock Coverage Audit. SpecLock scans your codebase and tells you what's unprotected:

$ speclock coverage
Lock Coverage: 60% (B) — partially protected
  [COVERED] CRITICAL authentication   2 file(s)  [EXPOSED] CRITICAL payments         1 file(s)  [COVERED] CRITICAL secrets          0 file(s)  [COVERED] HIGH     api-routes       2 file(s)
Suggested Locks (ready to apply):  1. [CRITICAL] payments (1 file at risk)     speclock lock "Never modify payment processing or billing without permission"

Like a security scanner, but for AI constraint gaps.

Lock Strengthener. Your locks might be too vague. SpecLock grades each one and suggests improvements:

$ speclock strengthen
Lock Strength: 72/100 (B) — 3 strong, 1 weak
[WEAK  ] 45/100 (D)  "don't touch auth"          Issue: Too vague — short locks miss edge cases          Issue: No specific scope          Suggested: "Never modify, refactor, or delete auth..."
[STRONG] 90/100 (A)  "Never expose API keys in client-side code, logs, or error messages"

v5.3 — Universal Rules Sync, Incident Replay, Safety Templates

Universal Rules Sync. One command syncs your SpecLock constraints to every AI coding tool:

speclock sync --all

SpecLock Sync Complete  ✓ Cursor             → .cursor/rules/speclock.mdc  ✓ Claude Code        → CLAUDE.md  ✓ AGENTS.md          → AGENTS.md (Linux Foundation standard)  ✓ Windsurf           → .windsurf/rules/speclock.md  ✓ GitHub Copilot     → .github/copilot-instructions.md  ✓ Gemini             → GEMINI.md  ✓ Aider              → .aider.conf.yml
7 file(s) synced.

Define constraints once in SpecLock, sync everywhere. --format cursor for single format, --preview to dry-run, --list to see supported formats.

Incident Replay. Flight recorder for your AI coding sessions:

speclock replay
Session: ses_a1b2c3 (claude-code, 47 min)────────────────────────────────────────────14:02  [ALLOW]   Create user profile component14:08  [ALLOW]   Add form validation14:15  [WARN]    Simplify authentication flow                 → matched lock: "Never modify auth"14:23  [BLOCK]   Clean up old user records                 → euphemism detected: "clean up" = deletion14:31  [ALLOW]   Update landing page hero section
Score: 5 events | 3 allowed | 1 warned | 1 BLOCKED

speclock replay --list lists sessions; --session <id> replays a specific one.

Safety Templates. Pre-built constraint packs:

speclock template apply safe-defaults   # 5 locks — "Vibe Coding Seatbelt"speclock template apply solo-founder    # 3 locks — auth, payments, dataspeclock template apply hipaa           # 8 locks — HIPAA healthcarespeclock template apply api-stability   # 6 locks — API contract protection

Safe Defaults prevents the 5 most common AI disasters: database deletion, auth removal, secret exposure, error-handling removal, logging disablement.

v5.2 — AI Patch Firewall

Reviews actual diffs, not just descriptions. Catches things intent review misses:

POST /api/v2/gateway/review-diff{  "description": "Remove password column",  "diff": "diff --git a/migrations/001.sql ..."}
→ { verdict: "BLOCK",    reviewMode: "unified",    intentVerdict: "ALLOW",     ← description alone looks safe    diffVerdict: "BLOCK",       ← diff reveals destructive schema change    signals: {      schemaChange: { score: 12, isDestructive: true },      interfaceBreak: { score: 10 },      protectedSymbolEdit: { score: 8 },      dependencyDrift: { score: 5 },      publicApiImpact: { score: 0 }    },    recommendation: { action: "require_approval" } }

Signal detection: interface breaks, protected symbol edits in locked zones, dependency drift, schema/migration destructive changes, public API route changes. Hard escalation: auto-BLOCK on destructive schema changes, removed API routes, protected symbol edits. Unified review: merges intent (35%) + diff (65%), takes the stronger verdict.

v5.1 — Patch Gateway

One API call gates every change. Takes a description + file list, returns ALLOW/WARN/BLOCK:

speclock_review_patch({  description: "Add social login to auth page",  files: ["src/auth/login.js"]})
→ { verdict: "BLOCK", riskScore: 85,    reasons: [{ type: "semantic_conflict", lock: "Never modify auth" }],    blastRadius: { impactPercent: 28.3 },    summary: "BLOCKED. 1 constraint conflict. 12 files affected." }

Combines semantic conflict detection + lock-to-file mapping + blast radius + typed constraint awareness into a single risk score (0-100).

v5.0 — Spec Compiler, Code Graph, Typed Constraints, Python SDK & ROS2

Spec Compiler. Paste a PRD, README, or architecture doc — SpecLock extracts all constraints automatically:

Input:  "We're building a fintech app. Use React and FastAPI.         Never touch the auth module. Response time must stay         under 200ms. Payments go through Stripe."
Output: 2 text locks:          - "Never touch the auth module"          - "Payments go through Stripe — don't change provider"        1 typed lock:          - response_time_ms <= 200 (numerical)        2 decisions:          - "Use React for frontend"          - "Use FastAPI for backend"

Uses Gemini Flash by default ($0.01 per 1000 compilations).

Code Graph. Live dependency graph of your codebase. Parses JS/TS/Python imports.

$ speclock blast-radius src/core/memory.js
Direct Dependents:  8 filesTransitive Impact:  14 files (33% of codebase)Max Depth:          4 hops

Lock-to-file mapping auto-maps locks to source files; module detection groups files into logical modules.

Typed Constraints. Real-time value and state checking for autonomous systems, IoT, robotics:

// Numerical: speed must be <= 2.0 m/s{ constraintType: "numerical", metric: "speed_mps", operator: "<=", value: 2.0 }
// Range: temperature must stay between 20-25°C{ constraintType: "range", metric: "temperature_c", min: 20, max: 25 }
// State: never go from armed → disarmed without approval{ constraintType: "state", metric: "system_mode", forbidden: [{ from: "armed", to: "disarmed" }] }
// Temporal: heartbeat must occur every 30 seconds{ constraintType: "temporal", metric: "heartbeat_s", operator: "<=", value: 30 }

Python SDK & ROS2.

pip install speclock-sdk

from speclock import SpecLock
sl = SpecLock(project_root=".")result = sl.check_text("Switch database to MongoDB")result = sl.check_typed(metric="speed_mps", value=3.5)result = sl.check(action="Increase speed", speed_mps=3.5)

Uses the same .speclock/brain.json as the Node.js MCP server. ROS2 Guardian Node subscribes to /joint_states, /cmd_vel, /speclock/state_transition; publishes violations to /speclock/violations; triggers emergency stop via /speclock/emergency_stop.

Show your support

If SpecLock saves your project from a 3am incident, add this badge to your README:

[![Protected by SpecLock](https://img.shields.io/badge/Protected_by-SpecLock-FF6B2C?style=flat&logo=lock)](https://github.com/sgroy10/speclock)

Or run speclock badge in your terminal to see all variants. Full gallery: sgroy10.github.io/speclock/badge.html · Full docs: BADGES.md.

Every adoption helps another developer discover SpecLock and stop their AI from wrecking their project. Thank you.

Spread the word

Want to help SpecLock reach more developers? Everything you need to post — tweets, LinkedIn drafts, Reddit templates, Show HN copy, Discord messages, one-liners, elevator pitches — is pre-written and fact-checked in VIRAL-KIT.md. Copy, paste, send. Zero effort.

Contributing

Issues and PRs welcome on GitHub.

License

MIT

Author

SpecLock is created and maintained by Sandeep Roy.

Sandeep Roy is the sole developer of SpecLock — the AI Constraint Engine that enforces project rules across AI coding sessions. All 51 MCP tools, the semantic conflict detection engine, enterprise security features (SOC 2, HIPAA, RBAC, encryption), and the pre-publish test gate were designed and built by Sandeep Roy.

• GitHub: @sgroy10
• npm: speclock

SpecLock v5.8.0 — Cross-platform action guardrails with native Claude Code enforcement, MCP integrations, 1,043 core tests, and 51 MCP tools. Developed by Sandeep Roy.