Scratch Security - VS Code Extension

AI-powered code security analysis, vulnerability detection, and Git workflow assistance for VS Code. Now with real-time context awareness for agentic coding IDEs!

Features

Security Analysis

• AI-Powered Analysis: Uses Google Gemini AI to intelligently detect security vulnerabilities
• Real-time Scanning: Analyze individual files or entire workspaces
• Security Dashboard: Visual overview of your code's security status
• Smart Detection: Identifies SQL injection, XSS, authentication issues, and more
• Security Scoring: Get an overall security score for your projects
• Export Reports: Generate detailed security reports in JSON format
• VS Code Integration: Seamlessly integrates with VS Code's UI and themes

Git Workflow Tools

• Merge Conflict Resolution: AI-assisted resolution of Git merge conflicts with side-by-side analysis
• Git Commit Squashing: Select and squash multiple commits with a visual interface (Pro feature)
• Pre-commit Security Guard: Automatic security scanning before staging files with git add
• Terminal Git Detection: Automatically detects git add commands in terminal and prompts for code review

Real-Time Context Awareness for Agentic Coding IDEs 🆕

Give your coding agents "eyes" to see code changes in real-time!

Scratch Security now provides real-time context awareness for agentic coding IDEs like Cursor, VSCode, and Antigravity. This enables AI coding agents to see their own code changes as they happen, just like a human engineer would.

Key Features:

• Real-Time Change Detection: Automatically detects file changes, including agent-made edits
• Intelligent Diff Capture: Captures code changes in efficient TOON format (30-50% token reduction)
• Context-Aware Summaries: Gemini-powered summaries of code changes with full context
• MCP Server Integration: Model Context Protocol (MCP) server for seamless agent communication
• File Context Caching: Persistent caching with SHA-256 hashing to prevent redundant processing
• Smart Change Tracking: Prevents infinite loops and duplicate processing with content hash comparison

How It Works:

1. Change Detection: Monitors file changes via multiple mechanisms:

   • Document change events (normal edits)
   • File system watcher (external/agent edits)
   • Periodic polling (fallback for missed events)

2. Diff Generation: Creates efficient TOON-formatted diffs with:

   • Line-by-line change tracking
   • Full code context preservation
   • Timestamp and metadata

3. AI Summarization: Generates comprehensive summaries using Gemini:

   • Context-aware analysis
   • Potential bug identification
   • Impact assessment
   • Code quality insights

4. MCP Communication: Pushes context to agents via MCP server:

   • Real-time diff notifications
   • Query-based context retrieval
   • Session management for multiple agents

Supported IDEs:

• Cursor: Full Composer mode integration with session tracking
• VSCode: Custom integration with discovery mechanism
• Antigravity: Agent-first integration with MCP configuration

Configuration:

• scratch.enableContextReading: Enable/disable real-time context reading (default: true)
• scratch.autoSummarizeDiffs: Automatically generate Gemini summaries (default: true)
• scratch.enableMCP: Enable MCP server for agentic IDE integration (default: true)
• scratch.mcpMaxDiffs: Maximum number of recent diffs to keep (default: 100)

Commands:

• Scratch: Toggle Context Reading - Enable/disable real-time context awareness
• Scratch: Enable Agent Context (MCP) - Activate MCP server for agent communication
• Scratch: MCP Server Status - View MCP server status and capabilities

MCP Server Setup

The Scratch Security extension includes a standalone MCP (Model Context Protocol) server that provides real-time code change context to your coding agents. This allows agents in Cursor, Antigravity, and VSCode to see code changes as they happen.

Prerequisites

1. Node.js installed (v16 or higher)
2. Scratch Security extension installed and configured
3. The mcp-server.js file from this repository (located in the extension directory)

Setup for Cursor IDE

1. Locate Cursor's MCP configuration file:

   • macOS: ~/Library/Application Support/Cursor/User/globalStorage/mcp.json
   • Windows: %APPDATA%\Cursor\User\globalStorage\mcp.json
   • Linux: ~/.config/Cursor/User/globalStorage/mcp.json

