Calor
Coding Agent Language for Optimized Reasoning
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
| Principle | How Calor Implements It | Agent Benefit |
|---|
| Explicit over implicit | Effects declared with §E{cw, fs:r, net:rw} | Know side effects without reading implementation |
| Contracts are code | First-class §Q (requires) and §S (ensures) | Generate tests from specs, verify correctness |
| Stable IDs when you want them | §F{f001:Main}, §L{l001:i:1:100:1} (IDs are optional) | Precise references that survive refactoring |
| Indent-based blocks | Python-style indentation — no closer tags to mismatch | Lower edit cost (~16% fewer tokens in our studies) |
| Machine-readable semantics | Lisp-style operators (+ a b) | Symbolic manipulation without text parsing |
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
| Feature | Claude Code | Gemini CLI | Codex CLI | GitHub Copilot |
|---|
| Project instructions | CLAUDE.md | GEMINI.md | AGENTS.md | copilot-instructions.md |
| Skill invocation | /calor | @calor | $calor | Reference skill name |
| MCP tools | ✓ (~/.claude.json) | ✓ (.gemini/settings.json) | ✓ (.codex/config.toml) | ✓ (.vscode/mcp.json) |
| Enforcement | Hooks (enforced) | Hooks (enforced) | Guidance + MCP tools | Guidance + MCP tools |
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:
| Category | Tools |
|---|
| Compilation & Verification | calor_compile, calor_typecheck, calor_verify, calor_verify_contracts, calor_check |
| Code Navigation (LSP-style) | calor_goto_definition, calor_find_references, calor_symbol_info, calor_document_outline, calor_find_symbol |
| Analysis & Migration | calor_analyze, calor_assess, calor_convert, calor_compile_check_compat |
| Code Quality | calor_lint, calor_format, calor_validate_snippet |
| Syntax Help | calor_syntax_help, calor_syntax_lookup, calor_ids |
See calor mcp for the complete reference.
Documentation
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.
