A local-first developer tool, CLI, and TypeScript engine that translates raw Git diffs into behavior-aware change reports, downstream blast-radius mapping, and deterministic risk scores (0–100). Native Model Context Protocol (MCP) server for Claude, Antigravity, Cursor, and Windsurf.

📑 Table of Contents

• ❓ Why Use Change Firewall?
  • The Core Problem (Intent vs Consequences)
  • Git Diff vs Change Firewall
• 🚀 Quick Start (Zero Install)
• 📦 Installation Options
• 🛠️ CLI Command Reference & Flags
  • 1. change-firewall (Default Analysis)
  • 2. change-firewall preflight (Merge Gate)
  • 3. change-firewall watch (Live Monitoring)
  • 4. change-firewall impact <file> (Blast Radius)
  • 5. change-firewall why <file> (Architectural Role)
  • 6. change-firewall open (Dashboard Server)
  • 7. change-firewall demo (Simulation Mode)
  • 8. change-firewall mcp (Model Context Protocol)
• 💻 Programmatic Node.js / TypeScript API
  • analyzeChanges()
  • evaluatePreflight()
  • computeBlastRadius()
  • startWatchMode()
  • createMcpServer() / startMcpServer()
• 🤖 AI Coding Agent Self-Correction Loop & MCP
  • 🔌 Model Context Protocol (MCP) Server Setup
  • 🤖 Direct Agent Instructions (Claude Code, OpenAI Codex, Copilot)
• 🔄 CI/CD & GitHub Actions Integration
• 🪝 Git Pre-Commit Hook (Husky)
• 🧪 Real-World Behavioral Scenarios
• 🛡️ Architecture & Deterministic Guarantees
• 🔒 Privacy & Local-First Philosophy
• 📄 License

❓ Why Use Change Firewall?

The Core Problem (Intent vs Consequences)

AI coding assistants (Cursor, Claude Code, GitHub Copilot, Devin, Antigravity) are rewriting software development. They can modify 20 files in under 5 seconds and report:

✓ Authentication added
✓ Tests passing
✓ Build successful

The summary tells you what the AI intended to do. It does not tell you:

• What existing behavior secretly mutated?
• What API response contracts silently broke for downstream consumers?
• Which database models, routes, or callers depend on the changed code?
• What permissions or security assumptions shifted?

Tests only verify what they were originally written to test. Standard Git diffs only show line additions and deletions (+1, -1), concealing architectural ripple effects.

Git Diff vs Change Firewall

Consider this innocent-looking change:

- return user;
+ return { user };

| Tool | What It Sees | Result | |---|---|---| | Git Diff | 1 line modified (+1, -1) | Looks tiny and harmless. Developer approves PR. | | Change Firewall | 🔴 HIGH RISK: API Response Contract Mutated• Endpoint: GET /api/user• Before: User• After: { user: User }• Blast Radius: 7 client consumers depend on this endpoint structure!• Action: Update client response deserializers or revert wrapper. | Catches the breaking change before staging or production crashes! |

🚀 Quick Start (Zero Install)

You do not need an account, an API key, or a cloud server. Run Change Firewall directly in any JavaScript or TypeScript Git repository:

npx change-firewall

Or analyze changes and open the interactive visual browser dashboard in one step:

npx change-firewall --open

📦 Installation Options

Option A: Zero-Install (npx — Recommended)

Always runs the latest version on demand without polluting node_modules:

npx change-firewall

Option B: Local Project Dependency

Install in your project to pin versioning for your team:

npm install --save-dev change-firewall
# or
pnpm add -D change-firewall
# or
yarn add -D change-firewall

Add convenience scripts to your package.json:

{
  "scripts": {
    "firewall": "change-firewall",
    "firewall:watch": "change-firewall watch",
    "preflight": "change-firewall preflight",
    "dashboard": "change-firewall open"
  }
}

Option C: Global Installation

npm install -g change-firewall
change-firewall

