codeflash/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

CodeFlash is an AI-powered Python code optimizer that automatically improves code performance while maintaining correctness. It uses LLMs to generate optimization candidates, verifies correctness through test execution, and benchmarks performance improvements.

Common Commands

# Package management (NEVER use pip)
uv sync                          # Install dependencies
uv sync --group dev              # Install dev dependencies
uv add <package>                 # Add a package

# Running tests
uv run pytest tests/             # Run all tests
uv run pytest tests/test_foo.py  # Run specific test file
uv run pytest tests/test_foo.py::test_bar -v  # Run single test

# Type checking and linting
uv run mypy codeflash/           # Type check
uv run ruff check codeflash/     # Lint
uv run ruff format codeflash/    # Format

# Linting (run before committing)
uv run prek run --from-ref origin/main

# Mypy type checking (run on changed files before committing)
uv run mypy --non-interactive --config-file pyproject.toml <changed_files>

# Running the CLI
uv run codeflash --help
uv run codeflash init            # Initialize in a project
uv run codeflash --all           # Optimize entire codebase

Mypy Type Checking

When modifying code, fix any mypy type errors in the files you changed. Run mypy on changed files:

uv run mypy --non-interactive --config-file pyproject.toml <changed_files>

Rules:

• Fix type annotation issues: missing return types, incorrect types, Optional/None unions, import errors for type hints
• Do NOT add # type: ignore comments — always fix the root cause
• Do NOT fix type errors that require logic changes, complex generic type rework, or anything that could change runtime behavior
• Files in mypy_allowlist.txt are checked in CI — ensure they remain error-free

Agent Rules

@.tessl/RULES.md follow the instructions

@AGENTS.md