Neurcode AI 🚀

Enterprise-grade AI-powered code governance and intelligent diff analysis for VS Code.

Neurcode AI ensures every code change aligns with your project's security, performance, and architectural standards. It acts as a "Scope Guard" for your project, preventing scope creep, technical debt, and bloat before it enters your codebase.

📋 Table of Contents

• Features
• Prerequisites
• Installation
• Quick Start
• Commands
• Workflow
• Configuration
• Troubleshooting
• Advanced Usage
• Support

✨ Features

🎯 IDE-Native Integration

Unlike a simple CLI wrapper, the Neurcode VS Code extension provides rich, native IDE features:

📊 Status Bar Integration

• Real-time Grade Display: See your verification grade (A-F) directly in the status bar
• Score & Violations: View adherence score and violation count at a glance
• One-Click Access: Click the status bar to view detailed verification results
• Color-Coded Indicators: Visual feedback with green (pass), orange (warn), red (fail)

🔍 Problems Panel Integration

• Scope Violations as Diagnostics: Scope violations appear in VS Code's Problems panel
• Clickable Errors: Click violations to navigate directly to affected files
• Severity Levels: Errors for blocked files, warnings for scope issues
• Integrated Workflow: Use VS Code's native error handling and navigation

🎨 Visual File Decorations

• Explorer Indicators: Files with scope violations show warning badges in the Explorer
• Status Icons: Visual indicators show which files are authorized, blocked, or have warnings
• Hover Tooltips: Hover over files to see verification status and grade

📋 Enhanced Sidebar Tree View

The Neurcode sidebar now shows:

• Verification Results: Current grade, adherence score, and verdict
• Violation Details: Expandable list of files with scope violations
• Session Information: Active session ID with quick link to dashboard
• Project Status: Current project and plan information
• Interactive Items: Click session/plan IDs to open in dashboard

🛡️ Scope Guard

Automatically detects and blocks changes to files that were not in the approved plan. Prevents scope creep and unauthorized modifications.

📊 Real-time Verification

Get instant feedback (Grade A-F) on how well your code adheres to the plan. Verify changes with comprehensive analysis including:

• Scope adherence scoring
• Policy violation detection
• Code bloat analysis
• Security risk assessment

🔓 Smart Overrides

Need to edit a file that wasn't planned? One-click authorization to allow specific file deviations with full audit trail.

🧠 AI-Powered Planning

Generate detailed execution plans using advanced AI (DeepSeek) to guide your coding sessions:

• Intelligent file action planning (CREATE, MODIFY, BLOCK)
• Complexity estimation
• Best practice recommendations
• Automatic session title generation (2-5 word summaries)

📈 Session Management

Track AI coding sessions with:

• Automatic session creation
• Session status tracking (active, completed, cancelled)
• File change history
• Intent documentation

🎯 Policy Enforcement

Enforce custom governance rules:

• Security policies
• Code quality standards
• Architectural constraints
• Custom rule definitions

🔄 Git Integration

Seamless integration with Git:

• Analyze staged changes
• Compare against any branch or commit
• Track file history and versions
• Revert to previous versions

⚙️ Prerequisites

1. Sign Up for Neurcode Dashboard

🌟 Sign up at neurcode.com to access:

• 📊 Interactive Dashboard - Visualize your verification results, sessions, and governance metrics
• 📈 Analytics & Insights - Track code quality trends, adherence scores, and policy violations over time
• 🔍 Session History - Browse and review all your AI coding sessions with detailed file diffs
• ⚙️ Policy Management - Create and manage custom governance policies
• 🎯 Project Overview - Get comprehensive insights into your codebase health

The VS Code extension works best when connected to your Neurcode account for full data visualization and historical tracking.

2. Install Neurcode CLI

This extension requires the Neurcode CLI to be installed globally. The extension is a visual interface for the CLI.

Install the CLI:

npm install -g @neurcode/cli

Verify installation:

neurcode --version

If you see a "command not found" error, ensure Node.js is installed and npm is in your system PATH.

🚀 Installation

From Open VSX Registry

1. Open VS Code
2. Go to Extensions view (⇧⌘X / Ctrl+Shift+X)
3. Search for "Neurcode AI"
4. Click Install

Manual Installation

1. Download the .vsix file from the releases page
2. Open VS Code
3. Go to Extensions view
4. Click the "..." menu → "Install from VSIX..."
5. Select the downloaded .vsix file

🎯 Quick Start

Step 0: Sign Up & Get Started

🆕 New to Neurcode?

1. Sign up at neurcode.com
2. Create your account (free tier available)
3. Get your API key from the dashboard
4. This enables full data visualization and historical tracking

Step 1: Initialize Your Project

1. Open your project in VS Code
2. Open the Command Palette (⇧⌘P / Ctrl+Shift+P)
3. Run "Neurcode: Initialize Project" (or run neurcode init in terminal)
4. Follow the prompts to:
   • Authenticate with Neurcode (run neurcode login - opens browser)
   • Link to an existing project or create a new one
   • Configure your project settings

Step 2: Generate a Plan