2. Add the Scratch Security MCP server configuration:

   If the file doesn't exist, create it. If it exists, merge the configuration:

   {
     "mcpServers": {
       "scratch-security": {
         "command": "node",
         "args": [
           "/absolute/path/to/scratch-security/mcp-server.js"
         ],
         "env": {
           "SCRATCH_MCP_STATE_FILE": "${workspaceFolder}/.scratch/mcp-state.json"
         }
       }
     }
   }
   

   Important: Replace /absolute/path/to/scratch-security/mcp-server.js with the actual path to the mcp-server.js file. You can find it in:

   • Extension directory: ~/.vscode/extensions/scratchsecurity.scratch-security-*/mcp-server.js
   • Or copy it to your workspace and use a relative path: "${workspaceFolder}/mcp-server.js"

3. Make the script executable (optional but recommended):

   chmod +x /path/to/mcp-server.js
   

4. Restart Cursor for the changes to take effect

5. Verify the connection:

   • Open Cursor Composer
   • The Scratch Security MCP server should be available
   • Ask your agent about recent code changes to verify it can see them

Setup for Antigravity IDE

1. Locate Antigravity's MCP configuration:

   • Typically at: ~/.antigravity/mcp.json or in your workspace settings
   • If the file doesn't exist, create it

2. Add the Scratch Security MCP server configuration:

   {
     "mcpServers": {
       "scratch-security": {
         "command": "node",
         "args": [
           "/absolute/path/to/scratch-security/mcp-server.js"
         ],
         "env": {
           "SCRATCH_MCP_STATE_FILE": "${workspaceFolder}/.scratch/mcp-state.json"
         }
       }
     }
   }
   

   Important: Replace /absolute/path/to/scratch-security/mcp-server.js with the actual path to the mcp-server.js file.

3. Alternative: Use workspace settings:

   • Create or edit .antigravity/settings.json in your workspace:

   {
     "mcpServers": {
       "scratch-security": {
         "command": "node",
         "args": [
           "${workspaceFolder}/mcp-server.js"
         ]
       }
     }
   }
   

4. Restart Antigravity for the changes to take effect

5. Verify the connection:

   • Check the agent's available tools/context
   • Make a code change and verify the agent can see it

Setup for VSCode

1. Install the MCP Extension (if available):

   • Search for "Model Context Protocol" in the VSCode marketplace
   • Install if available, or use built-in MCP support in newer versions

2. Configure MCP in VSCode settings:

   Option A: User Settings

   • Open Settings (Ctrl+, or Cmd+,)
   • Search for "MCP" or "Model Context Protocol"
   • Add the server configuration

   Option B: Workspace Settings

   • Create or edit .vscode/settings.json in your workspace:

   {
     "mcp.servers": {
       "scratch-security": {
         "command": "node",
         "args": [
           "${workspaceFolder}/mcp-server.js"
         ],
         "env": {
           "SCRATCH_MCP_STATE_FILE": "${workspaceFolder}/.scratch/mcp-state.json"
         }
       }
     }
   }
   

3. Alternative: Using npx (if published as npm package):

   {
     "mcp.servers": {
       "scratch-security": {
         "command": "npx",
         "args": [
           "@scratch-security/mcp-server@latest"
         ]
       }
     }
   }
   

4. Restart VSCode for the changes to take effect

5. Verify the connection:

   • Check the MCP extension output panel
   • Look for "scratch-security" in available MCP servers

Finding the mcp-server.js File

The mcp-server.js file is included with the extension. To find it:

1. Extension directory location:

   • macOS: ~/.vscode/extensions/scratchsecurity.scratch-security-*/mcp-server.js
   • Windows: %USERPROFILE%\.vscode\extensions\scratchsecurity.scratch-security-*\mcp-server.js
   • Linux: ~/.vscode/extensions/scratchsecurity.scratch-security-*/mcp-server.js

2. Copy to workspace (recommended):

   • Copy mcp-server.js to your workspace root
   • Use ${workspaceFolder}/mcp-server.js in the configuration
   • This makes it easier to manage and version control

