Calor.Sdk 0.21.0

<p align="center"> <img src="docs/assets/calor-logo.png" alt="Calor Logo" width="200"> </p>

Calor

Coding Agent Language for Optimized Reasoning <br/> A programming language designed specifically for AI coding agents, compiling to .NET via C# emission.

Why Calor Exists

AI coding agents are transforming software development, but they're forced to work with languages designed for humans. This creates a fundamental mismatch:

AI agents need to understand code semantically — what it does, what side effects it has, what contracts it upholds — but traditional languages hide this information behind syntax that requires deep semantic analysis to parse.

Calor asks: What if we designed a language from the ground up for AI agents?

The Core Insight

When an AI agent reads code, it needs answers to specific questions:

• What does this function do? (not just how it's implemented)
• What are the side effects? (I/O, state mutations, network calls)
• What constraints must hold? (preconditions, postconditions)
• How do I precisely reference this code element across edits?
• Where does this scope end?

Traditional languages make agents infer these answers through complex analysis. Calor makes them explicit in the syntax.

What Makes Calor Different

Side-by-Side: What Agents See

Calor — Everything explicit:

§F{Square:pub}
  §I{i32:x}
  §O{i32}
  §Q (>= x 0)
  §S (>= result 0)
  §R (* x x)

C# — Contracts buried in implementation:

public static int Square(int x)
{
    if (!(x >= 0))
        throw new ArgumentException("Precondition failed");
    var result = x * x;
    if (!(result >= 0))
        throw new InvalidOperationException("Postcondition failed");
    return result;
}

What Calor tells the agent directly:

• Optional ID slot: §F{f002:Square:pub} if you need a stable handle for tooling; otherwise just §F{Square:pub}
• Precondition (§Q): x >= 0
• Postcondition (§S): result >= 0
• No side effects (no §E declaration)
• Block ends at dedent — no closer tag to forget

What C# requires the agent to infer:

• Parse exception patterns to find contracts
• Understand that lack of I/O calls probably means no side effects
• Hope line numbers don't change across edits

The Tradeoff

Calor deliberately trades token efficiency for semantic explicitness:

C#:   return a + b;    // 4 tokens, implicit semantics
Calor: §R (+ a b)       // Explicit Lisp-style operations

This tradeoff pays off when:

• Agents need to reason about code behavior
• Agents need to detect contract violations
• Agents need to edit specific code elements precisely
• Code correctness matters more than brevity

Benchmark Results

Calor shows measurable advantages in AI agent comprehension, error detection, edit precision, and refactoring stability. C# wins on token efficiency, reflecting a fundamental tradeoff: explicit semantics require more tokens but enable better agent reasoning.

See benchmark methodology and results →

Quick Start

# Install the compiler
dotnet tool install -g calor

# Initialize for Claude Code (run in a folder with a C# project or solution)
calor init --ai claude

# Initialize for OpenAI Codex CLI
calor init --ai codex

# Initialize for Google Gemini CLI
calor init --ai gemini

# Initialize for GitHub Copilot (with MCP tools)
calor init --ai github

# Compile Calor to C#
calor --input program.calr --output program.g.cs

Editor Support

Calor ships a first-class language server (calor lsp) speaking the standard Language Server Protocol over stdio: diagnostics, go-to-definition, references, symbol-exact rename, formatting, and semantic tokens. Any LSP-capable editor can use it — see the LSP docs for how to point your editor at it.

VS Code extension support was withdrawn after v0.13.1. The extension was distributed as platform-specific VSIX assets on each release; that channel is gone, along with the editors/vscode tree and its publishing workflows. The Marketplace listing was already frozen at v0.3.8 and is not maintained. The language server itself is unaffected and remains supported.

AI Integration Comparison

Your First Calor Program

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

Save as hello.calr, then:

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

Building from Source

git clone https://github.com/juanmicrosoft/calor.git
cd calor
bash src/Calor.Compiler/scripts/download-z3.sh
dotnet restore --locked-mode
dotnet build --no-restore

# Run the sample
dotnet run --project src/Calor.Compiler -- \
  --input samples/HelloWorld/hello.calr \
  --output samples/HelloWorld/hello.g.cs
dotnet run --project samples/HelloWorld

MCP Tooling

Calor ships an MCP (Model Context Protocol) server that gives AI agents direct access to the compiler. Run calor init --ai <agent> to auto-configure it, or start it manually:

calor mcp

The server exposes 19 tools across five categories:

See calor mcp for the complete reference.

Documentation

• Getting Started — Installation, hello world, and AI agent integration
  • Claude Integration — Enforced Calor-first with hooks
  • Codex Integration — OpenAI Codex CLI with MCP
  • Gemini Integration — Google Gemini CLI with hooks and MCP
  • GitHub Copilot Integration — GitHub Copilot with MCP tools
• Syntax Reference — Complete language reference
• CLI Reference — All calor commands including mcp, analyze, convert, and migrate
• Benchmarking — How we measure Calor vs C#
• Telemetry — Opt-in, off by default; exactly what is (and is never) collected

Contributing

Calor is an experiment in language design for AI agents. We welcome contributions, especially:

• Additional benchmark programs
• Metric refinements
• Parser improvements
• Documentation

See the evaluation framework in tests/Calor.Evaluation/ for how we measure progress.