CodeFlash AI Agent Instructions

Project Overview

CodeFlash is an AI-powered Python code optimizer that automatically improves code performance while maintaining correctness.

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
├── 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
├── telemetry/              # Sentry, PostHog
└── either.py               # Functional error handling

Critical Development Patterns

Use uv, NEVER pip

NEVER use pip install or pip commands. This project uses uv exclusively for package management.

uv sync                    # Install dependencies (NOT pip install -r requirements.txt)
uv sync --group dev        # Dev dependencies (NOT pip install -e .)
uv run pytest              # Run commands (NOT python -m pytest)
uv add package             # Add packages (NOT pip install package)

Use libcst, not ast

Always use libcst for code parsing/modification to preserve formatting.

Use Either pattern for errors

from codeflash.either import is_successful
result = aiservice_client.call_llm(...)
if is_successful(result):
    optimized_code = result.value
else:
    error = result.error

Git worktree isolation

Optimizations run in isolated worktrees:

from codeflash.code_utils.git_worktree_utils import create_detached_worktree, remove_worktree

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 (e.g., fix: resolve base class dependency tracking)

Code Style & Conventions

Tooling: Ruff for linting/formatting, mypy strict mode, pre-commit hooks
Line length: 120 characters
Python: 3.9+ syntax
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)

Agent Rules

@.tessl/RULES.md follow the instructions

2.9 KiB Raw Blame History