check-my-code (cmc)

A CLI tool that runs ESLint and Ruff linters on your code with a unified interface. It acts as a configuration manager, verification layer, and context provider for AI coding agents.

The Problem

Every repository has its own ESLint and Ruff configs, leading to:

• Configuration sprawl across projects
• Config drift as developers make local changes
• Friction adopting organization-wide standards
• AI agents that don't know your team's coding standards

The Solution

cmc uses cmc.toml as a single source of truth:

• Define rules once, generate linter configs as artifacts
• Inherit rules from remote repositories (private or community)
• Provide context to AI agents so they write compliant code from the start

Features

• Unified linting: Run ESLint (TypeScript/JavaScript) and Ruff (Python) with a single command
• Configuration management: Generate and audit linter configs from a central cmc.toml
• AI context: Export coding standards for AI coding agents (Claude, Cursor, Copilot)
• MCP server: Enable AI agents to proactively lint code via Model Context Protocol
• Graceful degradation: Works with whatever linters you have installed

Installation

npm install -g check-my-code

Requires Node.js >= 18.

Quick Start

1. Create a cmc.toml in your project root:

[project]
name = "my-project"

2. Run the linter:

cmc check

Commands

cmc check

Run linters on project files and report violations.

cmc check                     # Check entire project
cmc check src/                # Check specific directory
cmc check src/main.ts         # Check specific file
cmc check --json              # Output as JSON

cmc generate

Generate linter config files from cmc.toml ruleset.

cmc generate eslint           # Generate eslint.config.js
cmc generate ruff             # Generate ruff.toml
cmc generate eslint --force   # Overwrite existing config
cmc generate eslint --stdout  # Output to stdout

cmc audit

Check that linter configs match the ruleset defined in cmc.toml.

cmc audit                    # Audit all linter configs
cmc audit eslint             # Audit only ESLint config
cmc audit ruff               # Audit only Ruff config

cmc context

Append coding standards context to AI agent configuration files.

cmc context --target claude   # Appends to CLAUDE.md
cmc context --target cursor   # Appends to .cursorrules
cmc context --target copilot  # Appends to .github/copilot-instructions.md
cmc context --stdout          # Output to stdout

cmc mcp-server

Start an MCP (Model Context Protocol) server for AI agent integration.

cmc mcp-server                # Start MCP server (communicates via stdio)

cmc info

Display supported languages, runtimes, and linters.

cmc info                      # Show compatibility info
cmc info --json               # Output as JSON

MCP Server

The MCP server enables AI agents to proactively lint code and enforce coding standards. It exposes 7 tools:

| Tool | Description | | ----------------- | ------------------------------------------ | | check_files | Lint specific files | | check_project | Lint entire project or subdirectory | | fix_files | Auto-fix violations in files | | get_guidelines | Fetch coding standards templates | | get_status | Get current session state | | suggest_config | Generate cmc.toml from project description | | validate_config | Validate TOML against cmc.toml schema |

Setup

Claude Code:

claude mcp add cmc -- npx -y check-my-code mcp-server

Cursor / Claude Desktop / other MCP clients:

Add to your MCP configuration:

{
  "mcpServers": {
    "cmc": {
      "command": "npx",
      "args": ["-y", "check-my-code", "mcp-server"]
    }
  }
}

Configuration

Basic cmc.toml

[project]
name = "my-project"

With Custom Rules

[project]
name = "my-project"

# ESLint rules
[rulesets.eslint.rules]
"no-console" = "error"
"@typescript-eslint/no-explicit-any" = "error"

# Ruff configuration
[rulesets.ruff]
line-length = 100

[rulesets.ruff.lint]
select = ["E", "F", "I", "UP"]

With AI Context

[project]
name = "my-project"

[prompts]
templates = ["internal/typescript/5.5", "internal/python/3.12"]

AI Context Templates

The cmc context command fetches templates from the check-my-code-community repository.

Template format: <tier>/<language>/<version>

Available tiers:

| Tier | Description | | ------------ | -------------------------------------------------------- | | prototype | Minimal standards for quick prototypes and experiments | | internal | Standards for internal tools and team-facing apps | | production | Strict standards for production and customer-facing code |

Available templates:

| Template | Description | | --------------------------- | -------------------------------------------- | | internal/typescript/5.5 | TypeScript 5.5 coding standards (Node.js 20) | | internal/python/3.12 | Python 3.12 coding standards | | production/typescript/5.5 | Strict TypeScript 5.5 standards | | production/python/3.12 | Strict Python 3.12 standards | | prototype/typescript/5.5 | Minimal TypeScript 5.5 standards | | prototype/python/3.12 | Minimal Python 3.12 standards |

Use them in your cmc.toml:

[prompts]
templates = ["internal/typescript/5.5", "internal/python/3.12"]

You can pin a specific version:

[prompts]
templates = ["internal/typescript/[email protected]"]

You can also use a custom source repository:

[prompts]
templates = ["my-template"]
source = "github:myorg/my-templates/[email protected]"

Exit Codes

| Code | Meaning | | ---- | ----------------------- | | 0 | Success (no violations) | | 1 | Violations found | | 2 | Configuration error | | 3 | Runtime error |

Supported Languages & Tools

Run cmc info for the full compatibility matrix, or cmc info --json for machine-readable output.

| Language | Version | Linter | Extensions | | ---------- | ------- | ------ | -------------------------------------------- | | TypeScript | 5.5 | ESLint | .ts, .tsx, .js, .jsx, .mjs, .cjs | | Python | 3.12 | Ruff | .py, .pyi |

| Tool | Description | Install | | ------ | ---------------------------- | ------------------------ | | ESLint | JavaScript/TypeScript linter | npm install eslint | | Ruff | Fast Python linter | pip install ruff | | tsc | TypeScript type checker | npm install typescript |

Runtime: Node.js >= 20

Linters are optional - cmc gracefully skips files if the corresponding linter isn't installed.

Troubleshooting

ESLint not found

Skipping ESLint: not installed

Install ESLint in your project:

npm install eslint @eslint/js typescript-eslint --save-dev

Or globally:

npm install -g eslint

Ruff not found

Skipping Ruff: not installed

Install Ruff:

# macOS
brew install ruff

# pip
pip install ruff

# pipx
pipx install ruff

No cmc.toml found

Error: No cmc.toml found

Create a cmc.toml file in your project root:

[project]
name = "my-project"

Template not found

Error: Template "my-template" not found

Check that the template name matches one of the available templates, or audit your custom source repository contains the template file.

Git not available (for remote templates)

Error: git is not installed or not in PATH

The cmc context command uses git to fetch remote templates. Install git:

# macOS
xcode-select --install

# Ubuntu/Debian
sudo apt install git

# Windows
winget install Git.Git

Design Principles

• Single source of truth: cmc.toml is authoritative; linter configs are generated artifacts
• Additive-only inheritance: Projects can only add or strengthen rules, not weaken them
• Linter-first: Delegates to native linters (ESLint, Ruff) for actual checking
• Graceful degradation: Silently skips missing linters rather than failing
• Agent-agnostic: Works with any AI coding tool via standardized context output

Roadmap

v1 (Current)

• CLI commands: check, generate, audit, context, mcp-server
• ESLint + Ruff support
• AI context templates from community repository
• MCP server for AI agent integration

v2 (Planned)

• Config inheritance: Remote config inheritance from git repositories
• Environment enforcers: Verify version managers (mise, asdf), container runtimes (Docker, Podman), and required files
• Extended linting: Formatting, type safety, security, complexity checks
• Custom hooks: User-defined pre/post validation scripts

License

MIT