init

Initialize Calor development environment with MSBuild integration and optional AI agent support.

Bash

calor init [options]

Overview

The init command sets up your project for Calor development by:

Adding MSBuild targets - Integrates Calor compilation into your .NET build process
Configuring AI agent integration (optional) - Creates skills/prompts for your preferred AI coding assistant

After running init, you can write .calr files alongside your .cs files and they'll compile automatically during dotnet build.

Quick Start

Bash

# Basic initialization (MSBuild integration only)
calor init

# Initialize with Claude Code support
calor init --ai claude

# Initialize with a specific .csproj
calor init --project MyApp.csproj

Options

Option	Short	Required	Description
`--ai`	`-a`	No	Agent to configure; repeat for `claude`, `codex`, `gemini`, and/or `github`
`--project`	`-p`	No	Target .csproj file (auto-detects if single .csproj exists)
`--solution`	`-s`	No	Initialize all projects in a `.sln` or `.slnx` solution
`--force`	`-f`	No	Overwrite existing files without prompting

AI Agent Support (Optional)

When you specify --ai, the command also sets up AI-specific configuration files.

Claude (`--ai claude`)

Creates the following files:

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/settings.json`	Hook configuration - enforces Calor-first development
`CLAUDE.md`	Project guidelines instructing Claude to prefer Calor for new code

Calor-First Enforcement

The .claude/settings.json file configures a PreToolUse hook that blocks Claude from creating .cs files. When Claude tries to write a C# file, it will see:

Plain Text

BLOCKED: Cannot create C# file 'MyClass.cs'

This is an Calor-first project. Create an .calr file instead:
  MyClass.calr

Use /calor skill for Calor syntax help.

Claude will then automatically retry with an .calr file. This enforcement ensures all new code is written in Calor.

Allowed file types:

.calr files (always allowed)
.g.cs generated files (build output)
Files in obj/ directory (build artifacts)

After initialization, use these Claude Code commands:

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

Codex (`--ai codex`)

Creates the following files:

File	Purpose
`.codex/config.toml`	MCP server configuration for Calor tools
`.codex/hooks.json`	Codex-native pre-write validation and post-write lint hooks
`AGENTS.md`	Project documentation with Calor-first guidelines

MCP Server Integration

The .codex/config.toml file configures an MCP server that gives Codex direct access to the consolidated MCP tools such as calor_check, calor_verify, calor_analyze, and calor_convert:

toml

# BEGIN CalorC MCP SECTION - DO NOT EDIT
[mcp_servers.calor]
command = "calor"
args = ["mcp", "--stdio"]
# END CalorC MCP SECTION

See calor mcp for the complete list of available tools.

Codex project lifecycle hooks cover supported apply_patch, Edit, and Write operations and lint changed .calr files afterward. The user must review and trust them with /hooks. Specialized file-change paths and shell commands can bypass hooks, so run the generated smoke test and retain CI checks. Calor writes current project guidance into AGENTS.md; it does not create project-local Codex skills.

Gemini (`--ai gemini`)

Creates the following files:

File	Purpose
`.gemini/skills/calor/SKILL.md`	Calor code writing skill with YAML frontmatter
`.gemini/skills/calor-convert/SKILL.md`	C# to Calor conversion skill
`.gemini/settings.json`	Hook configuration - enforces Calor-first development
`GEMINI.md`	Project guidelines instructing Gemini to prefer Calor for new code

Calor-First Enforcement

Like Claude Code, Gemini CLI supports hooks (as of v0.26.0+). The .gemini/settings.json file configures a BeforeTool hook that blocks Gemini from creating .cs files.

Gemini will receive a JSON response blocking the operation and suggesting an .calr file instead. This enforcement ensures all new code is written in Calor.

Allowed file types:

.calr files (always allowed)
.g.cs generated files (build output)
Files in obj/ directory (build artifacts)

After initialization, use these Gemini CLI commands:

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

GitHub Copilot (`--ai github`)

Creates the following files:

File	Purpose
`.github/copilot/skills/calor/SKILL.md`	Calor code writing skill with YAML frontmatter
`.github/copilot/skills/calor-convert/SKILL.md`	C# to Calor conversion skill
`.github/copilot-instructions.md`	Project documentation with Calor-first guidelines
`.vscode/mcp.json`	MCP server configuration for Copilot Agent mode

Guidance + MCP Tool Enforcement

GitHub Copilot does not support hooks like Claude Code or Gemini CLI. Calor-first development is guidance-based with MCP tool support.

MCP tools give Copilot programmatic access to the Calor compiler:

calor_compile, calor_verify, calor_analyze, and calor_convert
calor_check actions for diagnostics, type checking, lint, and snippet validation
Enforcement is not automatic - review file extensions after generation
Use calor assess to find any unconverted .cs files

After initialization, reference skills by name in your prompts:

Usage	Description
Reference `calor` skill	Write new Calor code with Copilot's assistance
Reference `calor-convert` skill	Convert existing C# code to Calor syntax

MSBuild Integration

The init command adds MSBuild targets to your .csproj file that:

Compile .calr files before C# compilation
Include generated .g.cs files in the build
Clean generated files on dotnet clean

Output Location

Generated C# files are placed in:

Plain Text

obj/<Configuration>/<TargetFramework>/calor/

This keeps generated files out of your source tree.

Build Settings

You can change how Calor builds by adding properties to your .csproj. For example, to turn off contract proving and keep the default for everything else:

xml

<PropertyGroup>
  <CalorVerify>false</CalorVerify>
</PropertyGroup>

Property	Default	What it does
`CalorEnforceEffects`	`true`	Check that each function's `§E{…}` list covers what its body really does. Set it to `false` to switch the check off.
`CalorPermissiveEffects`	`false`	Keep the effect checks on, but go easy on calls the compiler cannot look up. See below.
`CalorTypeCheck`	`true`	Run the type checker.
`CalorVerify`	`false`	Try to prove contracts with Z3 during the build.
`CalorElideProvenGuards`	`true`	When a contract is proved, leave its runtime check out of the generated C#. Only matters with `CalorVerify`.
`CalorEnableILAnalysis`	`false`	Read the compiled .NET assemblies you reference to work out what library calls do.
`CalorTranspileOnly`	`false`	Write the C# without type checking or Roslyn validation. Output made this way is never cached.
`CalorOutputDirectory`	`obj/…/calor/`	Where the generated `.g.cs` files go.
`CalorVerbose`	`false`	Print more detail while compiling.

CalorPermissiveEffects (New in 0.16)

This is the project-file version of the command line's --permissive-effects. Turning it on tells the compiler to assume that a call it cannot look up does nothing surprising, which helps while you are converting older code:

xml

<PropertyGroup>
  <CalorPermissiveEffects>true</CalorPermissiveEffects>
</PropertyGroup>

It stops the two "I cannot tell what this does" messages (Calor0411 and Calor0425) and reports "this function does something it never said it would" (Calor0410) as a warning instead of an error, both inside one file and across files. It never excuses an effect you wrote down yourself and then broke: Calor0424, Calor0420, and Calor0421 stay errors. See Effects for the full list.

Two things worth knowing:

Only true and false work. Writing 1 is not a value MSBuild can read as a yes-or-no answer, so the build stops with MSB4030.
The first build after you change it is a full rebuild. The setting is part of the fingerprint that decides whether cached work can be reused, so flipping it makes every file compile again once. Builds after that are back to normal.

Examples

Basic Initialization

Bash

# Initialize Calor (MSBuild only)
calor init

# Analyze codebase for migration candidates
calor assess ./src --top 10

With Claude Code

Bash

# Add Claude Code support
calor init --ai claude

With GitHub Copilot

Bash

# Add GitHub Copilot support
calor init --ai github

Initialize New Project

Bash

dotnet new console -o MyCalorApp
cd MyCalorApp
calor init
calor init --ai claude  # Optional