Verifying the Connection

1. Check MCP Server Status:

   • In VS Code: Run Scratch: MCP Server Status command
   • In Cursor: Check Composer's available context/tools
   • In Antigravity: Check agent's available tools

2. Test the Connection:

   • Make a code change in your workspace
   • The extension should detect the change and write it to .scratch/mcp-state.json
   • Ask your agent about recent code changes
   • The agent should be able to see and reference the changes

3. Check State File:

   • Verify .scratch/mcp-state.json exists in your workspace
   • The file should be updated when you make code changes
   • Check the file contents to see recent diffs

Troubleshooting

Server Not Starting:

• Verify Node.js is installed: node --version (should be v16+)
• Check file permissions: chmod +x mcp-server.js
• Verify the path to mcp-server.js is correct (use absolute path if relative doesn't work)
• Check IDE logs for connection errors

No Data Available:

• Ensure the Scratch Security extension is active
• Verify scratch.enableMCP is set to true in settings
• Check that scratch.enableContextReading is enabled
• Verify .scratch/mcp-state.json exists and is being updated
• Make a code change and check if the state file updates

Connection Issues:

• Restart your IDE after adding the configuration
• Check IDE logs for MCP-related errors
• Verify the MCP server process is running
• Check for port conflicts or permission issues

Path Issues:

• Use absolute paths if relative paths don't work
• On Windows, use forward slashes or escaped backslashes: C:/path/to/mcp-server.js
• Verify the file exists at the specified path

Available MCP Tools

Once connected, your coding agent will have access to these tools:

• get_recent_diffs - Get recent code changes detected by Scratch Security
• get_file_context - Get context and recent changes for a specific file
• get_diff_summary - Get AI-generated summary of a specific diff
• push_context - Query for relevant code changes based on a search query

These tools enable your agent to:

• See code changes in real-time
• Understand the context of modifications
• Reference recent changes when generating code
• Maintain awareness of the codebase state

For more detailed setup instructions, see MCP_SETUP.md.

Automatic chrome-devtools-mcp Installation

The extension can automatically help you install and configure chrome-devtools-mcp, which allows your coding agents to interact with Chrome DevTools for web debugging and performance analysis.

Features:

• Automatic Prompt: The extension will prompt you to install chrome-devtools-mcp after activation (if not already configured)
• One-Click Setup: Automatically configures the MCP server for your IDE (Cursor, Antigravity, or VSCode)
• Prerequisites Check: Verifies Node.js version (v20.19+) before installation
• Manual Option: You can also manually install via Ctrl+Shift+P → "Scratch: Install chrome-devtools-mcp"

What chrome-devtools-mcp enables:

• Debug web applications in Chrome
• Analyze performance metrics
• Inspect DOM elements
• Test web pages programmatically
• Capture screenshots and network traffic

Prerequisites:

• Node.js v20.19 or newer
• Chrome (current stable version or newer)
• npm (comes with Node.js)

Configuration: The extension automatically adds this configuration to your IDE's MCP settings:

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"]
    }
  }
}

Optional Configuration: You can customize chrome-devtools-mcp by editing the configuration and adding options:

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": [
        "-y",
        "chrome-devtools-mcp@latest",
        "--channel=canary",
        "--headless=true",
        "--isolated=true"
      ]
    }
  }
}

Testing: Once configured, you can test it by asking your agent:

Check the performance of https://developers.chrome.com

The MCP server will automatically start a Chrome browser instance when needed.

Getting Started

1. Install the Extension: Install from the VS Code Marketplace
2. Sign In: Sign in with your Google account to use the extension
3. Configure API Key: Get a free API key from Google AI Studio and configure it via Ctrl+Shift+P → "Scratch: Configure API Key"
4. Start Analyzing: Use Ctrl+Shift+S to analyze the current file or access commands from the Command Palette

Usage

Security Analysis

Quick Start

