BranchMate - VS Code Extension

AI-powered code reviewer and test case generator for Azure DevOps feature branches. BranchMate is a VS Code Chat Participant (Agent) that analyzes your git changes, generates Azure DevOps-compatible test cases, uploads them directly to ADO, and performs comprehensive code reviews -- all from the chat panel.

Prerequisites
Installation
Commands
Configuration Settings
Output Format
How It Works
Importing to Azure DevOps
Azure DevOps Direct Upload
Multi-Root Workspace Support
Model Selection & Fallback
Troubleshooting
Rebuilding After Changes

Prerequisites

Before using this extension, ensure the following are in place:

Requirement	Details
VS Code	Version 1.96.0 or higher
GitHub Copilot	Active subscription (Business or Enterprise recommended)
Copilot Chat	Extension installed and signed in
Git	Installed and available in your system PATH
Git Repository	The workspace folder must be a git-initialized repository
Claude Opus 4.6	Enabled in your organization's Copilot model policy (optional -- falls back to other models)

Installation

From the VS Code Marketplace (Recommended)

If your organization has been granted access, search for BranchMate in the Extensions view (Ctrl+Shift+X) and click Install.

From a `.vsix` file

code --install-extension branchmate-3.1.0.vsix --force

After installation, reload VS Code:

Press Ctrl+Shift+P > type "Reload Window" > press Enter

Commands

All commands are used in the VS Code Chat panel (open with Ctrl+Shift+I or click the Chat icon in the sidebar). Type @branchmate followed by a command.

`@branchmate /generate`

Analyze all uncommitted git changes and generate test cases.

This is the primary command. It collects all uncommitted changes in the repository -- staged, unstaged, and untracked new files -- and sends them to the AI model for analysis.

What it does step by step:

