Gemini Integration

This guide explains how to use Calor with Google Gemini CLI. For other AI integrations, see Claude Integration or Codex Integration.

Quick Setup

Initialize your project for Gemini CLI with a single command:

Bash

calor init --ai gemini

This creates:

File	Purpose
`.gemini/skills/calor/SKILL.md`	Teaches Gemini Calor syntax
`.gemini/skills/calor-convert/SKILL.md`	Teaches Gemini C# to Calor conversion
`.gemini/settings.json`	MCP server + hooks - AI agent tools and Calor-first enforcement
`GEMINI.md`	Project documentation with Calor-first guidelines

Calor-First Enforcement

Unlike Codex CLI, Gemini CLI supports hooks (as of v0.26.0+). This means Calor-first development is enforced, not just guided.

When Gemini tries to create a .cs file, the hook blocks the operation and returns:

JSON

{
  "decision": "deny",
  "reason": "BLOCKED: Cannot create C# file 'MyClass.cs'",
  "systemMessage": "This is an Calor-first project. Create an .calr file instead..."
}

Gemini will then automatically retry with an .calr file.

MCP Server Integration

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

Type check code and get semantic errors
Verify contracts using the Z3 SMT solver
Navigate code with goto-definition and find-references
Analyze code for bugs and migration potential

How It Works

The MCP server is configured in .gemini/settings.json alongside hooks:

JSON

{
  "mcpServers": {
    "calor": {
      "command": "calor",
      "args": ["mcp", "--stdio"]
    }
  },
  "hooks": { ... }
}

When you start Gemini CLI in the project, it discovers the MCP server and can use tools like:

Plain Text

calor_typecheck     - Check for type errors
calor_verify        - Verify function contracts
calor_goto_definition - Navigate to symbol definitions
calor_find_references - Find all usages of a symbol

Example: Contract Verification

Gemini can verify your contracts are correct:

Plain Text

You: Does this function have any contract violations?

§F{f001:Divide:pub}
  §I{i32:a}
  §I{i32:b}
  §O{i32}
  §Q (!= b 0)
  §R (/ a b)
§/F{f001}

Gemini: [Uses calor_verify_contracts tool]
The precondition §Q (!= b 0) is proven correct by Z3.
This ensures division by zero cannot occur.

Available Tools

Tool	Purpose
`calor_typecheck`	Semantic type checking with error categorization
`calor_verify_contracts`	Z3-based contract verification
`calor_goto_definition`	Navigate to symbol definitions
`calor_find_references`	Find all usages of a symbol
`calor_document_outline`	Get file structure
`calor_analyze`	Advanced bug detection

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

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;
}

Gemini vs Claude Code vs Codex

Feature	Claude Code	Gemini CLI	Codex CLI
Skills directory	`.claude/skills/`	`.gemini/skills/<name>/`	`.codex/skills/<name>/`
Project instructions	`CLAUDE.md`	`GEMINI.md`	`AGENTS.md`
Skill invocation	`/calor`	`@calor`	`$calor`
Enforcement	Hooks (enforced)	Hooks (enforced)	Guidance only
Hook mechanism	`PreToolUse`	`BeforeTool`	N/A
MCP tools	Yes (compile, verify, analyze, convert, etc.)	Yes (compile, verify, analyze, convert, etc.)	No

Best Practices

Trust the enforcement - Gemini CLI will block .cs creation
Use explicit instructions - Be specific about contracts and effects
Start with skill reference - Begin prompts with @calor or @calor-convert
Review contracts - Verify generated contracts match your requirements

Troubleshooting

Hook Not Blocking Files

Verify the settings file exists:

Bash

cat .gemini/settings.json

It should contain the BeforeTool hook configuration with calor hook validate-write --format gemini.

calor Not Found

Ensure the Calor compiler is installed:

Bash

dotnet tool install -g calor
export PATH="$PATH:$HOME/.dotnet/tools"