🛠️ CLI Command Reference & Flags

1. change-firewall (Default Analysis)

Analyzes uncommitted changes in your Git working tree.

# Standard terminal report
npx change-firewall

# Analyze and automatically open browser dashboard (http://localhost:4783)
npx change-firewall --open

# Analyze only staged changes (git add)
npx change-firewall --staged

# Compare against a specific base branch or commit (e.g., origin/main)
npx change-firewall --base origin/main

# Output machine-readable JSON (great for AI agents or scripts)
npx change-firewall --json

# Run dashboard on a custom port
npx change-firewall --open -p 5000

Flags:

| Flag | Description | Default | |---|---|---| | --open | Opens local browser dashboard automatically | false | | --json | Outputs report as raw JSON | false | | -s, --staged | Only inspect staged changes | false | | -b, --base <ref> | Base commit or branch to compare against | HEAD | | -p, --port <number> | Dashboard port | 4783 |

2. change-firewall preflight (Merge Gate)

Evaluates whether current code changes are safe to merge. Enforces strict exit codes for CI/CD gates.

• Exit Code 0: Approved / Safe to merge.
• Exit Code 1: Blocked / Merge review required.

# Standard preflight gate (fails if risk > 60 or high-risk findings exist)
npx change-firewall preflight

# Set a custom risk score threshold (0-100)
npx change-firewall preflight --max-risk 75

# Ignore high severity findings if overall score is below threshold
npx change-firewall preflight --no-fail-on-high

# Compare PR against base branch in CI
npx change-firewall preflight --base origin/main

# Emit JSON result for CI parsing
npx change-firewall preflight --json

Flags:

| Flag | Description | Default | |---|---|---| | -m, --max-risk <number> | Max acceptable risk score before blocking | 60 | | --no-fail-on-high | Do not block solely on HIGH severity findings | false | | -b, --base <ref> | Base branch/commit to diff against | HEAD | | -s, --staged | Evaluate staged changes only | false | | --json | Output preflight result as JSON | false |

3. change-firewall watch (Live Monitoring)

Runs in the background while you or an AI agent (Cursor, Claude Code, Copilot, Antigravity) edit code:

• Automatically debounces rapid file modifications (350ms).
• Re-analyzes deltas on the fly (Risk changed: 42 → 68).
• Live-streams updates to your browser dashboard via Server-Sent Events (SSE) without page reloads.

# Start watch mode with auto-opened dashboard
npx change-firewall watch

# Watch mode on custom port without auto-opening browser
npx change-firewall watch -p 8080 --no-open

4. change-firewall impact <file> (Blast Radius)

Performs deep blast-radius tracing for a specific file across the codebase.

npx change-firewall impact src/middleware/auth.ts

What It Displays:

• Direct dependents list (1 hop away).
• Transitive / indirect downstream consumers (2–3 hops away).
• Protected API routes impacted.
• Blast severity rating (HIGH, MEDIUM, LOW).

5. change-firewall why <file> (Architectural Role)

Explains why a file matters to the system architecture and its historical stability.

npx change-firewall why src/services/userService.ts

What It Displays:

• Architectural role (Authentication Middleware, Public Route, Service, Model, Test Suite).
• Caller count & downstream consumers.
• Git Churn analysis: total historical commits, high-churn warnings, unique contributors, and recent commits.

6. change-firewall open (Dashboard Server)

Spins up the embedded local dashboard at http://localhost:4783 loaded with the current working tree analysis.

npx change-firewall open

7. change-firewall demo (Simulation Mode)

Launches an interactive simulation of the Golden Moment scenario without requiring any uncommitted Git changes. Great for exploring the tool and dashboard features immediately:

npx change-firewall demo

8. change-firewall mcp (Model Context Protocol)

Starts the native Model Context Protocol (MCP) server over standard I/O (stdio). This exposes Change Firewall as native tools and prompts to AI assistants like Claude Desktop, Google Antigravity, Cursor, and Windsurf.