Detects the workspace root -- identifies which git repository you're working in
Runs git diff --cached -- collects staged changes (files you've git added)
Runs git diff -- collects unstaged changes (modified but not staged files)
Runs git ls-files --others --exclude-standard -- finds untracked new files
Generates diffs for untracked files -- runs git diff --no-index on up to 10 new files to include their full content
Combines all diffs into a single payload
Lists the changed files in the chat output
Sends the diff + prompt to Claude Opus 4.6 (or fallback model)
Extracts the CSV from the model's response
Validates and cleans the CSV -- ensures correct column count, proper escaping, and Azure DevOps compatibility
Saves the CSV to the workspace as testcases-YYYY-MM-DDTHH-MM-SS.csv
Opens the file in a side-by-side editor tab
Shows a preview of the first 20 rows in the chat

Example usage:

@branchmate /generate

@branchmate /generate This change adds retry logic for failed API calls with exponential backoff

When to use:

You've made several changes across multiple files and want test cases covering everything
Before creating a pull request, to generate a test plan for the entire changeset
When you want the broadest coverage of your current work

`@branchmate /staged`

Generate test cases from staged changes only.

This command analyzes only the files you've explicitly staged with git add. This is useful when your working directory has many changes but you want test cases only for what you're about to commit.

What it does step by step:

Detects the workspace root
Runs git diff --cached -- collects only staged diffs
Runs git diff --cached --name-only -- lists staged file names
Sends staged diffs to the AI model
Extracts, validates, and saves the CSV
Opens the file in a side-by-side editor

Example usage:

@branchmate /staged

@branchmate /staged Focus on the database query changes only

When to use:

You have a mix of work-in-progress and ready-to-commit changes
You want test cases scoped precisely to what's going into the next commit
You've staged a logical unit of work and want targeted test coverage

Workflow:

# Stage specific files
git add src/Services/PaymentService.cs
git add src/Models/Payment.cs

# Then in VS Code Chat:
# @branchmate /staged

`@branchmate /file`

Generate test cases for the currently active file's changes only.

This command analyzes git changes for the single file you currently have open and focused in the editor. It checks both staged and unstaged changes for that file.

What it does step by step:

Reads the active editor's file path -- the file currently focused in VS Code
Converts to a relative path within the repository
Runs git diff --cached -- "<file>" -- staged changes for this file
Runs git diff -- "<file>" -- unstaged changes for this file
If no diff found, treats it as a new untracked file and runs git diff --no-index to capture its full content
Sends the file-specific diff to the AI model
Extracts, validates, and saves the CSV
Opens the file in a side-by-side editor

Example usage:

@branchmate /file

@branchmate /file This file handles JWT token validation and expiry checks

When to use:

You want test cases for a single file's changes
You're iterating on one file and want to regenerate test cases as you refine it
The file is a critical component and you want deep, focused test coverage

Important:

You must have a file open and focused in the editor. If no file is open, the agent will display an error message.
The file must have git changes (modified, staged, or be a new untracked file).

`@branchmate /help`

Show all available commands, settings, and usage examples directly in the chat window.

This command does not analyze any git changes. It prints a comprehensive help guide inside the chat panel so you can quickly reference how to use the agent without leaving VS Code.

What it displays:

Commands table -- all available commands (/generate, /staged, /file, /branch, /crossrepo, /close, /review, /help) with descriptions
Context examples -- shows how to add free-form text after commands to guide generation
Settings table -- all configurable settings with their defaults
Current settings -- your active configuration values
Output format -- brief description of the CSV file and how to import it
Model priority -- which AI models the agent tries to use and in what order

Example usage:

@branchmate /help

When to use:

First time using the agent and want to see what--s available
Need a quick reference for command syntax or settings
Want to verify your current configuration without opening settings

`@branchmate /branch`

Generate test cases from all committed changes on the current feature branch (compared to main/master).

This command compares your current branch against the default branch (main or master) and generates test cases covering all committed changes on the feature branch -- not just uncommitted work.

Example usage:

@branchmate /branch

@branchmate /branch This branch implements the new payment gateway integration

When to use:

You want test cases covering the entire feature branch before creating a PR
Your changes are already committed and you want full branch-level coverage
You want to compare against main/master to see the total scope of changes

`@branchmate /crossrepo`

Generate cross-repository test cases from current branch + an external ADO repository for end-to-end coverage.

This command fetches code changes from an external Azure DevOps Git repository via the ADO REST API and combines them with your local branch changes. This enables end-to-end test case generation spanning multiple repos (e.g., frontend + backend, API + consumer).

Prerequisites:

branchmate.azureDevOpsOrg, branchmate.azureDevOpsProject, and branchmate.azureDevOpsPAT must be configured
The external repo must be accessible with your PAT

Example usage:

@branchmate /crossrepo

When to use:

Your feature spans multiple repositories (e.g., API changes + UI changes)
You need end-to-end test coverage across service boundaries
You want to validate integration points between repos

`@branchmate /close`

Close all non-closed test cases in the configured Azure DevOps test suite.

This command finds all test cases in your configured test suite and transitions them to the "Closed" state. Useful for cleaning up after a test cycle is complete.

Prerequisites:

branchmate.azureDevOpsOrg, branchmate.azureDevOpsProject, branchmate.azureDevOpsPAT, branchmate.testPlanId, and branchmate.testSuiteId must be configured

Example usage:

@branchmate /close

When to use:

A test cycle is complete and you want to bulk-close test cases
Cleaning up stale test cases in a suite

`@branchmate /review`

Review all committed changes on the feature branch for bugs, security, performance, and best practices.

This command performs a comprehensive AI-powered code review of your feature branch. It analyzes every changed file for real issues -- bugs, security vulnerabilities, performance problems, error handling gaps, and maintainability concerns -- and presents findings with severity levels and fix suggestions.

What it reviews:

Bugs -- logic errors, null references, race conditions
Security -- injection risks, credential exposure, authorization gaps
Performance -- inefficient queries, memory leaks, unnecessary allocations
Error handling -- missing try/catch, swallowed exceptions, incomplete cleanup
Best practices -- naming, patterns, testability, maintainability

Example usage:

@branchmate /review

When to use:

Before creating a pull request to catch issues early
Self-review of your code before requesting peer review
Learning about potential improvements in your code

`@branchmate /bug`

Create a bug work item in Azure DevOps from a failed test case.

This command takes an existing ADO test case ID, fetches its details (title and steps), uses the AI to generate a structured bug report, and creates the bug work item in Azure DevOps -- linked as a child of the configured parent work item.

What it does step by step:

Parses the test case ID from your prompt (bare number or natural language)
Fetches sprint info from the parent work item (configured via branchmate.workItemId)
Fetches test case details from Azure DevOps (title, steps, expected results)
Sends to AI model to generate a structured bug report with repro steps
Creates the bug work item in ADO with proper area path, iteration path, and application field
Links the bug as a child of the parent work item

Prerequisites:

branchmate.azureDevOpsOrg, branchmate.azureDevOpsProject, and branchmate.azureDevOpsPAT must be configured
branchmate.areaPath -- Azure DevOps Area Path
branchmate.workItemId -- parent work item ID (bug will be linked as a child)
branchmate.application -- application name for the bug work item

Example usage:

@branchmate /bug 131231

@branchmate /bug Create a bug for test case 131231

When to use:

A test case has failed and you want to quickly create a bug work item
You want consistent, well-structured bug reports with repro steps derived from test case steps
You need bugs linked to the correct sprint and parent work item automatically

Free-form Prompts

You can add natural language context after any command to guide the AI's test case generation. This text is appended to the prompt and helps the model understand business logic that isn't obvious from the code alone.

Examples:

@branchmate /generate The expiry date must be in CST timezone. Messages with past dates should be excluded.

@branchmate /staged This is a data quality validation. Each SQL query checks a specific column 
for null values, duplicates, and referential integrity against the source system.

@branchmate /file Only 3 key message slots are available. If more than 3 valid messages exist, 
use the priority ranking field to determine which ones to keep.

@branchmate /generate focus on negative test cases and error handling paths

Tips for better results:

Describe the business rules that the code implements
Mention any constraints or limits (max values, allowed ranges, required formats)
Specify which scenarios you care about most (negative, edge cases, concurrency)
Reference external systems the code interacts with (APIs, databases, queues)
Mention any configuration that affects behavior

Configuration Settings

Configure the extension in VS Code settings (Ctrl+,) or in .vscode/settings.json:

`branchmate.areaPath`

Type: string
Default: ""
Description: The Azure DevOps Area Path that will be set on every generated test case. This maps to your team's area in Azure DevOps.
Example: "Product", "Product\\DataQuality", "Engineering\\Backend"

`branchmate.assignedTo`

Type: string
Default: ""
Description: The email address that will appear in the "Assigned To" column of every generated test case.
Example: "your.name@company.com", "team-lead@company.com"

`branchmate.outputDirectory`

Type: string
Default: "" (workspace root)
Description: The directory where generated CSV files will be saved. If empty, files are saved to the workspace root folder.
Example: "C:\\TestCases", "./test-output"

`branchmate.maxTestCases`

Type: number
Default: 20
Description: The maximum number of test cases the AI will generate in a single run. The minimum is always 8 (hardcoded in the prompt). Increase this for large changesets, decrease for focused changes.
Example: 10, 30, 50

`branchmate.azureDevOpsOrg`

Type: string
Default: ""
Description: Azure DevOps organization name (e.g., "YourOrg" for https://dev.azure.com/YourOrg). Required for /crossrepo, /close, and direct upload features.

`branchmate.azureDevOpsProject`

Type: string
Default: ""
Description: Azure DevOps project name where test cases will be created and managed.

`branchmate.azureDevOpsPAT`

Type: string
Default: ""
Description: Azure DevOps Personal Access Token with Work Items (Read & Write) and Test Management (Read & Write) scopes.

`branchmate.testPlanId`

Type: number
Default: 0
Description: Azure DevOps Test Plan ID for uploading test cases.

`branchmate.testSuiteId`

Type: number
Default: 0
Description: Azure DevOps Test Suite ID for uploading test cases.

`branchmate.workItemId`

Type: string
Default: ""
Description: Comma-separated Work Item IDs to link test cases as "Tests" (Related Work). For /bug, the first ID is used as the parent work item. Leave empty to skip linking.

`branchmate.application`

Type: string
Default: ""
Description: Application name for bug work items created via /bug. You can find valid values on the bug creation page in Azure DevOps.

Example settings.json:

{
  "branchmate.areaPath": "ProjectName",
  "branchmate.assignedTo": "your.name@company.com",
  "branchmate.outputDirectory": "",
  "branchmate.maxTestCases": 20,
  "branchmate.azureDevOpsOrg": "YourOrg",
  "branchmate.azureDevOpsProject": "YourProject",
  "branchmate.azureDevOpsPAT": "your-pat-token",
  "branchmate.testPlanId": 12345,
  "branchmate.testSuiteId": 67890,
  "branchmate.workItemId": "1001,1002",
  "branchmate.application": "YourAppName"
}

Per-repository override:

Create a .vscode/settings.json in any repository to override defaults for that project:

{
  "branchmate.areaPath": "ProjectName\\DataQuality",
  "branchmate.maxTestCases": 30
}

Output Format

The generated CSV follows the Azure DevOps Work Item Import format with these columns:

Column	Test Case Row	Step Row	Description
`ID`	(empty)	(empty)	Auto-assigned by Azure DevOps on import
`Work Item Type`	`Test case`	(empty)	Identifies the row as a test case header
`Title`	Feature - Scenario	(empty)	Descriptive test case title
`Test Step`	(empty)	`1`, `2`, `3`...	Sequential step number
`Step Action`	(empty)	Action text	What to do in this step
`Step Expected`	(empty)	Expected text	What should happen
`Priority`	`1` or `2`	(empty)	1 = Critical, 2 = Important
`CP Automation Status`	`Not Automated`	(empty)	Automation tracking field
`Area Path`	`ProjectName`	(empty)	Azure DevOps area path
`Assigned To`	Email address	(empty)	Assignee email
`State`	`Design`	(empty)	Work item state

Example CSV output:

ID,Work Item Type,Title,Test Step,Step Action,Step Expected,Priority,HRB Automation Status,Area Path,Assigned To,State
,Test case,PaymentService - Successful payment processing,,,,,Not Automated,ProjectName,your.name@company.com,Design
,,,1,Configure a valid payment request with amount $50.00 and card ending 4242,Payment request object is created successfully,,,,,,
,,,2,Call ProcessPayment() with the valid request,Method returns PaymentResult with Status = Success,,,,,,
,,,3,Verify the transaction ID is a valid GUID,Transaction ID is non-null and in GUID format,,,,,,
,Test case,PaymentService - Reject negative payment amount,,,,1,Not Automated,ProjectName,your.name@company.com,Design
,,,1,Create a payment request with amount -10.00,Request object is created,,,,,,
,,,2,Call ProcessPayment() with the negative amount,ArgumentException is thrown with message containing "amount",,,,,,

Test case categories generated:

The AI generates test cases across these categories:

Priority 1 (Critical):

Happy path / positive scenarios with valid inputs
Core business logic validation
Error handling for critical failures
Integration points (APIs, databases, message queues)
Logging and observability

Priority 2 (Important):

Boundary conditions (empty, null, min, max values)
Edge cases (special characters, Unicode, large payloads)
Negative scenarios (invalid input, malformed data)
Configuration and settings validation
Timezone / locale concerns
Concurrency and race conditions

How It Works

Architecture

+----------------------------------------------------------+
|  VS Code Chat Panel                                      |
|  User types: @branchmate /generate                       |
+----------------------------+-----------------------------+
                             |
                             v
+----------------------------------------------------------+
|  extension.ts -- Chat Request Handler                    |
|  - Reads command (/generate, /staged, /file, /branch,    |
|    /crossrepo, /close, /review, /bug)                    |
|  - Reads user's free-form context                        |
|  - Reads VS Code settings                                |
+----------------------------+-----------------------------+
                             |
                             v
+----------------------------------------------------------+
|  gitChangeAnalyzer.ts -- Git Integration                 |
|  - Detects workspace/repo root                           |
|  - Runs git diff (staged / unstaged / untracked)         |
|  - Returns diff text + list of changed files             |
+----------------------------+-----------------------------+
                             |
               +-------------+-------------+
               v                           v
+-------------------+  +-----------------------------------+
| promptBuilder.ts  |  | reviewPromptBuilder.ts            |
| - Test case       |  | - Code review system prompt       |
|   system prompt   |  | - Structured review output format |
| - CSV format      |  | - Severity-based categorization   |
|   rules           |  +----------------+------------------+
+---------+---------+                  |
          |                            |
          +-----------+----------------+
                      v
+----------------------------------------------------------+
|  VS Code Language Model API (vscode.lm)                  |
|  - Selects Claude Opus 4.6 > 4.5 > any available        |
|  - Sends messages and streams response                   |
+----------------------------+-----------------------------+
                             |
               +-------------+-------------+
               v                           v
+-------------------+  +-----------------------------------+
| testCaseCsv       |  | codeReviewRenderer.ts             |
| Generator.ts      |  | - Parses review JSON              |
| - Extracts CSV    |  | - Renders findings with severity  |
| - Validates       |  | - Formats inline suggestions      |
| - Fixes columns   |  +----------------+------------------+
+---------+---------+                  |
          |                            |
          +-----------+----------------+
                      v
+----------------------------------------------------------+
|  Output                                                  |
|  - Saves testcases-YYYY-MM-DDTHH-MM-SS.csv              |
|  - Opens file in side-by-side editor                     |
|  - Shows preview in chat                                 |
|  - Displays import instructions                          |
|  - Optionally uploads to Azure DevOps via REST API       |
+----------------------------------------------------------+

Source Files

File	Purpose
`src/extension.ts`	Main entry point. Registers the `@branchmate` chat participant, handles commands, orchestrates the pipeline, saves output.
`src/gitChangeAnalyzer.ts`	Git integration layer. Runs git commands to collect diffs. Handles staged, unstaged, untracked, branch-level, and per-file scenarios. Supports multi-root workspaces.
`src/promptBuilder.ts`	Prompt engineering for test case generation. Constructs the system and user prompts sent to the AI model. Embeds CSV format rules, escaping instructions, and test case generation guidelines.
`src/reviewPromptBuilder.ts`	Prompt engineering for code reviews. Builds the system prompt for structured code review output with severity levels, categories, and fix suggestions.
`src/testCaseCsvGenerator.ts`	CSV extraction and validation. Parses the AI response, extracts CSV content, validates structure, fixes column counts, and ensures proper escaping.
`src/codeReviewRenderer.ts`	Code review output rendering. Parses the structured JSON review response and renders it as formatted markdown in the chat panel with severity indicators.
`src/adoRepoFetcher.ts`	Azure DevOps repository fetcher. Fetches branch diffs, commits, and file contents from external ADO Git repos via REST API for cross-repo test generation.
`src/azureDevOpsUploader.ts`	Azure DevOps uploader. Parses generated CSV into test case objects and creates them in ADO via REST API, including test steps and work item linking.
`src/sqlValidationGenerator.ts`	SQL validation script generator. Produces SQL validation queries for data-related changes.
`package.json`	Extension manifest. Declares the chat participant, commands, and configuration settings.

Importing to Azure DevOps

Open Azure DevOps in your browser
Navigate to Boards > Queries
Click Import Work Items (top-right)
Select the generated testcases-*.csv file
Azure DevOps will show a column mapping preview
Verify the columns are mapped correctly:
- Work Item Type → Work Item Type
- Title → Title
- Priority → Priority
- Area Path → Area Path
- Assigned To → Assigned To
- State → State
Click Import
Test cases will appear in your backlog with steps populated

Azure DevOps Direct Upload

In addition to CSV import, BranchMate can upload test cases directly to Azure DevOps via the REST API. After generating test cases, BranchMate will prompt you to upload them.

Required settings:

branchmate.azureDevOpsOrg -- your ADO organization
branchmate.azureDevOpsProject -- your ADO project
branchmate.azureDevOpsPAT -- your Personal Access Token
branchmate.testPlanId -- target Test Plan ID
branchmate.testSuiteId -- target Test Suite ID

Optional:

branchmate.workItemId -- work item IDs to link test cases to

What it does:

Parses the generated CSV into individual test case objects
Creates each test case as an ADO work item with steps
Adds test cases to the specified test suite
Links test cases to specified work items (if configured)
Reports success/failure for each test case in the chat

Multi-Root Workspace Support

If you have multiple folders open in VS Code (multi-root workspace), the agent will show a Quick Pick dropdown asking you to select which repository to analyze.

This works transparently with all commands (/generate, /staged, /file, /branch, /crossrepo, /review, /bug).

Model Selection & Fallback

The extension tries to use the best available AI model in this order:

Claude Opus 4.6 (claude-opus-4.6 family) -- preferred for highest quality test cases
Claude Opus 4.5 (claude-opus-4.5 family) -- strong fallback with excellent quality
Any available Copilot model -- last resort, uses whatever model is enabled

The selected model is displayed in the chat output so you know which model generated your test cases.

Requirements for Claude Opus 4.6:

Your GitHub Copilot organization policy must have Claude Opus 4.6 enabled
You must have GitHub Copilot Business or Enterprise subscription
The model must be available in your region

Troubleshooting

Problem	Solution
`@branchmate` not appearing in chat	Reload VS Code (`Ctrl+Shift+P` > "Reload Window"). Verify the extension is installed via Extensions panel.
"No workspace folder open"	Open a folder or repository in VS Code (`File` > `Open Folder`).
"Not a git repository"	Initialize git with `git init` or open a git-enabled project.
"No git changes detected"	Make some code changes. Verify with `git status` in terminal.
"No language model available"	Install and sign in to GitHub Copilot Chat extension.
"No active file open" (`/file` command)	Open and focus a file in the editor before using `/file`.
CSV has wrong column count	This is auto-fixed by the validator. If it persists, report the issue.
Large diffs truncated	Diffs over 60,000 characters are truncated. Use `/staged` or `/file` to narrow scope.
ADO upload fails	Verify your PAT has Work Items (Read & Write) and Test Management (Read & Write) scopes. Check org/project names.

Rebuilding After Changes

If you modify the extension source code:

# Compile TypeScript
npm run compile

# Package into VSIX
npx @vscode/vsce package

# Reinstall
code --install-extension branchmate-3.1.0.vsix --force

# Reload VS Code window
# Ctrl+Shift+P > "Reload Window"

For development with auto-recompile:

npm run watch

Then press F5 in VS Code to launch the Extension Development Host for testing.

License

MIT License -- see LICENSE for details.

BranchMate

Muhammed Shabil

BranchMate - VS Code Extension

Table of Contents

Prerequisites

Installation

From the VS Code Marketplace (Recommended)

From a .vsix file

Commands

@branchmate /generate

What it does step by step:

Example usage:

When to use:

@branchmate /staged

What it does step by step:

Example usage:

When to use:

Workflow:

@branchmate /file

What it does step by step:

Example usage:

When to use:

Important:

@branchmate /help

What it displays:

Example usage:

When to use:

@branchmate /branch

Example usage:

When to use:

@branchmate /crossrepo

Prerequisites:

Example usage:

When to use:

@branchmate /close

Prerequisites:

Example usage:

When to use:

@branchmate /review

What it reviews:

Example usage:

When to use:

@branchmate /bug

What it does step by step:

Prerequisites:

Example usage:

When to use:

Free-form Prompts

Examples:

Tips for better results:

Configuration Settings

branchmate.areaPath

branchmate.assignedTo

branchmate.outputDirectory

branchmate.maxTestCases

branchmate.azureDevOpsOrg

branchmate.azureDevOpsProject

branchmate.azureDevOpsPAT

branchmate.testPlanId

branchmate.testSuiteId

branchmate.workItemId

branchmate.application

Example settings.json:

Per-repository override:

Output Format

Example CSV output:

Test case categories generated:

How It Works

Architecture

Source Files

Importing to Azure DevOps

Azure DevOps Direct Upload

Required settings:

Optional:

What it does:

Multi-Root Workspace Support

Model Selection & Fallback

Requirements for Claude Opus 4.6:

Troubleshooting

Rebuilding After Changes

From a `.vsix` file

`@branchmate /generate`

`@branchmate /staged`

`@branchmate /file`

`@branchmate /help`

`@branchmate /branch`

`@branchmate /crossrepo`

`@branchmate /close`

`@branchmate /review`

`@branchmate /bug`

`branchmate.areaPath`

`branchmate.assignedTo`

`branchmate.outputDirectory`

`branchmate.maxTestCases`

`branchmate.azureDevOpsOrg`

`branchmate.azureDevOpsProject`

`branchmate.azureDevOpsPAT`

`branchmate.testPlanId`

`branchmate.testSuiteId`

`branchmate.workItemId`

`branchmate.application`