Getting Started

This guide will help you install Calor, write your first program, and understand how to integrate Calor with AI coding agents.

Quick Overview

Calor is a programming language that compiles to C# via source-to-source transformation. The workflow is:

Plain Text

your_code.calr → Calor Compiler → your_code.g.cs → .NET Build → executable

What You'll Learn

Installation - Set up the Calor compiler
Hello World - Write and run your first Calor program
How It Works - How AI agents work with Calor using in-context examples
Claude Integration - Use Calor with Claude Code (enforced Calor-first)
Codex Integration - Use Calor with OpenAI Codex CLI
Gemini Integration - Use Calor with Google Gemini CLI (enforced Calor-first)
GitHub Copilot Integration - Use Calor with GitHub Copilot

Prerequisites

.NET 10.0 SDK or later
A terminal or command prompt

Installation

Install the Calor compiler as a global .NET tool:

Bash

dotnet tool install -g calor

Or update an existing installation:

Bash

dotnet tool update -g calor

Quick Start

Calor integrates into any .NET project. Start with a C# project (new or existing), enable Calor, and from that point forward all new code is written in Calor.

Step 1: Start with a C# Project

Bash

# Create a new project, or use an existing one
dotnet new console -o MyApp
cd MyApp

Step 2: Enable Calor

Bash

calor init

This adds MSBuild integration so .calr files compile automatically during dotnet build.

Step 3: (Optional) Enable AI Agent Integration

For Claude Code (with enforced Calor-first via hooks):

Bash

calor init --ai claude

For OpenAI Codex CLI (guidance-based):

Bash

calor init --ai codex

For Google Gemini CLI (with enforced Calor-first via hooks):

Bash

calor init --ai gemini

For GitHub Copilot (guidance-based):

Bash

calor init --ai github

This adds Calor skills and project documentation that instruct the AI to:

Write all new code in Calor (not C#)
Analyze existing C# files before modifying them

Note: Claude Code and Gemini CLI enforce Calor-first via hooks (blocks .cs creation). Codex CLI is guidance-based only. GitHub Copilot is guidance-based with MCP tool support.

Step 4: Write Calor Code

After init, create .calr files and they compile automatically. Create Program.calr:

Plain Text

§M{m001:MyApp}
§F{f001:Main:pub}
  §O{void}
  §E{cw}
  §P "Hello from Calor!"
§/F{f001}
§/M{m001}

Then build:

Bash

dotnet build

See Hello World for a detailed explanation of the syntax.

Step 5: (Optional) Migrate Existing C# Files

For existing C# codebases, analyze which files are good candidates for migration:

Bash

calor analyze ./src --top 10

Then convert high-scoring files:

Bash

calor convert HighScoreFile.cs

See the Adding Calor to Existing Projects guide for the complete walkthrough.

What You Get

Basic Init (`calor init`)

Component	Description
MSBuild integration	`.calr` files compile automatically during `dotnet build`
Generated output	C# files go to `obj/` directory, keeping source tree clean

With Claude (`calor init --ai claude`)

Component	Description
Claude Code skills	`/calor` to write Calor code, `/calor-convert` to convert C#
Hook configuration	Enforces Calor-first - blocks `.cs` file creation
CLAUDE.md	Project guidelines instructing Claude to prefer Calor for new code

With Codex (`calor init --ai codex`)

Component	Description
Codex skills	`$calor` to write Calor code, `$calor-convert` to convert C#
AGENTS.md	Project guidelines (guidance-based, not enforced)

Note: Codex CLI does not support hooks, so Calor-first is guidance-based only.

With Gemini (`calor init --ai gemini`)

Component	Description
Gemini CLI skills	`@calor` to write Calor code, `@calor-convert` to convert C#
Hook configuration	Enforces Calor-first - blocks `.cs` file creation via `BeforeTool` hook
GEMINI.md	Project guidelines instructing Gemini to prefer Calor for new code

With GitHub Copilot (`calor init --ai github`)

Component	Description
Copilot skills	`calor` and `calor-convert` skills (referenced by name)
copilot-instructions.md	Project guidelines with Calor-first rules
MCP tools	`calor_compile`, `calor_verify`, `calor_analyze`, etc. via `.vscode/mcp.json`

Note: GitHub Copilot does not support hooks, but MCP tools provide programmatic compiler access for validation.

AI Integration Comparison

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
MCP tools	`~/.claude.json`	N/A	N/A	`.vscode/mcp.json`
Enforcement	Hooks (enforced)	Hooks (enforced)	Guidance only	Guidance + MCP tools
Hook mechanism	`PreToolUse`	`BeforeTool`	N/A	MCP tools

Manual Installation

For alternative installation methods (global tool only, manual Claude skills setup, or building from source), see the Installation page.

Next Steps

Installation - Detailed setup instructions
Hello World - Understand the hello world program
Adding Calor to Existing Projects - Complete migration guide
Syntax Reference - Complete language reference
CLI Reference - All calor commands including migration analysis