npx change-firewall mcp

Exposed MCP Tools:

• analyze_changes: Performs AST behavioral diffing, caller blast radius mapping, and deterministic risk scoring (0–100).
• evaluate_preflight: Determines whether current changes are safe to merge, blocking on high-risk mutations.
• compute_blast_radius: Inspects direct consumers, indirect dependents, and affected routes for a specific file.
• explain_file_impact: Explains architectural role (middleware, route, service, model), historical git churn, and callers.

Exposed MCP Prompts:

• change_firewall_audit: Guided prompt for agents to audit diffs and propose self-corrections before committing.

💻 Programmatic Node.js / TypeScript API

Change Firewall exports a fully-typed JavaScript / TypeScript API for use in your custom tools, scripts, testing suites, or backend servers.

import {
  analyzeChanges,
  evaluatePreflight,
  computeBlastRadius,
  buildDependencyGraph,
  startWatchMode,
} from 'change-firewall';

1. analyzeChanges()

Runs full behavioral analysis, AST diffing, and risk scoring on the repository.

import { analyzeChanges } from 'change-firewall';

async function run() {
  const report = await analyzeChanges({
    cwd: process.cwd(),      // Project root path (defaults to process.cwd())
    // base: 'origin/main',  // Base ref to compare against (defaults to HEAD)
    // staged: false,        // True to analyze only staged files
  });

  console.log(`Repository: ${report.repoName} (${report.branch})`);
  console.log(`Risk Score: ${report.risk.score}/100 [${report.risk.level}]`);
  console.log(`Files Changed: ${report.summary.totalFilesChanged}`);
  console.log(`Behavioral Shifts: ${report.summary.behavioralChangeCount}`);

  // Inspect specific behavioral findings
  for (const finding of report.findings) {
    console.log(`\n[${finding.severity}] ${finding.title}`);
    console.log(`File: ${finding.filePath}`);
    console.log(`Confidence: ${finding.confidence}%`);
    console.log(`Evidence:`, finding.evidence);
    console.log(`Recommendation: ${finding.recommendation}`);
  }
}

run();

2. evaluatePreflight()

Evaluates an analysis report against merge safety rules.

import { analyzeChanges, evaluatePreflight } from 'change-firewall';

async function checkMerge() {
  const report = await analyzeChanges({ cwd: process.cwd() });

  const preflight = evaluatePreflight(report, {
    maxRisk: 60,          // Maximum allowed risk score (0-100, default: 60)
    blockOnHighRisk: true, // Block if any HIGH severity finding exists (default: true)
    allowWarnings: true,   // Allow medium/low warnings if risk <= maxRisk
  });

  if (preflight.readyToMerge) {
    console.log('✅ Changes are safe to merge! Risk score:', preflight.riskScore);
    process.exit(0);
  } else {
    console.error('❌ MERGE BLOCKED:');
    preflight.blockers.forEach((b) => console.error(`  - 🛑 ${b}`));

    if (preflight.recommendations.length > 0) {
      console.log('\nRecommendations:');
      preflight.recommendations.forEach((r) => console.log(`  - 💡 ${r}`));
    }

    process.exit(1);
  }
}

checkMerge();

3. computeBlastRadius()

Calculates the downstream blast radius and caller hierarchy for any specific file.

import { buildDependencyGraph, computeBlastRadius } from 'change-firewall';

async function checkImpact(targetFilePath: string) {
  // 1. Build project reverse import graph
  const { reverse } = await buildDependencyGraph(process.cwd());

  // 2. Traverse BFS up to 3 hops deep
  const blast = computeBlastRadius(targetFilePath, reverse, 3);

  console.log(`File: ${targetFilePath}`);
  console.log(`Total Consumers Affected: ${blast.totalDependents}`);
  console.log(`Direct Dependents:`, blast.directDependents);
  console.log(`Indirect Dependents (2-3 hops):`, blast.indirectDependents);

  if (blast.totalDependents > 5) {
    console.warn(`⚠️ High blast radius: ${blast.totalDependents} files depend on this!`);
  }
}

