codeflash/CLAUDE.md

# CLAUDE.md

## Project Overview

CodeFlash is an AI-powered code optimizer that automatically improves performance while maintaining correctness. It supports Python, JavaScript, TypeScript, Java 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
```

See `.claude/rules/architecture.md` for directory mapping and entry points.

## Setup

```bash
uv sync                  # Install all dependencies
uv run prek install      # Install git pre-commit hooks (ruff + mypy)
```

## Bug Fix Workflow

Follow these steps in order, do not skip ahead:

1. Read the relevant code to understand the bug
2. Write a test that reproduces the bug (run it to confirm it fails)
3. Spawn subagents (using the Agent tool) to attempt the fix — each subagent should apply a fix and run the test to prove it passes
4. Review the subagent results, pick the best fix, and apply it
5. Never jump straight to writing a fix yourself — always go through steps 1-4

Everything that can be tested should have tests.
docs: add comprehensive CLAUDE.md for Claude Code Consolidates project guidance including common commands, architecture overview, key patterns (Either/Result, git worktree isolation, libcst), and code style conventions. 2026-01-20 06:05:02 +00:00			`# CLAUDE.md`

			`## Project Overview`

update 2026-03-16 04:41:26 +00:00			`CodeFlash is an AI-powered code optimizer that automatically improves performance while maintaining correctness. It supports Python, JavaScript, TypeScript, Java with more languages planned. It uses LLMs to generate optimization candidates, verifies correctness through test execution, and benchmarks performance improvements.`
docs: add comprehensive CLAUDE.md for Claude Code Consolidates project guidance including common commands, architecture overview, key patterns (Either/Result, git worktree isolation, libcst), and code style conventions. 2026-01-20 06:05:02 +00:00
refactor: restructure CLAUDE.md for effective context usage - Remove commands block from CLAUDE.md (standard tool usage Claude knows) - Remove dead @AGENTS.md reference - Add optimization pipeline overview with module pointers - Add domain glossary (optimization candidate, addressable time, candidate forest, replay test, tracer, worktree mode) - Extract mypy workflow to .claude/skills/fix-mypy.md (on-demand) - Create .claude/skills/fix-prek.md for prek workflow (on-demand) - Add key entry points table to architecture.md - Create path-scoped rules: optimization-patterns.md, language-patterns.md - Remove redundancy from source-code.md and across rules files - Move "never use pip" convention to code-style.md 2026-02-14 22:37:51 +00:00			`## Optimization Pipeline`
docs: add comprehensive CLAUDE.md for Claude Code Consolidates project guidance including common commands, architecture overview, key patterns (Either/Result, git worktree isolation, libcst), and code style conventions. 2026-01-20 06:05:02 +00:00
refactor: restructure CLAUDE.md for effective context usage - Remove commands block from CLAUDE.md (standard tool usage Claude knows) - Remove dead @AGENTS.md reference - Add optimization pipeline overview with module pointers - Add domain glossary (optimization candidate, addressable time, candidate forest, replay test, tracer, worktree mode) - Extract mypy workflow to .claude/skills/fix-mypy.md (on-demand) - Create .claude/skills/fix-prek.md for prek workflow (on-demand) - Add key entry points table to architecture.md - Create path-scoped rules: optimization-patterns.md, language-patterns.md - Remove redundancy from source-code.md and across rules files - Move "never use pip" convention to code-style.md 2026-02-14 22:37:51 +00:00			```
chore: rebuild .claude config from scratch Delete all existing .claude/ tracked files and recreate from scratch, adapting patterns from codeflash-agent. Hooks (6, up from 1): - bash-guard: blocks grep/find/cat in Bash, redirects to dedicated tools - require-read + track-read: enforces Read-before-Write/Edit - post-compact: injects git state + project conventions into compaction - post-edit-lint: runs prek on edited Python files (kept) - status-line: shows user, area, branch, dirty state Rules (10, up from 8): - New: sessions, debugging, github (from codeflash-agent) - Rewrote: code-style (absorbed source-code), git (added sizing/hygiene) - Removed: source-code (folded into code-style) Settings: permissions allowlist, attribution, includeCoAuthoredBy, full hook wiring, status line, enableAllProjectMcpServers. .gitignore: whitelist .claude/skills/ for tracking. 2026-04-23 09:31:04 +00:00			`Discovery -> Ranking -> Context Extraction -> Test Gen + Optimization -> Baseline -> Candidate Evaluation -> PR`
docs: add comprehensive CLAUDE.md for Claude Code Consolidates project guidance including common commands, architecture overview, key patterns (Either/Result, git worktree isolation, libcst), and code style conventions. 2026-01-20 06:05:02 +00:00			```

chore: reorganize Claude rules and add workflow guidelines Move pre-commit/pre-push prek rules from code-style.md to git.md, deduplicate pipeline docs in CLAUDE.md, and add shared workflow rules. 2026-03-27 14:43:53 +00:00			See `.claude/rules/architecture.md` for directory mapping and entry points.
docs: add mypy type checking instructions to CLAUDE.md 2026-02-11 03:05:10 +00:00
chore: add mypy to pre-commit config and document setup - Add mypy as a local pre-commit hook via prek (ruff-check + ruff-format + mypy now all run at commit time) - Add Setup section to CLAUDE.md with uv sync and prek install steps 2026-04-23 09:38:34 +00:00			`## Setup`

			```bash
			`uv sync # Install all dependencies`
			`uv run prek install # Install git pre-commit hooks (ruff + mypy)`
			```

chore: rebuild .claude config from scratch Delete all existing .claude/ tracked files and recreate from scratch, adapting patterns from codeflash-agent. Hooks (6, up from 1): - bash-guard: blocks grep/find/cat in Bash, redirects to dedicated tools - require-read + track-read: enforces Read-before-Write/Edit - post-compact: injects git state + project conventions into compaction - post-edit-lint: runs prek on edited Python files (kept) - status-line: shows user, area, branch, dirty state Rules (10, up from 8): - New: sessions, debugging, github (from codeflash-agent) - Rewrote: code-style (absorbed source-code), git (added sizing/hygiene) - Removed: source-code (folded into code-style) Settings: permissions allowlist, attribution, includeCoAuthoredBy, full hook wiring, status line, enableAllProjectMcpServers. .gitignore: whitelist .claude/skills/ for tracking. 2026-04-23 09:31:04 +00:00			`## Bug Fix Workflow`

			`Follow these steps in order, do not skip ahead:`

			`1. Read the relevant code to understand the bug`
			`2. Write a test that reproduces the bug (run it to confirm it fails)`
			`3. Spawn subagents (using the Agent tool) to attempt the fix — each subagent should apply a fix and run the test to prove it passes`
			`4. Review the subagent results, pick the best fix, and apply it`
			`5. Never jump straight to writing a fix yourself — always go through steps 1-4`

			`Everything that can be tested should have tests.`