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

$3

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

$3

🌟 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.

$3

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

Install the CLI:
``bash
npm install -g @neurcode/cli
`

Verify installation:
`bash
neurcode --version
`

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

---

🚀 Installation

$3

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

$3

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

$3

🆕 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

$3

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

$3

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

$3

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

$3

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 |

$3

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

`bash


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

$3

`
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
`

$3

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)

$3

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):
`bash
neurcode allow path/to/file.ts
`

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

---

⚙️ Configuration

$3

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

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

This file is automatically managed by the extension and CLI.

$3

Your API key is stored in your user home directory:

- macOS/Linux: ~/.neurcode/config.json
- Windows: C:\Users\\.neurcode\config.json

The extension uses the same configuration as the CLI.

$3

You can override the API URL:

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

---

🔧 Troubleshooting

$3

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

Solution:
1. Install the CLI globally:
`bash
npm install -g @neurcode/cli
`
2. Verify installation:
`bash
neurcode --version
`
3. Restart VS Code
4. If still not working, check your PATH:
`bash
echo $PATH # macOS/Linux
echo %PATH% # Windows
`
Ensure Node.js bin directory is included.

$3

Problem: You're not logged in to Neurcode.

Solution:
1. Open terminal in VS Code ( Ctrl+ `)
2. Run:
`bash
neurcode login
`
3. Follow the authentication flow in your browser
4. Return to VS Code and try again

$3

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:
`bash
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)

$3

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:
`bash
neurcode doctor
`
2. Check project initialization:
`bash
neurcode init
`
3. Verify authentication:
`bash
neurcode login
`

---

🚀 Advanced Usage

$3

Define custom governance policies:

`bash


View current policies

neurcode config policies

Create custom policy via dashboard

Visit: https://dashboard.neurcode.com/policies

`

$3

Analyze specific git diffs:

`bash


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"
`

$3

Work with multiple sessions:

`bash


List all sessions

neurcode session list --all

View session details

neurcode session status

End current session

neurcode session end
`

$3

Enable automatic file change tracking:

`bash
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

$3

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

$3

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

$3

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

$3

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

$3

- 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

$3

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

$3

🔄 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

$3

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