• Analyze File: Press Ctrl+Shift+S or right-click any code file → "Scratch: Analyze Current File"
• Analyze Workspace: Ctrl+Shift+P → "Scratch: Analyze Current Workspace"
• View Dashboard: Ctrl+Shift+P → "Scratch: Open Security Dashboard"

Analysis Features

• Automatic analysis results displayed in a side panel
• Detailed issue breakdown by severity (Critical, High, Medium, Low)
• Overall security score calculation
• Export analysis results to JSON format

Git Merge Conflict Resolution

Resolve merge conflicts with AI-powered analysis and recommendations. The extension automatically detects Git merge conflicts when you open a file containing conflict markers (<<<<<<<, =======, >>>>>>>).

How it works:

1. Automatic detection when opening files with conflict markers
2. Prompt to resolve with AI assistance
3. Security analysis of both HEAD and incoming versions using Gemini AI
4. Side-by-side comparison panel showing:
   • Security scores and issue counts for each version
   • Detailed security analysis results
   • AI recommendation indicating which version has fewer security issues
   • Options to keep HEAD version, incoming version, or merge both versions

Intelligent Detection:

• Validates that conflict markers are actual Git merge conflicts (not comments or code)
• Ensures markers appear at the start of lines in correct sequence
• Prevents false positives from code examples or documentation

Limits: Free tier users can resolve 1 merge conflict per day. Pro users have unlimited conflict resolutions.

Git Commit Squashing (Pro Feature)

Interactively squash multiple Git commits into a single commit with a clean commit history. This feature helps maintain a linear and readable Git history by combining related commits.

How it works:

1. Run Ctrl+Shift+P → "Scratch: Squash Git Commits"
2. View a checklist of recent commits from HEAD downward
3. Select a contiguous range of commits to squash
4. Provide a new combined commit message
5. The extension automatically executes the squash operation using git reset --soft and git commit

Use cases:

• Clean up feature branch history before merging
• Combine fixup commits with their original commits
• Merge related commits before pushing to remote

Requirements: This feature requires a Pro subscription. Free users will be prompted to upgrade when attempting to use this feature.

Pre-commit Security Guard

Automatically detect when files are being staged with git add and optionally run security analysis before committing. This helps catch security vulnerabilities early in your development workflow.

How it works:

1. Automatically intercepts Git staging commands (git add, git stage, etc.)
2. Prompts you to run a quick security analysis before committing
3. Analyzes all staged files using the same Gemini-powered security scanning
4. Displays detailed analysis results in a side panel for each staged file
5. Allows you to review security issues before proceeding with the commit

Configuration options:

• Always prompt before committing
• Skip for current commit
• Never ask again (can be toggled per workspace)

Benefits:

• Catch security issues before they enter your repository
• Review vulnerabilities in context of your staged changes
• Maintain code quality standards automatically

Supported Languages

• JavaScript/TypeScript (.js, .ts, .jsx, .tsx)
• Python (.py)
• Java (.java)
• C/C++ (.c, .cpp)
• PHP (.php)
• Ruby (.rb)
• Go (.go)
• Rust (.rs)
• Swift (.swift)
• Kotlin (.kt)

Security Issues Detected

• SQL Injection vulnerabilities
• Cross-Site Scripting (XSS)
• Authentication/Authorization flaws
• Input validation problems
• Sensitive data exposure
• Insecure dependencies
• Code injection risks
• Path traversal vulnerabilities
• Cryptographic issues

Configuration

Access settings via File → Preferences → Settings → search for "Scratch":

Security Analysis

• Auto Analyze: Automatically analyze files when saved
• Severity Filter: Set minimum severity level to display
• Max File Size: Maximum file size to analyze (default: 1MB)
• Exclude Patterns: File patterns to exclude from analysis

Real-Time Context Awareness

• Enable Context Reading: Enable real-time context reading and change detection (default: true)
• Auto Summarize Diffs: Automatically generate Gemini summaries for file changes (default: true)
• Enable MCP: Enable MCP server for agentic IDE integration (default: true)
• MCP Max Diffs: Maximum number of recent diffs to keep in MCP server (default: 100)

