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 Rules to follow

Use libcst, not ast - For Python, always use libcst for code parsing/modification to preserve formatting.
Code context extraction and replacement tests must always assert for full string equality, no substring matching.
Any new feature or bug fix that can be tested automatically must have test cases.

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

3.6 KiB Raw Blame History