GitHub Copilot Integration

This guide explains how to use Calor with GitHub Copilot. For other AI integrations, see Claude Integration, Gemini Integration, or Codex Integration.

Quick Setup

Initialize your project for GitHub Copilot with a single command:

Bash

calor init --ai github

This creates:

File	Purpose
`.github/copilot/skills/calor/SKILL.md`	Teaches Copilot Calor syntax
`.github/copilot/skills/calor-convert/SKILL.md`	Teaches Copilot C# to Calor conversion
`.github/copilot-instructions.md`	Project documentation with Calor-first guidelines
`.vscode/mcp.json`	Configures Calor MCP tools for Copilot Agent mode

Enforcement: Guidance + MCP Tools

Unlike Claude Code and Gemini CLI which use hooks to enforce Calor-first development, GitHub Copilot relies on instructions and MCP tools. While Copilot lacks hooks, MCP tools provide programmatic access to the Calor compiler:

Calor-first development is guidance-based with MCP tool support
Copilot should follow the instructions and create .calr files
MCP tools like calor_diagnose and calor_validate_snippet enable validation within Copilot
Use calor analyze to find any unconverted .cs files
Review file extensions after generation

Available Skills

The `calor` Skill

Reference the calor skill to activate Calor-aware code generation:

Plain Text

Using the calor skill, write a function that calculates factorial with:
- Precondition: n >= 0
- Postcondition: result >= 1

The `calor-convert` Skill

Reference the calor-convert skill to convert existing C# code to Calor:

Plain Text

Using the calor-convert skill, convert this C# class to Calor:

public class Calculator
{
    public int Add(int a, int b) => a + b;
}

MCP Server Integration

The init command also configures an MCP (Model Context Protocol) server that gives Copilot direct access to the Calor compiler. This enables Copilot to:

Compile and verify Calor code
Type check source for semantic errors
Analyze code for bugs and migration potential
Validate code snippets inline

How It Works

When you open the project in VS Code with Agent mode enabled, Copilot reads .vscode/mcp.json and starts the MCP server automatically. Copilot can then use tools like:

Plain Text

calor_typecheck        - Check for type errors
calor_verify           - Verify function contracts
calor_diagnose         - Get syntax diagnostics
calor_validate_snippet - Validate code snippets

Available Tools

Tool	Purpose
`calor_compile`	Compile Calor source to C#
`calor_typecheck`	Semantic type checking with error categorization
`calor_verify`	Verify contracts with Z3 SMT solver
`calor_analyze`	Advanced bug detection and migration analysis
`calor_convert`	Convert between C# and Calor
`calor_diagnose`	Get syntax diagnostics for a file
`calor_validate_snippet`	Validate incremental code snippets

See calor mcp for the complete list of 19 available tools.

Using MCP Tools in Prompts

Plain Text

Use the calor_compile tool to compile src/Models/User.calr

Plain Text

Use the calor_diagnose tool to validate this file for syntax errors

Configuration

The .vscode/mcp.json file is created automatically by calor init --ai github:

JSON

{
  "servers": {
    "calor": {
      "command": "calor",
      "args": ["mcp", "--stdio"]
    }
  }
}

Note: Unlike Claude Code which configures MCP in ~/.claude.json (user-level), GitHub Copilot uses .vscode/mcp.json (project-level). The Copilot format does not require a type field — the command field implies stdio transport.

GitHub Copilot vs Other AI Integrations

Feature	Claude Code	Gemini CLI	Codex CLI	GitHub Copilot
Skills directory	`.claude/skills/`	`.gemini/skills/`	`.codex/skills/`	`.github/copilot/skills/`
Project instructions	`CLAUDE.md`	`GEMINI.md`	`AGENTS.md`	`copilot-instructions.md`
Skill invocation	`/calor`	`@calor`	`$calor`	Reference skill name
Enforcement	Hooks (enforced)	Hooks (enforced)	Guidance only	Guidance + MCP tools
Hook mechanism	`PreToolUse`	`BeforeTool`	N/A	MCP tools

Best Practices

Review generated files - Check that Copilot created .calr files, not .cs
Use explicit instructions - Be specific about wanting Calor output
Reference skills clearly - Mention "using the calor skill" in your prompts
Run analysis regularly - Use calor analyze to find migration candidates
Include context - Copilot works best with clear, detailed prompts about contracts and effects
Validate with MCP - Use calor_diagnose via MCP to validate code after generation
Use Agent mode - Enable Agent mode in VS Code for best MCP tool integration

Workflow Tips

Starting a New Feature

Plain Text

Using the calor skill, I need to implement [feature description].
Please create the Calor code with appropriate contracts and effects.

Converting Existing Code

Plain Text

Using the calor-convert skill, convert src/Services/PaymentService.cs to Calor

Verifying Compliance

After Copilot generates code, verify Calor compliance:

Bash

# Find any .cs files that shouldn't exist
calor analyze ./src --top 10