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

# Pre-commit (run before committing)
uv run pre-commit run --all-files

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

Architecture

codeflash/
├── main.py                 # CLI entry point
├── cli_cmds/               # Command handling, console output (Rich)
├── discovery/              # Find optimizable functions
├── context/                # Extract code dependencies and imports
├── optimization/           # Generate optimized code via AI
│   ├── optimizer.py        # Main optimization orchestration
│   └── function_optimizer.py  # Per-function optimization logic
├── verification/           # Run deterministic tests (pytest plugin)
├── benchmarking/           # Performance measurement
├── github/                 # PR creation
├── api/                    # AI service communication
├── code_utils/             # Code parsing, git utilities
├── models/                 # Pydantic models and types
├── tracing/                # Function call tracing
├── lsp/                    # IDE integration (Language Server Protocol)
├── telemetry/              # Sentry, PostHog
├── either.py               # Functional Result type for error handling
└── result/                 # Result types and handling

Key Patterns

Either/Result pattern for errors:

from codeflash.either import is_successful, Success, Failure
result = some_operation()
if is_successful(result):
    value = result.unwrap()
else:
    error = result.failure()

Use libcst, not ast - Always use libcst for code parsing/modification to preserve formatting.

Code Style

• Line length: 120 characters
• Python: 3.9+ syntax
• Tooling: Ruff for linting/formatting, mypy strict mode, pre-commit hooks
• Comments: Minimal - only explain "why", not "what"
• Docstrings: Do not add unless explicitly requested
• Naming: Prefer public functions (no leading underscore) - Python doesn't have true private functions
• Paths: Always use absolute paths, handle encoding explicitly (UTF-8)

Git Commits & Pull Requests

• Use conventional commit format: fix:, feat:, refactor:, docs:, test:, chore:
• Keep commits atomic - one logical change per commit
• Commit message body should be concise (1-2 sentences max)
• PR titles should also use conventional format

Agent Rules

@.tessl/RULES.md follow the instructions

@AGENTS.md