Commands

Security Analysis

Git Workflow

Real-Time Context Awareness

Account Management

Security Tree View

The extension adds a "Scratch Security" panel to the Explorer sidebar showing:

• Overall security score
• Files analyzed with individual scores
• Security issues grouped by file
• Issue severity indicators
• Quick navigation to problem areas

Authentication & Setup

Sign In

The extension requires authentication with Google OAuth:

1. Run Ctrl+Shift+P → "Scratch: Sign In with Google"
2. A browser window opens for Google authentication
3. After successful sign-in, return to VS Code

API Key Configuration

After signing in, configure your Gemini API key:

1. Visit Google AI Studio
2. Sign in with your Google account
3. Create a new API key
4. Copy the key
5. In VS Code: Ctrl+Shift+P → "Scratch: Configure API Key"
6. Paste your key and press Enter

Why You Need Your Own Key

• Rate Limits: Personal keys have higher rate limits
• Privacy: Your code analysis stays private to your account
• Reliability: Avoid potential service interruptions
• Features: Access to latest AI model improvements

Subscription Tiers

Free Tier

• 10 security analyses per day
• 1 merge conflict resolution per day
• Basic security scanning features

Pro Tier

• Unlimited security analyses
• Unlimited merge conflict resolutions
• Git commit squashing feature
• Priority support

Upgrade to Pro via Ctrl+Shift+P → "Scratch: Upgrade to Pro" when you reach free tier limits.

Privacy & Security

• Local Processing: File scanning happens locally on your machine
• Secure Storage: API keys are stored securely using VS Code's secret storage
• No Data Collection: We don't collect or store your code or analysis results
• Optional Cloud: AI analysis requires sending code to Google's Gemini API
• Context Privacy: Real-time context data stays local; only sent to your configured agents via MCP
• Efficient Processing: Content hash tracking prevents unnecessary API calls and quota exhaustion

Troubleshooting

Common Issues

"API key not configured" error

• Solution: Run "Scratch: Configure API Key" command and enter your key

"File too large to analyze" error

• Solution: Increase max file size in settings or exclude large files

Analysis takes too long

• Solution: Exclude unnecessary directories (node_modules, dist, build)

No issues found but expecting some

• Solution: Check if file type is supported and try analyzing a different file

Getting Help

1. Check the GitHub Issues page
2. Review the troubleshooting section above
3. Create a new issue with:
   • VS Code version
   • Extension version
   • Error messages
   • Steps to reproduce

Changelog

4.0.0 - Real-Time Context Awareness 🆕

• Real-Time Context Awareness: Give coding agents "eyes" to see code changes in real-time
• MCP Server Integration: Model Context Protocol server for Cursor, VSCode, and Antigravity
• Intelligent Change Detection: Multi-mechanism detection (document events, file watcher, polling)
• TOON Format: Efficient diff serialization (30-50% token reduction)
• Context-Aware Summaries: Gemini-powered comprehensive change analysis
• File Context Caching: Persistent caching with SHA-256 hashing
• Smart Loop Prevention: Content hash tracking prevents infinite loops and duplicate processing
• Interactive Analysis Panel: Enhanced with code highlighting, fix application, and vulnerability viewing
• Generic Fix Prevention: Blocks application of generic word changes like "No code change required"
• Terminal Git Detection: Detects git add commands in terminal and prompts for review
• Agent Result Sharing: Analysis results automatically sent to MCP server for agent reference

3.0.0-beta

• Git merge conflict resolution with AI assistance
• Git commit squashing (Pro feature)
• Pre-commit security guard for git add workflow
• Google OAuth authentication
• Analysis tracking and history
• Daily usage limits for free tier
• Pro subscription integration with Stripe

2.0.0: Fix Bugs

• AI-powered security analysis
• VS Code integration
• Security dashboard
• Export functionality
• Multi-language support

1.0.0

• Initial release
• AI-powered security analysis
• VS Code integration
• Security dashboard
• Export functionality
• Multi-language support

Enjoy secure coding with Scratch Security!