checkImpact('src/services/auth.ts');

4. startWatchMode()

Starts a debounced file watcher that serves live-streaming updates over SSE to the local dashboard.

import { startWatchMode } from 'change-firewall';

async function runLiveWatcher() {
  const handle = await startWatchMode({
    cwd: process.cwd(),
    port: 4783,          // Dashboard port
    open: true,          // Automatically open browser
    debounceMs: 350,     // Debounce delay for rapid edits
    onUpdate: (report) => {
      // Triggered whenever code is modified
      console.log(`[${new Date().toLocaleTimeString()}] Tree updated!`);
      console.log(`Risk Score: ${report.risk.score}/100`);
      console.log(`Modified: ${report.diffs.map((d) => d.filePath).join(', ')}`);
    },
  });

  console.log(`Watcher active on port ${handle.port}`);

  // Clean shutdown
  process.on('SIGINT', async () => {
    await handle.stop();
    process.exit(0);
  });
}

runLiveWatcher();

5. createMcpServer() / startMcpServer()

Embed or start the Model Context Protocol (MCP) server directly in your custom Node.js application or test harness:

import { createMcpServer, startMcpServer } from 'change-firewall';

// Option A: Start standard stdio MCP server for AI clients
await startMcpServer();

// Option B: Create McpServer instance for custom transports (e.g. SSE / testing)
const server = createMcpServer({ name: 'custom-firewall', version: '0.1.3' });

🤖 AI Coding Agent Self-Correction Loop & MCP

Change Firewall provides two integration models for AI coding assistants:

1. Native Model Context Protocol (MCP): AI assistants directly discover and execute Change Firewall tools without needing raw terminal/shell access.
2. Direct Agent Instructions (CLI / JSON Mode): Terminal-enabled agents run Change Firewall CLI commands to verify and self-correct their own code.

🔌 Model Context Protocol (MCP) Server Setup

Change Firewall exposes 4 native MCP tools (analyze_changes, evaluate_preflight, compute_blast_radius, explain_file_impact) and the change_firewall_audit prompt.

1. Claude Desktop

Add Change Firewall to your claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "change-firewall": {
      "command": "npx",
      "args": ["-y", "change-firewall", "mcp"]
    }
  }
}

2. Google Antigravity

