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 (project hooks and MCP):

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, Gemini CLI, and Codex can configure Calor-first hooks. For Codex, review and trust the generated hooks with /hooks, then run the generated smoke test because specialized file-change paths may bypass lifecycle hooks. 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!"

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 assess ./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
Hook configuration	Validates covered file edits and lints changed `.calr` files
MCP configuration	Direct compiler, verification, analysis, and conversion tools
AGENTS.md	Automatically loaded Calor project guidelines

Note: Codex hooks require repository and hook trust. They are guardrails; builds, tests, and repository-wide checks remain necessary.

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
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
MCP tools	`~/.claude.json`	`.gemini/settings.json`	`.codex/config.toml`	`.vscode/mcp.json`
Enforcement	Hooks (enforced)	Hooks (enforced)	Hooks for covered writes	Guidance + MCP tools
Hook mechanism	`PreToolUse`	`BeforeTool`	Codex project hooks	None

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