Codex Integration

This guide explains how to use Calor with OpenAI Codex CLI. For Claude Code integration, see Claude Integration.

Quick Setup

Initialize your project for Codex CLI with a single command:

Bash

calor init --ai codex

This creates:

File	Purpose
`.codex/skills/calor/SKILL.md`	Teaches Codex Calor syntax
`.codex/skills/calor-convert/SKILL.md`	Teaches Codex C# to Calor conversion
`.codex/config.toml`	MCP server configuration for Calor tools
`AGENTS.md`	Project documentation with Calor-first guidelines

MCP Server Integration

The init command also configures an MCP (Model Context Protocol) server that gives Codex direct access to the Calor compiler. This enables Codex to:

Type check code and get semantic errors
Verify contracts using the Z3 SMT solver
Analyze code for bugs and migration potential
Convert between C# and Calor

How It Works

When you open the project in Codex CLI, the MCP server starts automatically based on the .codex/config.toml configuration:

toml

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

Available Tools

Tool	Purpose
`calor_typecheck`	Semantic type checking with error categorization
`calor_verify_contracts`	Z3-based contract verification
`calor_compile`	Compile Calor source to C#
`calor_analyze`	Advanced bug detection
`calor_convert`	Convert between C# and Calor
`calor_format`	Format source to canonical style
`calor_lint`	Check agent-optimized format issues

See calor mcp for the complete list of 19 available tools.

Codex CLI does not support hooks like Claude Code. However, MCP tools provide direct access to the Calor compiler, and Calor-first development is guidance-based, relying on instructions in AGENTS.md and the skill files:

MCP tools give Codex native access to compile, verify, and convert Calor code
Codex should follow the instructions and create .calr files
Hooks are not supported, so enforcement is not automatic
Review file extensions after generation
Use calor analyze to find any unconverted .cs files

Available Skills

The `$calor` Skill

Use $calor to activate Calor-aware code generation:

Plain Text

$calor

Write a function that calculates factorial with:
- Precondition: n >= 0
- Postcondition: result >= 1

The `$calor-convert` Skill

Use $calor-convert to convert existing C# code to Calor:

Plain Text

$calor-convert

Convert this C# class to Calor:

public class Calculator
{
    public int Add(int a, int b) => a + b;
}

Codex vs Claude Code

Feature	Claude Code	Codex CLI
Skills directory	`.claude/skills/`	`.codex/skills/<name>/`
Project instructions	`CLAUDE.md`	`AGENTS.md`
Skill invocation	`/calor`	`$calor`
MCP Tools	Yes	Yes
Enforcement	Hooks (enforced)	Guidance + MCP tools

Best Practices

Use MCP tools - Leverage MCP tools for compilation and verification
Review generated files - Check that Codex created .calr files, not .cs
Use explicit instructions - Be specific about wanting Calor output
Start with skill reference - Begin prompts with $calor or $calor-convert
Run analysis regularly - Use calor analyze to find migration candidates