cargo-kimi

Cargo subcommand for kimi-dotfiles — structured contracts for Rust.

Installation

cargo install --git https://github.com/ekhodzitsky/cargo-kimi cargo-kimi

Commands

cargo kimi init

Initialize AI coding guidelines in the current project.

cargo kimi init --template rust-only --strictness strict --yes

Templates:

• minimal — Core rules only (AGENTS.md)
• rust-only — Core rules + Rust-specific lints (default)
• full — Core rules + Rust + CI + benchmarks
• modular — Split rules into .kimi/parts/ directory for large projects

cargo kimi check

Run mechanized checks and compute a 0–100 contract score.

cargo kimi check                   # Standard strictness + clippy + tests
cargo kimi check --strictness strict
cargo kimi check --format json     # Pure JSON output for CI (no clippy/test)

Scoring breakdown:

• Hoare triples on pub fn — 30 pts
• No unwrap/expect/panic — 20 pts
• Newtype wrappers — 10 pts
• PhantomData usage — 10 pts
• Typestate patterns — 10 pts
• Average function length ≤ 40 lines — 10 pts
• Proper Result handling — 10 pts

Score exemptions: Add // kimi:score-ignore=unwrap,unsafe in the first 10 lines of a file to waive specific penalties (issues are still reported with [EXEMPT]). Useful for FFI boundaries and generated code.

cargo kimi fix

Auto-fix mechanical issues: insert Hoare triple stubs, replace unwrap() with ?, and add // SAFETY: comments before unsafe blocks.

cargo kimi fix --dry-run           # Preview changes
cargo kimi fix                     # Apply fixes

What it does:

• Adds /// { precondition } / /// { postcondition } doc comments above pub fn
• Replaces .unwrap() → ? where the return type allows it
• Replaces .expect("msg") → .map_err(|e| format!("msg: {e}"))?
• Adds // SAFETY: TODO: explain why this is safe before unsafe blocks

cargo kimi trend

Show score history as an ASCII bar chart.

cargo kimi trend --days 30

Scores are appended to .kimi/score-history.jsonl after every cargo kimi check.

cargo kimi verify

Run formal verification with Kani (requires kani-verifier).

cargo kimi verify

cargo kimi init-skill

Generate a SKILL.md with YAML frontmatter compatible with agentskills.io.

cargo kimi init-skill my-skill "Description of what this skill does"

cargo kimi mcp

Start an MCP server over stdio for Claude Code, Codex, and other MCP clients.

cargo kimi mcp

Exposes the check_contracts tool natively — no shell execution required.

Strictness Levels

• relaxed — Only critical violations fail
• standard — Critical + major (default)
• strict — All violations including minor and info

Options

Kimi Skills

Two skills are included for use inside Kimi Code CLI:

• kimi-check — /kimi.check [--strictness strict] runs contract checks and reports scores
• kimi-fix — /kimi.fix [--dry-run] applies mechanical fixes

Install them by copying skills/kimi-check/ and skills/kimi-fix/ to your ~/.claude/skills/ directory.

GitHub Action

Add contract checking to your CI with automatic PR comments:

# .github/workflows/kimi.yml
name: Kimi Contract Check

on:
  pull_request:
    paths:
      - '**.rs'
      - 'Cargo.toml'

jobs:
  contracts:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - uses: ekhodzitsky/cargo-kimi/.github/actions/cargo-kimi@main
        with:
          strictness: standard
          fail-on-drop: 60
          post-comment: true

Inputs:

Example Workflow

# Initialize a Rust project with strict rules
cargo kimi init --template rust-only --strictness strict --yes

# Check current score
cargo kimi check

# Preview auto-fixes
cargo kimi fix --dry-run

# Apply mechanical fixes
cargo kimi fix

# Re-check after fixes
cargo kimi check

# View score trend over time
cargo kimi trend --days 14