Add to your global configuration at ~/.gemini/config/mcp_config.json (or within your project's .agents/ plugin):

{
  "mcpServers": {
    "change-firewall": {
      "command": "npx",
      "args": ["-y", "change-firewall", "mcp"]
    }
  }
}

3. Cursor & Windsurf

1. Navigate to Cursor Settings > Features > MCP (or Windsurf Settings).
2. Click + Add New MCP Server.
3. Fill in:
   • Name: change-firewall
   • Type: command (stdio)
   • Command: npx -y change-firewall mcp

🤖 Direct Agent Instructions (Claude Code, OpenAI Codex, Copilot)

For agents with terminal access (like Claude Code, Antigravity IDE, Cursor Agent, Aider, or OpenAI Codex / Copilot), you can instruct the agent to run Change Firewall as an automated self-correction loop.

Add the following rules to your repository's CLAUDE.md, AGENTS.md, GEMINI.md, or .cursorrules:

### Change Verification & Safety Protocol:
Before committing or completing any code change:
1. Run `npx change-firewall preflight --json` to evaluate merge safety.
2. If `readyToMerge` is false, inspect the `blockers` and `highRiskCount` in the output.
3. Automatically self-correct any breaking API contract mutations or missing test coverage.
4. For targeted inspection of affected callers, run `npx change-firewall impact <modified-file>`.

Sample JSON Output (npx change-firewall analyze --json):

{
  "risk": {
    "score": 74,
    "level": "HIGH"
  },
  "summary": {
    "totalFilesChanged": 3,
    "behavioralChangesCount": 1
  },
  "findings": [
    {
      "category": "API_CONTRACT",
      "title": "API Response Contract Mutated",
      "filePath": "src/controllers/user.ts",
      "severity": "HIGH",
      "confidence": 92,
      "evidence": [
        "Return statement modified: return user -> return { user }",
        "7 client consumers depend on root-level User object structure."
      ],
      "affectedFiles": [
        "src/client/userClient.ts",
        "src/views/profile.tsx"
      ],
      "recommendation": "Update client response deserializers or revert wrapper."
    }
  ]
}

🔄 CI/CD & GitHub Actions Integration

Add Change Firewall to your PR verification pipeline to prevent high-risk behavioral changes from merging and automatically drop rich behavior reports into PR reviews.

Option A: Interactive PR Bot & Merge Gate (Recommended)

Creates an interactive branded PR summary comment on every pull request and halts the merge gate if high-risk regressions are detected:

Create .github/workflows/change-firewall.yml:

name: Change Firewall

on:
  pull_request:
    branches: [ main, master, develop ]

permissions:
  contents: read
  pull-requests: write
  issues: write

jobs:
  analyze-changes:
    name: Change Firewall
    runs-on: ubuntu-latest

    steps:
      - name: Checkout Code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0 # Full history required to diff against target branch

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 22

      - name: Run Change Firewall Preflight
        id: firewall
        run: |
          set +e
          npx change-firewall preflight --base origin/${{ github.base_ref }} --json > change-firewall-report.json
          EXIT_CODE=$?
          echo "EXIT_CODE=$EXIT_CODE" >> "$GITHUB_ENV"
          exit 0

      - name: Post PR Summary Comment
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            let reportData;
            try {
              reportData = JSON.parse(fs.readFileSync('change-firewall-report.json', 'utf8'));
            } catch (err) {
              console.log('No report generated:', err.message);
              return;
            }

            const { readyToMerge, score, highRiskCount, mediumRiskCount, blockers, recommendations } = reportData;

            const iconUrl = 'https://raw.githubusercontent.com/himanshYou2003/change-firewall/main/assets/icon.png';
            const statusBadge = readyToMerge
              ? '🟢 **PASS / READY TO MERGE**'
              : '🔴 **BLOCKED / REVIEW REQUIRED**';

            let comment = `### <img src="${iconUrl}" width="24" height="24" align="absmiddle" alt="Change Firewall" /> Change Firewall Report: ${statusBadge}\n\n`;

            comment += `| Metric | Value | Status |\n`;
            comment += `| :--- | :--- | :--- |\n`;
            comment += `| **Overall Risk Score** | \`${score} / 100\` | ${score > 60 ? '⚠️ High Risk' : score > 30 ? '🟡 Medium Risk' : '🟢 Safe'} |\n`;
            comment += `| **High-Risk Behavioral Shifts** | \`${highRiskCount}\` | ${highRiskCount > 0 ? '🚨 Attention Needed' : '✓ Clean'} |\n`;
            comment += `| **Medium-Risk Shifts** | \`${mediumRiskCount}\` | ${mediumRiskCount > 0 ? '⚠️ Review' : '✓ None'} |\n\n`;

            if (blockers && blockers.length > 0) {
              comment += `#### 🚨 Merge Blockers\n`;
              for (const b of blockers) {
                comment += `* ❌ ${b}\n`;
              }
              comment += '\n';
            }

            if (recommendations && recommendations.length > 0) {
              comment += `#### 💡 Recommendations\n`;
              for (const r of recommendations) {
                comment += `* ➔ ${r}\n`;
              }
              comment += '\n';
            }

            comment += `---\n`;
            comment += `<sub>⚡ Verified by <a href="https://change-firewall.vercel.app"><b>Change Firewall</b></a> • <i>Behavior-Aware Change Intelligence for AI-Generated Diffs</i></sub>`;

            await github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              body: comment
            });

      - name: Enforce Merge Gate
        run: |
          if [ "$EXIT_CODE" -ne 0 ]; then
            echo "❌ Change Firewall blocked merge due to high-risk behavioral changes."
            exit 1
          fi