1. Open Command Palette (⇧⌘P / Ctrl+Shift+P)
2. Run "Neurcode: Generate Plan"
3. Describe what you want to build:

   Add user authentication with JWT tokens

4. The AI will generate a detailed execution plan with:
   • Files to create/modify
   • Recommended approach
   • Complexity estimation
   • Best practices

Step 3: Code with Confidence

As you code:

• Neurcode automatically watches your changes
• The Scope Guard will block unauthorized files
• Real-time verification tracks adherence to the plan

Step 4: Verify Your Changes

1. Click "Neurcode: Verify Changes" in the sidebar or Command Palette
2. Get instant feedback:
   • ✅ Grade A: Perfect adherence
   • ⚠️ Grade B-C: Minor deviations
   • 🚫 Grade D-F: Significant scope issues
3. View in Dashboard: Click session/plan links in the sidebar to see detailed visualizations at dashboard.neurcode.com

💡 Tip: The VS Code extension provides quick feedback, but for detailed analysis, visual diffs, and historical data, visit the Neurcode Dashboard

⌨️ Commands

| Command | Description | Access Method | |---------|-------------|---------------| | Generate Plan | Generate an AI-powered execution plan for your task | Command Palette (⇧⌘P) or Sidebar | | Verify Changes | Verify current code against the plan and get a grade | Command Palette, Status Bar, or Sidebar | | Allow Current File | Authorize the currently open file (bypass Scope Guard) | Right-click file → "Allow" or Command Palette | | Refresh Status | Reload the status sidebar and refresh all data | Click refresh icon in sidebar | | Show Status | Display detailed verification results in a popup | Click status bar indicator | | Initialize Project | Set up Neurcode for your workspace | Command Palette |

Additional CLI Commands

The extension integrates with the CLI. You can also use these commands in the integrated terminal:

# Session Management
neurcode session list          # List all sessions
neurcode session end [id]      # End a session
neurcode session status [id]   # View session details

# Analysis & Monitoring
neurcode check                 # Analyze git diff for risky changes
neurcode watch                 # Start file watching and cloud sync
neurcode doctor                # Run health check and diagnostics

# Authentication
neurcode login                 # Authenticate with Neurcode
neurcode logout                # Log out and remove API key

🔄 Workflow

Typical Development Workflow (VS Code Extension)

1. Click "Initialize Project" or run neurcode init
   ↓
2. Command Palette → "Generate Plan" → Enter intent
   ↓
3. Code your changes (Neurcode automatically tracks)
   ↓
4. Click status bar or run "Verify Changes"
   ↓
5. View results:
   - Status bar shows grade instantly
   - Problems panel shows violations
   - Sidebar shows detailed breakdown
   ↓
6. Click violation files to navigate and fix
   ↓
7. Re-verify to see improved grade

Visual Workflow

1. Status Bar shows your current grade at all times (e.g., "✓ A (95%)")
2. Problems Panel lists all scope violations as clickable errors
3. Sidebar provides detailed verification results and violation details
4. Explorer shows warning badges on files with violations
5. One-click actions for common tasks (verify, allow, refresh)

Handling Scope Deviations

If you need to modify a file outside the plan:

1. VS Code Extension (Recommended):

   • Right-click the file in Explorer
   • Select "Allow Current File"
   • Or use Command Palette → "Allow Current File"

2. CLI (Alternative):

   neurcode allow path/to/file.ts

The file will be authorized with a full audit trail, and all visual indicators will update automatically.

⚙️ Configuration

Project Configuration

Each project has a .neurcode/config.json file:

{
  "projectId": "proj_abc123",
  "sessionId": "session_xyz789",
  "lastPlanId": "plan_def456",
  "apiUrl": "https://api.neurcode.com"
}

This file is automatically managed by the extension and CLI.

API Key Configuration

Your API key is stored in your user home directory:

• macOS/Linux: ~/.neurcode/config.json
• Windows: C:\Users\<username>\.neurcode\config.json

The extension uses the same configuration as the CLI.

Environment Variables

You can override the API URL:

export NEURCODE_API_URL="https://api.neurcode.com"

🔧 Troubleshooting

"Command not found: neurcode"

Problem: The CLI is not installed or not in your system PATH.

Solution:

1. Install the CLI globally:

   npm install -g @neurcode/cli

2. Verify installation:

   neurcode --version

3. Restart VS Code
4. If still not working, check your PATH:

   echo $PATH  # macOS/Linux
   echo %PATH% # Windows

   Ensure Node.js bin directory is included.

"Authentication Required" Error

Problem: You're not logged in to Neurcode.

Solution:

1. Open terminal in VS Code (Ctrl+`)
2. Run:

   neurcode login

3. Follow the authentication flow in your browser
4. Return to VS Code and try again

Extension Not Working

Problem: Extension appears installed but commands don't work.

Solution:

1. Sign up first: Ensure you have an account at neurcode.com
2. Check the Output panel (View → Output → Select "Neurcode")
3. Verify CLI is accessible:

   neurcode doctor

4. Authenticate: Run neurcode login to connect your account
5. Reload VS Code window: Developer: Reload Window
6. Check VS Code version (requires v1.80.0 or later)

Plan Generation Fails

Problem: Plan generation returns an error.

Possible Causes:

• Not authenticated (neurcode login)
• API URL incorrect (check neurcode doctor)
• No project initialized (neurcode init)
• Network connectivity issues

Solution:

1. Run diagnostics:

   neurcode doctor

2. Check project initialization:

   neurcode init

3. Verify authentication:

   neurcode login

🚀 Advanced Usage

Custom Policies

Define custom governance policies:

# View current policies
neurcode config policies

# Create custom policy via dashboard
# Visit: https://dashboard.neurcode.com/policies

Git Integration

Analyze specific git diffs:

# Check staged changes
neurcode check --staged

# Check against a specific branch
neurcode check --base main

# Check with AI analysis
neurcode check --ai --intent "Added user authentication"

Session Management

Work with multiple sessions:

# List all sessions
neurcode session list --all

# View session details
neurcode session status <session-id>

# End current session
neurcode session end

File Watching & Cloud Sync

Enable automatic file change tracking:

neurcode watch

This will:

• Watch for file changes
• Sync to cloud automatically
• Enable remote command execution
• Track all modifications in real-time

📊 Understanding Grades

| Grade | Score Range | Meaning | Action | |-------|------------|---------|--------| | A | 90-100% | Perfect adherence to plan | ✅ Ship it! | | B | 80-89% | Minor deviations | ⚠️ Review warnings | | C | 70-79% | Some scope issues | ⚠️ Review and authorize if needed | | D | 60-69% | Significant deviations | 🚫 Fix scope issues | | F | <60% | Major scope violations | 🚫 Blocked - Review plan |

🎓 Best Practices

1. Always Start with a Plan

• Generate a plan before coding
• Review the AI-generated plan
• Adjust if needed before starting

2. Verify Regularly

• Verify after completing logical sections
• Don't wait until the end
• Catch issues early

3. Use Sessions Effectively

• One session per feature/task
• End sessions when complete
• Use descriptive intents

4. Authorize Thoughtfully

• Use "Allow" sparingly
• Document why files were authorized
• Review authorized files in dashboard

5. Monitor Your Score

• Aim for Grade A-B consistently
• Review Grade C-D cases
• Understand what caused lower grades

🔐 Security & Privacy

• API Keys: Stored locally in your home directory
• File Contents: Only sent to Neurcode API when explicitly analyzing
• Git Integration: Reads git diff locally, only sends metadata to API
• Privacy: Your code remains private - only diffs and metadata are analyzed

📚 Additional Resources

• 🌐 Website & Sign Up: https://neurcode.com/ - Sign up for full dashboard access
• 📊 Dashboard: https://dashboard.neurcode.com - View sessions, analytics, and visualizations
• 📖 Documentation: https://docs.neurcode.com - Comprehensive guides and API docs
• 💻 GitHub Repository: https://github.com/sujit-jaunjal/neurcode
• ⌨️ CLI Documentation: Run neurcode --help in terminal

Why Use the Dashboard?

While the VS Code extension provides excellent real-time feedback, the Neurcode Dashboard offers:

• 📈 Historical Analytics - Track your code quality trends over time
• 🔍 Advanced Visualizations - Interactive charts and graphs
• 📊 Detailed File Diffs - Side-by-side comparisons with syntax highlighting
• 📋 Session Management - Review and manage all your AI coding sessions
• ⚙️ Policy Configuration - Visual policy editor and management
• 🎯 Team Collaboration - Share insights and reports with your team

🐛 Reporting Issues

Found a bug or have a feature request?

1. Check existing issues: GitHub Issues
2. Run diagnostics: neurcode doctor
3. Create new issue: Include:
   • VS Code version
   • Extension version
   • CLI version (neurcode --version)
   • Error messages from Output panel
   • Steps to reproduce

📄 License

This extension is licensed under the MIT License. See LICENSE for details.

👨‍💻 Built by

Sujit Jaunjal

• 🌐 Website
• 🐦 GitHub
• 💼 LinkedIn

🙏 Acknowledgments

Built with:

• VS Code Extension API
• TypeScript
• Neurcode CLI
• DeepSeek AI

⭐ Star us on GitHub if you find this extension helpful!

🎉 What's New in v0.4.0

Major Enhancements

🔄 IDE-Native Integration

• Status bar showing real-time verification grades
• Problems panel integration for scope violations
• Visual file decorations in Explorer
• Enhanced sidebar with verification results

📊 Real-Time Data

• Direct backend API integration (no CLI dependency for status)
• Automatic refresh of verification results
• Live session and plan information

🎯 Better Developer Experience

• Click violations to navigate to files
• One-click actions from status bar
• Visual indicators throughout the IDE
• Seamless workflow without leaving VS Code

📋 Enhanced Information Display

• Detailed verification breakdown in sidebar
• Expandable violation lists
• Quick links to dashboard
• Comprehensive tooltips and help text

Migration from Previous Versions

If you're upgrading from v0.3.0 or earlier:

1. No configuration changes needed
2. All existing features remain
3. New features activate automatically
4. Status bar appears automatically
5. Problems panel integration is automatic

Version 0.4.0 | Last Updated: January 2025