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:

calor init --ai gemini

This creates:

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:

{
  "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:

{
  "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:

calor_check         - Diagnose, lint, type check, or validate
calor_verify        - Verify function contracts
calor_navigate      - Definitions, references, symbols, and scope
calor_structure     - Outlines, call graphs, and impact

Example: Contract Verification

Gemini can verify your contracts are correct:

You: Does this function have any contract violations?

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

Gemini: [Uses calor_verify]
The precondition is satisfiable and excludes b = 0 for valid callers.
It is assumed while verifying the body; the runtime precondition check remains.

Available Tools

See calor mcp for the complete 18-tool surface.

Available Skills

The @calor Skill

Use @calor to activate Calor-aware code generation:

@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:

@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

Best Practices

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

Troubleshooting

Hook Not Blocking Files

Verify the settings file exists:

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:

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

See Also

• Syntax Reference - Complete language reference
• calor init - Full init command documentation
• MCP Server - MCP tools documentation
• Claude Integration - Alternative with Claude Code
• Codex Integration - Alternative with OpenAI Codex CLI