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
calor_check actions enable diagnostics, type checks, lint, and snippet validation within Copilot
Use calor assess 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_check            - Diagnose, type check, lint, or validate snippets
calor_verify           - Verify function contracts
calor_navigate         - Definitions, references, symbols, and scope
calor_structure        - Outlines, call graphs, and impact

Available Tools

Tool	Purpose
`calor_compile`	Compile Calor source to C#
`calor_check`	Diagnostics, type checking, lint, and snippet validation
`calor_verify`	Verify contracts with Z3 SMT solver
`calor_analyze`	Advanced bug detection and migration analysis
`calor_convert`	Convert between C# and Calor
`calor_navigate`	Definition, reference, symbol, type, and scope queries
`calor_structure`	Outline, call graph, and impact analysis

See calor mcp for the complete 18-tool surface.

Using MCP Tools in Prompts

Plain Text

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

Plain Text

Use calor_check with action diagnose 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
Project-local skills	`.claude/skills/`	`.gemini/skills/`	Not generated; managed `AGENTS.md` guidance	`.github/copilot/skills/`
Project instructions	`CLAUDE.md`	`GEMINI.md`	`AGENTS.md`	`copilot-instructions.md`
Skill invocation	`/calor`	`@calor`	Not applicable	Reference skill name
Enforcement	Hooks (enforced)	Hooks (enforced)	Hooks for covered tools + guidance	Guidance + MCP tools
Hook mechanism	`PreToolUse`	`BeforeTool`	Codex project hooks	None

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 assess to find migration candidates
Include context - Copilot works best with clear, detailed prompts about contracts and effects
Validate with MCP - Use calor_check with action: "diagnose" 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 assess ./src --top 10