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/config.toml`	MCP server configuration for Calor tools
`.codex/hooks.json`	Codex-native write validation and post-write lint hooks
`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_compile`	Compile Calor source to C#
`calor_check`	Diagnose, lint, type check, or validate snippets via `action`
`calor_verify`	Seven-status Z3 contract verification
`calor_analyze`	Advanced bug detection
`calor_convert`	Convert between C# and Calor
`calor_format`	Format source to canonical style
`calor_session_open` / `calor_file_write`	Cross-file checks and transactional writes

See calor mcp for the complete 18-tool surface.

Codex supports project lifecycle hooks. Calor writes a PreToolUse hook for covered apply_patch, Edit, and Write operations plus a PostToolUse lint hook for changed .calr files. Run /hooks, review the generated commands, and trust the exact project configuration before relying on them.

The write hook validates rename destinations and multi-file patches, but it is a guardrail rather than a security boundary. Shell commands and specialized file-change paths can bypass lifecycle hooks. Run the smoke test in bench/phase0-agent-native/CODEX-SMOKE.md and keep repository CI checks enabled.

Project Guidance

calor init --ai codex writes a managed Calor section into AGENTS.md; it does not generate project-local Codex skill files. The guidance covers current indent-only syntax, contracts, effects, IDs, and the required validation loop. Re-running init updates the managed section without replacing unrelated project instructions.

Codex vs Claude Code

Feature	Claude Code	Codex CLI
Project instructions	`CLAUDE.md`	`AGENTS.md`
MCP Tools	Yes	Yes
Enforcement	Hooks	Hooks for covered tools + `AGENTS.md`

Best Practices

Review and trust hooks - Confirm both lifecycle hooks are active with /hooks
Run the smoke test - Verify the current Codex tool path triggers the hooks
Use MCP tools - Compile, check, and verify through the consolidated v0.12 surface
Review generated files - Treat hooks as a guardrail and retain CI backstops
Run analysis regularly - Use calor assess to find migration candidates