Installation

This guide covers installing the Calor compiler and setting up your development environment.

Before you start

Install the .NET 10 SDK, not just the runtime. Check dotnet --version before the commands below.

Try your first program — a complete new-directory path, without an AI subscription.
Adopt Calor in an existing project — preserve your application and its entry point.
Connect an optional agent — choose a provider after project setup.
Contribute to the compiler — source builds and contributor tests are a separate path.

Global Tool Install

Install the Calor compiler as a global .NET tool:

Bash

dotnet tool install -g calor

After installation, you can compile Calor files from anywhere:

Bash

calor --input program.calr --output program.g.cs

To update to the latest version:

Bash

dotnet tool update -g calor

The site header identifies the compiler release these docs describe. Historical packaging notes remain in the changelog; they are not instructions to install an older patch.

AI Agent Integration

Calor provides first-class support for AI coding agents. The calor init command sets up your project for AI-assisted development.

Supported AI Agents

Agent	Flag	What Gets Created
Claude Code	`--ai claude`	Skills in `.claude/skills/`, `CLAUDE.md` project docs
OpenAI Codex	`--ai codex`	Codex-optimized configuration
Google Gemini	`--ai gemini`	Gemini-optimized configuration
GitHub Copilot	`--ai github`	Copilot-optimized configuration

Claude Code Integration

Initialize your project for Claude Code:

Bash

calor init --ai claude

This creates:

File	Purpose
`.claude/skills/calor/SKILL.md`	Calor code writing skill with YAML frontmatter
`.claude/skills/calor-convert/SKILL.md`	C# to Calor conversion skill
`CLAUDE.md`	Project documentation (creates new or updates Calor section)

Claude Code Commands

After initialization, use these commands in Claude Code:

Command	Description
`/calor`	Write new Calor code with Claude's assistance
`/calor-convert`	Convert existing C# code to Calor syntax

MSBuild Integration

The init command also adds MSBuild targets to your .csproj file for automatic Calor compilation:

Bash

# Specify project explicitly
calor init --ai claude --project MyApp.csproj

# Auto-detect single .csproj
calor init --ai claude

After initialization, Calor files compile automatically during dotnet build.

See calor init for complete documentation.

Calor ships a language server (calor lsp) speaking standard LSP over stdio: diagnostics, go-to-definition, references, symbol-exact rename, formatting, and semantic tokens. Any LSP-capable editor can use it.

Warning

VS Code extension support was withdrawn after v0.13.1. The extension was distributed as VSIX assets attached to each release; that channel no longer exists, and the Marketplace listing (frozen at v0.3.8) is not maintained. The language server is unaffected — point your editor at calor lsp directly.

Prerequisites

Before installing Calor, ensure you have:

Requirement	Version	Check Command
.NET SDK	10.0+	`dotnet --version`
Git	Any recent	`git --version`

Installing .NET SDK

macOS (Homebrew):

Bash

brew install dotnet-sdk

Windows: Download from dotnet.microsoft.com

Linux (Ubuntu/Debian):

Bash

sudo apt-get update
sudo apt-get install -y dotnet-sdk-10.0

For Contributors

The sections below are for developers who want to contribute to Calor or build from source. End users can skip this—the global tool install above is all you need.

Clone and Build

If you want to contribute to Calor or build from source:

Bash

# Clone the repository
git clone https://github.com/juanmicrosoft/calor.git
cd calor

# Build the entire solution
dotnet build

# Verify the build
dotnet run --project src/Calor.Compiler -- --help

Expected output:

Plain Text

Calor Compiler - Coding Agent Language for Optimized Reasoning

Usage:
  calor --input <file.calr> --output <file.cs>

Options:
  --input, -i    Input Calor source file
  --output, -o   Output C# file
  --help, -h     Show this help message

Project Structure

Plain Text

calor/
├── src/
│   └── Calor.Compiler/      # The Calor compiler
├── samples/
│   └── HelloWorld/         # Sample Calor program
├── tests/
│   ├── E2E/                # End-to-end tests
│   └── Calor.Evaluation/    # Evaluation framework
└── docs/                   # This documentation

Compiling Calor Files

Basic usage:

Bash

dotnet run --project src/Calor.Compiler -- \
  --input path/to/your/program.calr \
  --output path/to/output/program.g.cs

The .g.cs extension is a convention indicating "generated C#".

Running Generated Code

After compilation, you need a C# project to run the generated code:

Option 1: Use the HelloWorld Sample

Bash

# Compile your Calor file
dotnet run --project src/Calor.Compiler -- \
  --input your-program.calr \
  --output samples/HelloWorld/your-program.g.cs

# Run it (requires modifying HelloWorld.csproj or including the file)
dotnet run --project samples/HelloWorld

Option 2: Create a New Project

Bash

# Create a new console project
dotnet new console -o MyCalorProgram
cd MyCalorProgram

# Compile Calor to the project directory
dotnet run --project ../src/Calor.Compiler -- \
  --input ../my-code.calr \
  --output my-code.g.cs

# Run the program
dotnet run

Running Tests

E2E Tests

Bash

# macOS/Linux
./tests/E2E/run-tests.sh

# Windows
.\tests\E2E\run-tests.ps1

Evaluation Framework

Bash

# Run the evaluation
dotnet run --project tests/Calor.Evaluation -- --output report.json

# Generate markdown report
dotnet run --project tests/Calor.Evaluation -- --output report.md --format markdown

Troubleshooting

Build Errors

"SDK not found":

Bash

# Verify .NET is installed
dotnet --info

# If missing, install .NET 10.0 SDK

"Project not found":

Bash

# Ensure you're in the calor directory
pwd  # Should show .../calor

# List available projects
ls src/

Runtime Errors

"Main method not found":

Ensure your Calor code has a public Main function:
Plain Text
```
§F{f001:Main:pub}
  §O{void}
  // ...
```

Next Steps

Hello World - Understand Calor syntax
Syntax Reference - Complete language reference