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 v0.12 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.

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