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-05-04 18:25:17 +00:00 · 2026-01-20 01:05:02 -05:00 · 2026-01-20 01:05:02 -05:00 · 2b8dfb5d89
commit 2b8dfb5d89
parent 478a2524a1
1 changed files with 96 additions and 0 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@ -0,0 +1,96 @@
+# 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
+
+```bash
+# 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:**
+```python
+from codeflash.either import is_successful, Success, Failure
+result = some_operation()
+if is_successful(result):
+    value = result.unwrap()
+else:
+    error = result.failure()
+```
+
+**Git worktree isolation** - Optimizations run in isolated worktrees to avoid affecting the main repo:
+```python
+from codeflash.code_utils.git_worktree_utils import create_detached_worktree, remove_worktree
+```
+
+**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
+- **Comments**: Minimal - only explain "why", not "what"
+- **Docstrings**: Do not add unless explicitly requested
+- **Paths**: Always use absolute paths, handle encoding explicitly (UTF-8)
+
+## Git Commits
+
+- 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)
+
+# Agent Rules <!-- tessl-managed -->
+
+@.tessl/RULES.md follow the [instructions](.tessl/RULES.md)