Option B: Quick 1-Line Safety Check (Minimal)

For a minimal setup that simply fails the check without posting comments:

name: Change Firewall Gate

on:
  pull_request:
    branches: [ main, master ]

jobs:
  firewall-gate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - name: Run Preflight Gate
        run: npx change-firewall preflight --base origin/${{ github.base_ref }}

🪝 Git Pre-Commit Hook (Husky)

Catch accidental API contract breaks or relaxed permissions before they are even committed to Git:

npx husky add .husky/pre-commit "npx change-firewall preflight --staged"

If an AI tool breaks an API response contract or alters security middleware without adding tests, the commit is safely intercepted!

🧪 Real-World Behavioral Scenarios

| Scenario | Code Change | What Change Firewall Detects | |---|---|---| | API Contract Wrapper | - return user;+ return { user }; | Flags API_CONTRACT shift, lists all client callers, warns of runtime response shape mismatch. | | Auth Guard Relaxation | - if (user.role === 'admin')+ if (user.role !== 'guest') | Flags AUTH shift, maps all affected downstream routes, checks for missing regression tests. | | Nullability Widening | - function get(id: string): User+ function get(id?: string): User \| null | Flags FUNCTION_CONTRACT widening, warns that downstream callers lack null checks. | | Validation Drift | + z.object({ email: z.string().email() }).parse(body) | Flags VALIDATION schema check, warns that previously accepted client payloads might now fail. | | Deleted Export | - export function legacyAuth() | Flags CRITICAL deleted export, lists all files importing that symbol. |

🛡️ Architecture & Deterministic Guarantees

Unlike tools that rely on remote LLMs to "guess" what changed, Change Firewall is 100% deterministic and grounded in compiler truth:

+-----------------------+     +--------------------------+     +-------------------------+
|   Working Tree Diff   | --> | TypeScript AST Analysis  | --> | Reverse Dependency Graph|
+-----------------------+     +--------------------------+     +-------------------------+
                                                                             │
                                                                             ▼
                                                               +-------------------------+
                                                               | Deterministic Risk Score|
                                                               |       (0 - 100)         |
                                                               +-------------------------+

1. In-Memory Git Dual-Tree Inspection: Directly compares your working tree files against HEAD in memory.
2. Native TypeScript AST Diffing: Uses the official TypeScript Compiler API (ts.createSourceFile) to inspect syntax trees, type signatures, return statements, and guard conditions.
3. Static Reverse Dependency Graph: Scans project imports and builds a reverse caller graph using BFS traversal to pinpoint the exact blast radius.
4. Deterministic Risk Formula: Combines behavioral severity, downstream caller counts, and historical Git churn into a transparent 0–100 score.

$$\text{Finding} + \text{Evidence} + \text{Blast Radius} + \text{Confidence} + \text{Actionable Recommendation}$$

🔒 Privacy & Local-First Philosophy

• 🚫 No API Keys Required — Works completely offline.
• 🚫 Zero Code Uploads — Your source code never leaves your computer.
• 🚫 Zero External AI Hallucinations — Analysis is backed by real compiler syntax trees and Git history.
• 💻 Self-Contained — Dashboard is served locally at http://localhost:4783 with zero external dependencies.

🌐 Links & Resources

• Official Web App & Visual Simulator: change-firewall.vercel.app
• Interactive Documentation & IDE: change-firewall.vercel.app/docs
• NPM Package: npmjs.com/package/change-firewall
• GitHub Repository: github.com/himanshYou2003/change-firewall

📄 License

MIT © Himanshu