# CLAUDE.md

## Project Overview

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

## Optimization Pipeline

```
Discovery → Ranking → Context Extraction → Test Gen + Optimization → Baseline → Candidate Evaluation → PR
```

1. **Discovery** (`discovery/`): Find optimizable functions across the codebase
2. **Ranking** (`benchmarking/function_ranker.py`): Rank functions by addressable time using trace data
3. **Context** (`languages/<lang>/context/`): Extract code dependencies (read-writable code + read-only imports)
4. **Optimization** (`optimization/`, `api/`): Generate candidates via AI service, run in parallel with test generation
5. **Verification** (`verification/`): Run candidates against tests, compare outputs via custom pytest plugin
6. **Benchmarking** (`benchmarking/`): Measure performance, select best candidate by speedup
7. **Result** (`result/`, `github/`): Create PR with winning optimization

## Domain Glossary

- **Optimization candidate**: A generated code variant that might be faster (`OptimizedCandidate`)
- **Function context**: All code needed for optimization — split into read-writable (modifiable) and read-only (reference)
- **Addressable time**: Time a function spends that could be optimized (own time + callee time / call count)
- **Candidate forest**: DAG of candidates where refinements/repairs build on previous candidates
- **Replay test**: Test generated from recorded benchmark data to reproduce real workloads
- **Tracer**: Profiling system that records function call trees and timings (`tracing/`, `tracer.py`)
- **Worktree mode**: Git worktree-based parallel optimization (`--worktree` flag)

## PR Reviews

- GitHub PR comments and review feedback can be stale — they may reference issues already fixed by a later commit. Before acting on review feedback, verify it still applies to the current code. If the issue no longer exists, resolve the conversation in the GitHub UI.

<!-- Section below is auto-generated by `tessl install` - do not edit manually -->

# Agent Rules <!-- tessl-managed -->

@.tessl/RULES.md follow the [instructions](.tessl/RULES.md)

@AGENTS.md
