codeflash-ai/codeflash
1
0
Fork 0
Code Issues 18 Pull requests 33 Projects Releases Packages Wiki Activity Actions 5.0k

chore: sync docs, rules, and workflows from main

Browse source
This commit is contained in:
Kevin Turcios 2026-03-02 22:48:28 -05:00
parent e8e1e2bb1a
commit 08dad4e6a4
20 changed files with 965 additions and 492 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

51
.claude/rules/architecture.md
View file

@ -1,11 +1,12 @@
# Architecture
When adding, moving, or deleting source files, update this doc to match.
```
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
@ -15,7 +16,21 @@ codeflash/
├── api/ # AI service communication
├── code_utils/ # Code parsing, git utilities
├── models/ # Pydantic models and types
├── languages/ # Multi-language support (Python, JavaScript/TypeScript)
├── languages/ # Multi-language support (Python, JavaScript/TypeScript, Java planned)
│ ├── base.py # LanguageSupport protocol and shared data types
│ ├── registry.py # Language registration and lookup by extension/enum
│ ├── current.py # Current language singleton (set_current_language / current_language_support)
│ ├── code_replacer.py # Language-agnostic code replacement
│ ├── python/
│ │ ├── support.py # PythonSupport (LanguageSupport implementation)
│ │ ├── function_optimizer.py # PythonFunctionOptimizer subclass
│ │ ├── optimizer.py # Python module preparation & AST resolution
│ │ └── normalizer.py # Python code normalization for deduplication
│ └── javascript/
│ ├── support.py # JavaScriptSupport (LanguageSupport implementation)
│ ├── function_optimizer.py # JavaScriptFunctionOptimizer subclass
│ ├── optimizer.py # JS project root finding & module preparation
│ └── normalizer.py # JS/TS code normalization for deduplication
├── setup/ # Config schema, auto-detection, first-run experience
├── picklepatch/ # Serialization/deserialization utilities
├── tracing/ # Function call tracing
@ -33,10 +48,36 @@ codeflash/
|------|------------|
| CLI arguments & commands | `cli_cmds/cli.py` |
| Optimization orchestration | `optimization/optimizer.py` → `run()` |
| Per-function optimization | `optimization/function_optimizer.py` |
| Per-function optimization | `optimization/function_optimizer.py` (base), `languages/python/function_optimizer.py`, `languages/javascript/function_optimizer.py` |
| Function discovery | `discovery/functions_to_optimize.py` |
| Context extraction | `context/code_context_extractor.py` |
| Test execution | `verification/test_runner.py`, `verification/pytest_plugin.py` |
| Context extraction | `languages/<lang>/context/code_context_extractor.py` |
| Test execution | `languages/<lang>/support.py` (`run_behavioral_tests`, etc.), `verification/pytest_plugin.py` |
| Performance ranking | `benchmarking/function_ranker.py` |
| Domain types | `models/models.py`, `models/function_types.py` |
| Result handling | `either.py` (`Result`, `Success`, `Failure`, `is_successful`) |
## LanguageSupport Protocol Methods
Core protocol in `languages/base.py`. Each language (`PythonSupport`, `JavaScriptSupport`) implements these.
| Category | Method/Property | Purpose |
|----------|----------------|---------|
| Identity | `language`, `file_extensions`, `default_file_extension` | Language identification |
| Identity | `comment_prefix`, `dir_excludes` | Language conventions |
| AI service | `default_language_version` | Language version for API payloads (`None` for Python, `"ES2022"` for JS) |
| AI service | `valid_test_frameworks` | Allowed test frameworks for validation |
| Discovery | `discover_functions`, `discover_tests` | Find optimizable functions and their tests |
| Discovery | `adjust_test_config_for_discovery` | Pre-discovery config adjustment (no-op default) |
| Context | `extract_code_context`, `find_helper_functions`, `find_references` | Code dependency extraction |
| Transform | `replace_function`, `format_code`, `normalize_code` | Code modification |
| Validation | `validate_syntax` | Syntax checking |
| Test execution | `run_behavioral_tests`, `run_benchmarking_tests`, `run_line_profile_tests` | Test runners |
| Test results | `test_result_serialization_format` | `"pickle"` (Python) or `"json"` (JS) |
| Test results | `load_coverage` | Load coverage from language-specific format |
| Test results | `compare_test_results` | Equivalence checking between original and candidate |
| Test gen | `postprocess_generated_tests` | Post-process `GeneratedTestsList` objects |
| Test gen | `process_generated_test_strings` | Instrument/transform raw generated test strings |
| Module | `detect_module_system` | Detect project module system (`None` for Python, `"esm"`/`"commonjs"` for JS) |
| Module | `prepare_module` | Parse/validate module before optimization |
| Setup | `setup_test_config` | One-time project setup after language detection |
| Optimizer | `function_optimizer_class` | Return `FunctionOptimizer` subclass for this language |

3
.claude/rules/code-style.md
View file

@ -7,4 +7,5 @@
- **Comments**: Minimal - only explain "why", not "what"
- **Docstrings**: Do not add unless explicitly requested
- **Naming**: NEVER use leading underscores (`_function_name`) - Python has no true private functions, use public names
- **Paths**: Always use absolute paths, handle encoding explicitly (UTF-8)
- **Paths**: Always use absolute paths
- **Encoding**: Always pass `encoding="utf-8"` to `open()`, `read_text()`, `write_text()`, etc. in new or changed code — Windows defaults to `cp1252` which breaks on non-ASCII content. Don't flag pre-existing code that lacks it unless you're already modifying that line.

3
.claude/rules/language-patterns.md
View file

@ -9,4 +9,5 @@ paths:
- Use `get_language_support(identifier)` from `languages/registry.py` to get a `LanguageSupport` instance — never import language classes directly
- New language support classes must use the `@register_language` decorator to register with the extension and language registries
- `languages/__init__.py` uses `__getattr__` for lazy imports to avoid circular dependencies — follow this pattern when adding new exports
- `is_javascript()` returns `True` for both JavaScript and TypeScript
- Prefer `LanguageSupport` protocol dispatch over `is_python()`/`is_javascript()` guards — remaining guards are being migrated to protocol methods
- `is_javascript()` returns `True` for both JavaScript and TypeScript (still used in ~15 call sites pending migration)

2
.claude/rules/optimization-patterns.md
View file

@ -3,7 +3,7 @@ paths:
- "codeflash/optimization/**/*.py"
- "codeflash/verification/**/*.py"
- "codeflash/benchmarking/**/*.py"
- "codeflash/context/**/*.py"
- "codeflash/languages/*/context/**/*.py"
---
# Optimization Pipeline Patterns

243
.github/workflows/claude.yml vendored
View file

@ -1,8 +1,20 @@
name: Claude Code
on:
workflow_dispatch:
pull_request:
types: [opened, synchronize, ready_for_review, reopened]
paths-ignore:
- '.github/workflows/**'
- '*.md'
- 'docs/**'
- 'demos/**'
- 'experiments/**'
- 'LICENSE'
- '.tessl/**'
- 'code_to_optimize/**'
- 'codeflash.code-workspace'
- 'uv.lock'
issue_comment:
types: [created]
pull_request_review_comment:
@ -16,10 +28,16 @@ jobs:
# Automatic PR review (can fix linting issues and push)
# Blocked for fork PRs to prevent malicious code execution
pr-review:
concurrency:
group: pr-review-${{ github.head_ref || github.run_id }}
cancel-in-progress: true
if: |
github.event_name == 'pull_request' &&
github.actor != 'claude[bot]' &&
github.event.pull_request.head.repo.full_name == github.repository
(
github.event_name == 'pull_request' &&
github.event.sender.login != 'claude[bot]' &&
github.event.pull_request.head.repo.full_name == github.repository
) ||
github.event_name == 'workflow_dispatch'
runs-on: ubuntu-latest
permissions:
contents: write
@ -32,7 +50,7 @@ jobs:
uses: actions/checkout@v4
with:
fetch-depth: 0
ref: ${{ github.event.pull_request.head.ref }}
ref: ${{ github.event.pull_request.head.ref || github.ref }}
- name: Install uv
uses: astral-sh/setup-uv@v6
@ -54,137 +72,162 @@ jobs:
with:
use_bedrock: "true"
use_sticky_comment: true
track_progress: true
allowed_bots: "claude[bot],codeflash-ai[bot]"
exclude_comments_by_actor: "*[bot]"
prompt: |
REPO: ${{ github.repository }}
PR NUMBER: ${{ github.event.pull_request.number }}
EVENT: ${{ github.event.action }}
<context>
repo: ${{ github.repository }}
pr_number: ${{ github.event.pull_request.number }}
event: ${{ github.event.action }}
is_re_review: ${{ github.event.action == 'synchronize' }}
</context>
## STEP 1: Run prek and mypy checks, fix issues
<commitment>
Execute these steps in order. If a step has no work, state that and continue to the next step.
Post all review findings in a single summary comment only — never as inline PR review comments.
</commitment>
First, run these checks on files changed in this PR:
1. `uv run prek run --from-ref origin/main` - linting/formatting issues
2. `uv run mypy <changed_files>` - type checking issues
<step name="triage">
Before doing any work, assess the PR scope:
If there are prek issues:
- For SAFE auto-fixable issues (formatting, import sorting, trailing whitespace, etc.), run `uv run prek run --from-ref origin/main` again to auto-fix them
- For issues that prek cannot auto-fix, do NOT attempt to fix them manually — report them as remaining issues in your summary
1. Run `gh pr diff ${{ github.event.pull_request.number }} --name-only` to get changed files.
2. Classify as TRIVIAL if ALL changed files are:
- Config/CI files (.github/, .tessl/, *.toml, *.lock, *.json, *.yml, *.yaml)
- Documentation (*.md, docs/)
- Non-production code (demos/, experiments/, code_to_optimize/)
- Only whitespace, formatting, or comment changes
If there are mypy issues:
- Fix type annotation issues (missing return types, Optional/None unions, import errors for type hints, incorrect types)
- Do NOT add `type: ignore` comments - always fix the root cause
If TRIVIAL: post a single comment "No substantive code changes to review." and stop — do not execute any further steps.
Otherwise: continue with the full review below.
</step>
After fixing issues:
- Stage the fixed files with `git add`
- Commit with message "style: auto-fix linting issues" or "fix: resolve mypy type errors" as appropriate
- Push the changes with `git push`
<step name="lint_and_typecheck">
Run checks on files changed in this PR and auto-fix what you can.
IMPORTANT - Verification after fixing:
- After committing fixes, run `uv run prek run --from-ref origin/main` ONE MORE TIME to verify all issues are resolved
- If errors remain, either fix them or report them honestly as unfixed in your summary
- NEVER claim issues are fixed without verifying. If you cannot fix an issue, say so
1. Run `uv run prek run --from-ref origin/main` to check linting/formatting.
If there are auto-fixable issues, run it again to fix them.
Report any issues prek cannot auto-fix in your summary.
Do NOT attempt to fix:
- Type errors that require logic changes or refactoring
- Complex generic type issues
- Anything that could change runtime behavior
2. Run `uv run mypy <changed_files>` to check types.
Fix type annotation issues (missing return types, Optional unions, import errors).
Always fix the root cause instead of adding `type: ignore` comments.
Leave alone: type errors requiring logic changes, complex generics, anything changing runtime behavior.
## STEP 2: Review the PR
3. After fixes: stage with `git add`, commit ("style: auto-fix linting issues" or "fix: resolve mypy type errors"), push.
${{ github.event.action == 'synchronize' && 'This is a RE-REVIEW after new commits. First, get the list of changed files in this latest push using `gh pr diff`. Review ONLY the changed files. Check ALL existing review comments and resolve ones that are now fixed.' || 'This is the INITIAL REVIEW.' }}
4. Verify by running `uv run prek run --from-ref origin/main` one more time. Report honestly if issues remain.
</step>
Review this PR focusing ONLY on:
1. Critical bugs or logic errors
<step name="resolve_stale_threads">
Before reviewing, resolve any stale review threads from previous runs.
1. Fetch unresolved threads you created:
`gh api graphql -f query='{ repository(owner: "${{ github.repository_owner }}", name: "${{ github.event.repository.name }}") { pullRequest(number: ${{ github.event.pull_request.number }}) { reviewThreads(first: 100) { nodes { id isResolved path comments(first: 1) { nodes { body author { login } } } } } } } }' --jq '.data.repository.pullRequest.reviewThreads.nodes[] | select(.isResolved == false) | select(.comments.nodes[0].author.login == "claude") | {id: .id, path: .path, body: .comments.nodes[0].body}'`
2. For each unresolved thread:
a. Read the file at that path to check if the issue still exists
b. If fixed → resolve it: `gh api graphql -f query='mutation { resolveReviewThread(input: {threadId: "<THREAD_ID>"}) { thread { isResolved } } }'`
c. If still present → leave it
Read the actual code before deciding. If there are no unresolved threads, skip to the next step.
</step>
<step name="review">
Review the diff (`gh pr diff ${{ github.event.pull_request.number }}`) for:
1. Bugs that will crash at runtime
2. Security vulnerabilities
3. Breaking API changes
4. Test failures (methods with typos that wont run)
IMPORTANT:
- First check existing review comments using `gh api repos/${{ github.repository }}/pulls/${{ github.event.pull_request.number }}/comments`. For each existing comment, check if the issue still exists in the current code.
- If an issue is fixed, use `gh api --method PATCH repos/${{ github.repository }}/pulls/comments/COMMENT_ID -f body="✅ Fixed in latest commit"` to resolve it.
- Only create NEW inline comments for HIGH-PRIORITY issues found in changed files.
- Limit to 5-7 NEW comments maximum per review.
- Use CLAUDE.md for project-specific guidance.
- Use `mcp__github_inline_comment__create_inline_comment` sparingly for critical code issues only.
Ignore style issues, type hints, and log message wording.
Record findings for the summary comment. Refer to CLAUDE.md for project conventions.
</step>
## STEP 3: Coverage analysis
<step name="duplicate_detection">
Check whether this PR introduces code that duplicates logic already present elsewhere in the repository — including across languages. Focus on finding true duplicates, not just similar-looking code.
1. Get changed source files (excluding tests and config):
`git diff --name-only origin/main...HEAD -- '*.py' '*.js' '*.ts' '*.java' | grep -v -E '(test_|_test\.(py|js|ts)|\.test\.(js|ts)|\.spec\.(js|ts)|conftest\.py|/tests/|/test/|/__tests__/)' | grep -v -E '^(\.github/|code_to_optimize/|\.tessl/|node_modules/)'`
2. For each changed file, read it and identify functions/methods added or substantially modified (longer than 5 lines).
3. Search for duplicates using Grep:
- Same function name defined elsewhere
- 2-3 distinctive operations from the body (specific API calls, algorithm patterns, string literals)
4. Cross-module check: this codebase has parallel modules under `languages/python/`, `languages/javascript/`, and `languages/java/` plus runtimes under `packages/codeflash/runtime/` and `codeflash-java-runtime/`. When a changed file is under one of these areas, search the others for equivalent logic. Only flag cases where the logic is genuinely shared or one module could import from the other.
5. When a Grep hit looks promising, read the full function and compare semantics. Flag only:
- Same function with same/very similar body in another module
- Same helper logic repeated in sibling files
- Same logic implemented inline across multiple classes
- Same algorithm reimplemented across language modules (Python code, not target-language differences)
Report at most 5 findings with confidence (HIGH/MEDIUM), locations, what's duplicated, and suggestion.
DO NOT report: boilerplate, functions under 5 lines, config/setup, intentional polymorphism, test files, imports, code that must differ due to target-language semantics.
If no duplicates found, include "No duplicates detected" in the summary.
</step>
<step name="coverage">
Analyze test coverage for changed files:
1. Get the list of Python files changed in this PR (excluding tests):
`git diff --name-only origin/main...HEAD -- '*.py' | grep -v test`
1. Get changed Python files (excluding tests): `git diff --name-only origin/main...HEAD -- '*.py' | grep -v test`
2. Run coverage on PR branch: `uv run coverage run -m pytest tests/ -q --tb=no` then `uv run coverage json -o coverage-pr.json`
3. Get per-file coverage: `uv run coverage report --include="<changed_files>"`
4. Compare with main: checkout main, run coverage, checkout back
5. Flag: new files below 75%, decreased coverage, untested changed lines
</step>
2. Run tests with coverage on the PR branch:
`uv run coverage run -m pytest tests/ -q --tb=no`
`uv run coverage json -o coverage-pr.json`
<step name="summary_comment">
Post exactly one summary comment containing all results from previous steps using this format:
3. Get coverage for changed files only:
`uv run coverage report --include="<changed_files_comma_separated>"`
4. Compare with main branch coverage:
- Checkout main: `git checkout origin/main`
- Run coverage: `uv run coverage run -m pytest tests/ -q --tb=no && uv run coverage json -o coverage-main.json`
- Checkout back: `git checkout -`
5. Analyze the diff to identify:
- NEW FILES: Files that don't exist on main (require good test coverage)
- MODIFIED FILES: Files with changes (changes must be covered by tests)
6. Report in PR comment with a markdown table:
- Coverage % for each changed file (PR vs main)
- Overall coverage change
- For NEW files: Flag if coverage is below 75%
- For MODIFIED files: Flag if the changed lines are not covered by tests
- Flag if overall coverage decreased
Coverage requirements:
- New implementations/files: Must have ≥75% test coverage
- Modified code: Changed lines should be exercised by existing or new tests
- No coverage regressions: Overall coverage should not decrease
## STEP 4: Post ONE consolidated summary comment
CRITICAL: You must post exactly ONE summary comment containing ALL results (pre-commit, review, coverage).
DO NOT post multiple separate comments. Use this format:
```
## PR Review Summary
### Prek Checks
[status and any fixes made]
### Code Review
[critical issues found, if any]
### Duplicate Detection
### Test Coverage
[coverage table and analysis]
---
*Last updated: <timestamp>*
```
</step>
To ensure only ONE comment exists:
1. Find existing claude[bot] comment: `gh api repos/${{ github.repository }}/issues/${{ github.event.pull_request.number }}/comments --jq '.[] | select(.user.login == "claude[bot]") | .id' | head -1`
2. If found, UPDATE it: `gh api --method PATCH repos/${{ github.repository }}/issues/comments/<ID> -f body="<content>"`
3. If not found, CREATE: `gh pr comment ${{ github.event.pull_request.number }} --body "<content>"`
4. Delete any OTHER claude[bot] comments to clean up duplicates: `gh api repos/${{ github.repository }}/issues/${{ github.event.pull_request.number }}/comments --jq '.[] | select(.user.login == "claude[bot]") | .id' | tail -n +2 | xargs -I {} gh api --method DELETE repos/${{ github.repository }}/issues/comments/{}`
<step name="simplify">
Run /simplify to review recently changed code for reuse, quality, and efficiency opportunities.
If improvements are found, commit with "refactor: simplify <description>" and push.
Only make behavior-preserving changes.
</step>
## STEP 5: Merge pending codeflash optimization PRs
<step name="merge_optimization_prs">
Check for open PRs from codeflash-ai[bot]:
`gh pr list --author "codeflash-ai[bot]" --state open --json number,title,headRefName,createdAt,mergeable`
Check for open optimization PRs from codeflash and merge if CI passes:
For each PR:
- If CI passes and the PR is mergeable → merge with `--squash --delete-branch`
- Close the PR as stale if ANY of these apply:
- Older than 7 days
- Has merge conflicts (mergeable state is "CONFLICTING")
- CI is failing
- The optimized function no longer exists in the target file (check the diff)
Close with: `gh pr close <number> --comment "Closing stale optimization PR." --delete-branch`
</step>
1. List open PRs from codeflash bot:
`gh pr list --author "codeflash-ai[bot]" --state open --json number,title,headRefName`
2. For each optimization PR:
- Check if CI is passing: `gh pr checks <number>`
- If all checks pass, merge it: `gh pr merge <number> --squash --delete-branch`
claude_args: '--model us.anthropic.claude-opus-4-6-v1 --allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr list:*),Bash(gh pr checks:*),Bash(gh pr merge:*),Bash(gh issue view:*),Bash(gh issue list:*),Bash(gh api:*),Bash(uv run prek *),Bash(uv run mypy *),Bash(uv run coverage *),Bash(uv run pytest *),Bash(git status*),Bash(git add *),Bash(git commit *),Bash(git push*),Bash(git diff *),Bash(git checkout *),Read,Glob,Grep,Edit"'
<verification>
Before finishing, confirm:
- All steps were attempted (even if some had no work)
- Stale review threads were checked and resolved where appropriate
- All findings are in a single summary comment (no inline review comments were created)
- If fixes were made, they were verified with prek
</verification>
claude_args: '--model us.anthropic.claude-sonnet-4-6 --max-turns 25 --allowedTools "Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr list:*),Bash(gh pr checks:*),Bash(gh pr merge:*),Bash(gh issue view:*),Bash(gh issue list:*),Bash(gh api:*),Bash(uv run prek *),Bash(uv run mypy *),Bash(uv run coverage *),Bash(uv run pytest *),Bash(git status*),Bash(git add *),Bash(git commit *),Bash(git push*),Bash(git diff *),Bash(git checkout *),Read,Glob,Grep,Edit,Skill"'
additional_permissions: |
actions: read
# @claude mentions (can edit and push) - restricted to maintainers only
claude-mention:
concurrency:
group: claude-mention-${{ github.event.issue.number || github.event.pull_request.number || github.run_id }}
cancel-in-progress: false
if: |
(
github.event_name == 'issue_comment' &&
@ -254,6 +297,6 @@ jobs:
uses: anthropics/claude-code-action@v1
with:
use_bedrock: "true"
claude_args: '--model us.anthropic.claude-opus-4-6-v1 --allowedTools "Read,Edit,Write,Glob,Grep,Bash(git status*),Bash(git diff*),Bash(git add *),Bash(git commit *),Bash(git push*),Bash(git log*),Bash(git merge*),Bash(git fetch*),Bash(git checkout*),Bash(git branch*),Bash(uv run prek *),Bash(prek *),Bash(uv run ruff *),Bash(uv run pytest *),Bash(uv run mypy *),Bash(uv run coverage *),Bash(gh pr comment*),Bash(gh pr view*),Bash(gh pr diff*),Bash(gh pr merge*),Bash(gh pr close*)"'
claude_args: '--model us.anthropic.claude-sonnet-4-6 --allowedTools "Read,Edit,Write,Glob,Grep,Bash(git status*),Bash(git diff*),Bash(git add *),Bash(git commit *),Bash(git push*),Bash(git log*),Bash(git merge*),Bash(git fetch*),Bash(git checkout*),Bash(git branch*),Bash(uv run prek *),Bash(prek *),Bash(uv run ruff *),Bash(uv run pytest *),Bash(uv run mypy *),Bash(uv run coverage *),Bash(gh pr comment*),Bash(gh pr view*),Bash(gh pr diff*),Bash(gh pr merge*),Bash(gh pr close*)"'
additional_permissions: |
actions: read

13
.github/workflows/unit-tests.yaml vendored
View file

@ -40,19 +40,6 @@ jobs:
fetch-depth: 0
token: ${{ secrets.GITHUB_TOKEN }}
- name: Set up JDK 11
uses: actions/setup-java@v4
with:
java-version: '11'
distribution: 'temurin'
cache: maven
- name: Build and install codeflash-runtime JAR
run: |
cd codeflash-java-runtime
mvn clean package -q -DskipTests
mvn install -q -DskipTests
- name: Install uv
uses: astral-sh/setup-uv@v6
with:

4
CLAUDE.md
View file

@ -2,7 +2,7 @@
## 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.
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
@ -12,7 +12,7 @@ Discovery → Ranking → Context Extraction → Test Gen + Optimization → Bas
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** (`context/`): Extract code dependencies (read-writable code + read-only imports)
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

1
docs/FRICTIONLESS_SETUP_PLAN.md Normal file
View file

@ -0,0 +1 @@

1
docs/JS_PROMPT_PARITY_RECOMMENDATIONS.md Normal file
View file

@ -0,0 +1 @@

18
docs/codeflash-concepts/how-codeflash-works.mdx
View file

@ -3,25 +3,31 @@ title: "How Codeflash Works"
description: "Understand Codeflash's generate-and-verify approach to code optimization and correctness verification"
icon: "gear"
sidebarTitle: "How It Works"
keywords: ["architecture", "verification", "correctness", "testing", "optimization", "LLM", "benchmarking"]
keywords: ["architecture", "verification", "correctness", "testing", "optimization", "LLM", "benchmarking", "javascript", "typescript", "python"]
---
# How Codeflash Works
Codeflash follows a "generate and verify" approach to optimize code. It uses LLMs to generate optimizations, then it rigorously verifies if those optimizations are indeed
faster and if they have the same behavior. The basic unit of optimization is a function—Codeflash tries to speed up the function, and tries to ensure that it still behaves the same way. This way if you merge the optimized code, it simply runs faster without breaking any functionality.
Codeflash supports **Python**, **JavaScript**, and **TypeScript** projects.
## Analysis of your code
Codeflash scans your codebase to identify all available functions. It locates existing unit tests in your projects and maps which functions they test. When optimizing a function, Codeflash runs these discovered tests to verify nothing has broken.
For Python, code analysis uses `libcst` and `jedi`. For JavaScript/TypeScript, it uses `tree-sitter` for AST parsing.
#### What kind of functions can Codeflash optimize?
Codeflash works best with self-contained functions that have minimal side effects (like communicating with external systems or sending network requests). Codeflash optimizes a group of functions - consisting of an entry point function and any other functions it directly calls.
Codeflash supports optimizing async functions.
Codeflash supports optimizing async functions in all supported languages.
#### Test Discovery
Codeflash currently only runs tests that directly call the target function in their test body. To discover tests that indirectly call the function, you can use the Codeflash Tracer. The Tracer analyzes your test suite and identifies all tests that eventually call a function.
Codeflash discovers tests that directly call the target function in their test body. For Python, it finds pytest and unittest tests. For JavaScript/TypeScript, it finds Jest and Vitest test files.
To discover tests that indirectly call the function, you can use the Codeflash Tracer. The Tracer analyzes your test suite and identifies all tests that eventually call a function.
## Optimization Generation
@ -48,12 +54,12 @@ We recommend manually reviewing the optimized code since there might be importan
Codeflash generates two types of tests:
- LLM Generated tests - Codeflash uses LLMs to create several regression test cases that cover typical function usage, edge cases, and large-scale inputs to verify both correctness and performance.
- Concolic coverage tests - Codeflash uses state-of-the-art concolic testing with an SMT Solver (a theorem prover) to explore execution paths and generate function arguments. This aims to maximize code coverage for the function being optimized. Codeflash runs the resulting test file to verify correctness. Currently, this feature only supports pytest.
- **LLM Generated tests** - Codeflash uses LLMs to create several regression test cases that cover typical function usage, edge cases, and large-scale inputs to verify both correctness and performance. This works for Python, JavaScript, and TypeScript.
- **Concolic coverage tests** - Codeflash uses state-of-the-art concolic testing with an SMT Solver (a theorem prover) to explore execution paths and generate function arguments. This aims to maximize code coverage for the function being optimized. Currently, this feature only supports Python (pytest).
## Code Execution
Codeflash runs tests for the target function using either pytest or unittest frameworks. The tests execute on your machine, ensuring access to the Python environment and any other dependencies associated to let Codeflash run your code properly. Running on your machine also ensures accurate performance measurements since runtime varies by system.
Codeflash runs tests for the target function on your machine. For Python, it uses pytest or unittest. For JavaScript/TypeScript, it uses Jest or Vitest. Running on your machine ensures access to your environment and dependencies, and provides accurate performance measurements since runtime varies by system.
#### Performance benchmarking

77
docs/configuration.mdx
View file

@ -1,83 +1,26 @@
---
title: "Manual Configuration"
description: "Configure Codeflash for your project with pyproject.toml settings and advanced options"
description: "Configure Codeflash for your project"
icon: "gear"
sidebarTitle: "Manual Configuration"
keywords:
[
"configuration",
"pyproject.toml",
"setup",
"settings",
"pytest",
"formatter",
]
---
# Manual Configuration
Codeflash is installed and configured on a per-project basis.
`codeflash init` should guide you through the configuration process, but if you need to manually configure Codeflash or set advanced settings, you can do so by editing the `pyproject.toml` file in the root directory of your project.
`codeflash init` should guide you through the configuration process, but if you need to manually configure Codeflash or set advanced settings, follow the guide for your language:
## Configuration Options
Codeflash config looks like the following
```toml
[tool.codeflash]
module-root = "my_module"
tests-root = "tests"
formatter-cmds = ["black $file"]
# optional configuration
benchmarks-root = "tests/benchmarks" # Required when running with --benchmark
ignore-paths = ["my_module/build/"]
pytest-cmd = "pytest"
disable-imports-sorting = false
disable-telemetry = false
git-remote = "origin"
override-fixtures = false
```
All file paths are relative to the directory of the `pyproject.toml` file.
Required Options:
- `module-root`: The Python module you want Codeflash to optimize going forward. Only code under this directory will be optimized. It should also have an `__init__.py` file to make the module importable.
- `tests-root`: The directory where your tests are located. Codeflash will use this directory to discover existing tests as well as generate new tests.
Optional Configuration:
- `benchmarks-root`: The directory where your benchmarks are located. Codeflash will use this directory to discover existing benchmarks. Note that this option is required when running with `--benchmark`.
- `ignore-paths`: A list of paths within the `module-root` to ignore when optimizing code. Codeflash will not optimize code in these paths. Useful for ignoring build directories or other generated code. You can also leave this empty if not needed.
- `pytest-cmd`: The command to run your tests. Defaults to `pytest`. You can specify extra commandline arguments here for pytest.
- `formatter-cmds`: The command line to run your code formatter or linter. Defaults to `["black $file"]`. In the command line `$file` refers to the current file being optimized. The assumption with using tools here is that they overwrite the same file and returns a zero exit code. You can also specify multiple tools here that run in a chain as a toml array. You can also disable code formatting by setting this to `["disabled"]`.
- `ruff` - A recommended way to run ruff linting and formatting is `["ruff check --exit-zero --fix $file", "ruff format $file"]`. To make `ruff check --fix` return a 0 exit code please add a `--exit-zero` argument.
- `disable-imports-sorting`: By default, codeflash uses isort to organize your imports before creating suggestions. You can disable this by setting this field to `true`. This could be useful if you don't sort your imports or while using linters like ruff that sort imports too.
- `disable-telemetry`: Disable telemetry data collection. Defaults to `false`. Set this to `true` to disable telemetry data collection. Codeflash collects anonymized telemetry data to understand how users are using Codeflash and to improve the product. Telemetry does not collect any code data.
- `git-remote`: The git remote to use for pull requests. Defaults to `"origin"`.
- `override-fixtures`: Override pytest fixtures during optimization. Defaults to `false`.
## Example Configuration
Here's an example project with the following structure:
```text
acme-project/
|- foo_module/
| |- __init__.py
| |- foo.py
| |- main.py
|- tests/
| |- __init__.py
| |- test_script.py
|- pyproject.toml
```
Here's a sample `pyproject.toml` file for the above project:
```toml
[tool.codeflash]
module-root = "foo_module"
tests-root = "tests"
ignore-paths = []
```
<CardGroup cols={2}>
<Card title="Python Configuration" icon="python" href="/configuration/python">
Configure via `pyproject.toml`
</Card>
<Card title="JavaScript / TypeScript Configuration" icon="js" href="/configuration/javascript">
Configure via `package.json`
</Card>
</CardGroup>

220
docs/configuration/javascript.mdx Normal file
View file

@ -0,0 +1,220 @@
---
title: "JavaScript / TypeScript Configuration"
description: "Configure Codeflash for JavaScript and TypeScript projects using package.json"
icon: "js"
sidebarTitle: "JavaScript / TypeScript"
keywords:
[
"configuration",
"package.json",
"javascript",
"typescript",
"jest",
"vitest",
"prettier",
"eslint",
"monorepo",
]
---
# JavaScript / TypeScript Configuration
Codeflash stores its configuration in `package.json` under the `"codeflash"` key.
## Full Reference
```json
{
"name": "my-project",
"codeflash": {
"moduleRoot": "src",
"testsRoot": "tests",
"testRunner": "jest",
"formatterCmds": ["prettier --write $file"],
"ignorePaths": ["src/generated/"],
"disableTelemetry": false,
"gitRemote": "origin"
}
}
```
All file paths are relative to the directory containing `package.json`.
<Info>
Codeflash auto-detects most settings from your project structure. Running `codeflash init` will set up the correct config — manual configuration is usually not needed.
</Info>
## Auto-Detection
When you run `codeflash init`, Codeflash inspects your project and auto-detects:
| Setting | Detection logic |
|---------|----------------|
| `moduleRoot` | Looks for `src/`, `lib/`, or the main source directory |
| `testsRoot` | Looks for `tests/`, `test/`, `__tests__/`, or files matching `*.test.js` / `*.spec.js` |
| `testRunner` | Checks `devDependencies` for `jest` or `vitest` |
| `formatterCmds` | Checks for `prettier`, `eslint`, or `biome` in dependencies and config files |
| Module system | Reads `"type"` field in `package.json` (ESM vs CommonJS) |
| TypeScript | Detects `tsconfig.json` |
You can always override any auto-detected value in the `"codeflash"` section.
## Required Options
- `moduleRoot`: The source directory to optimize. Only code under this directory will be optimized.
- `testsRoot`: The directory where your tests are located. Codeflash discovers existing tests and generates new ones here.
## Optional Options
- `testRunner`: Test framework to use. Auto-detected from your dependencies. Supported values: `"jest"`, `"vitest"`.
- `formatterCmds`: Formatter commands. `$file` refers to the file being optimized. Disable with `["disabled"]`.
- **Prettier**: `["prettier --write $file"]`
- **ESLint + Prettier**: `["eslint --fix $file", "prettier --write $file"]`
- **Biome**: `["biome check --write $file"]`
- `ignorePaths`: Paths within `moduleRoot` to skip during optimization.
- `disableTelemetry`: Disable anonymized telemetry. Defaults to `false`.
- `gitRemote`: Git remote for pull requests. Defaults to `"origin"`.
## Module Systems
Codeflash handles both ES Modules and CommonJS automatically. It detects the module system from your `package.json`:
```json
{
"type": "module"
}
```
- `"type": "module"` — Files are treated as ESM (`import`/`export`)
- `"type": "commonjs"` or omitted — Files are treated as CommonJS (`require`/`module.exports`)
No additional configuration is needed. Codeflash respects `.mjs`/`.cjs` extensions as well.
## TypeScript
TypeScript projects work out of the box. Codeflash detects TypeScript from the presence of `tsconfig.json` and handles `.ts`/`.tsx` files automatically.
No separate configuration is needed for TypeScript vs JavaScript.
## Test Framework Support
| Framework | Auto-detected from | Notes |
|-----------|-------------------|-------|
| **Jest** | `jest` in dependencies | Default for most projects |
| **Vitest** | `vitest` in dependencies | ESM-native support |
<Info>
**Functions must be exported** to be optimizable. Codeflash uses tree-sitter AST analysis to discover functions and check export status. Supported export patterns:
- `export function foo() {}`
- `export const foo = () => {}`
- `export default function foo() {}`
- `const foo = () => {}; export { foo };`
- `module.exports = { foo }`
- `const utils = { foo() {} }; module.exports = utils;`
</Info>
## Monorepo Configuration
For monorepo projects (Yarn workspaces, pnpm workspaces, Lerna, Nx, Turborepo), configure each package individually:
```text
my-monorepo/
|- packages/
| |- core/
| | |- src/
| | |- tests/
| | |- package.json <-- "codeflash" config here
| |- utils/
| | |- src/
| | |- __tests__/
| | |- package.json <-- "codeflash" config here
|- package.json <-- workspace root (no codeflash config)
```
Run `codeflash init` from within each package:
```bash
cd packages/core
npx codeflash init
```
<Warning>
**Always run codeflash from the package directory**, not the monorepo root. Codeflash needs to find the `package.json` with the `"codeflash"` config in the current working directory.
</Warning>
### Hoisted dependencies
If your monorepo hoists `node_modules` to the root (Yarn Berry with `nodeLinker: node-modules`, pnpm with `shamefully-hoist`), Codeflash resolves modules using Node.js standard resolution. This works automatically.
For **pnpm strict mode** (non-hoisted), ensure `codeflash` is a direct dependency of the package:
```bash
pnpm add --filter @my-org/core --save-dev codeflash
```
## Example
### Standard project
```text
my-app/
|- src/
| |- utils.js
| |- index.js
|- tests/
| |- utils.test.js
|- package.json
```
```json
{
"name": "my-app",
"codeflash": {
"moduleRoot": "src",
"testsRoot": "tests"
}
}
```
### Project with co-located tests
```text
my-app/
|- src/
| |- utils.js
| |- utils.test.js
| |- index.js
|- package.json
```
```json
{
"name": "my-app",
"codeflash": {
"moduleRoot": "src",
"testsRoot": "src"
}
}
```
### CommonJS library with no separate test directory
```text
my-lib/
|- lib/
| |- helpers.js
|- test/
| |- helpers.spec.js
|- package.json
```
```json
{
"name": "my-lib",
"codeflash": {
"moduleRoot": "lib",
"testsRoot": "test"
}
}
```

80
docs/configuration/python.mdx Normal file
View file

@ -0,0 +1,80 @@
---
title: "Python Configuration"
description: "Configure Codeflash for Python projects using pyproject.toml"
icon: "python"
sidebarTitle: "Python"
keywords:
[
"configuration",
"pyproject.toml",
"python",
"pytest",
"formatter",
"ruff",
"black",
]
---
# Python Configuration
Codeflash stores its configuration in `pyproject.toml` under the `[tool.codeflash]` section.
## Full Reference
```toml
[tool.codeflash]
# Required
module-root = "my_module"
tests-root = "tests"
# Optional
formatter-cmds = ["black $file"]
benchmarks-root = "tests/benchmarks"
ignore-paths = ["my_module/build/"]
pytest-cmd = "pytest"
disable-imports-sorting = false
disable-telemetry = false
git-remote = "origin"
override-fixtures = false
```
All file paths are relative to the directory of the `pyproject.toml` file.
## Required Options
- `module-root`: The Python module to optimize. Only code under this directory will be optimized. It should have an `__init__.py` file to make the module importable.
- `tests-root`: The directory where your tests are located. Codeflash discovers existing tests and generates new ones here.
## Optional Options
- `benchmarks-root`: Directory for benchmarks. Required when running with `--benchmark`.
- `ignore-paths`: Paths within `module-root` to skip. Useful for build directories or generated code.
- `pytest-cmd`: Command to run your tests. Defaults to `pytest`. You can add extra arguments here.
- `formatter-cmds`: Formatter/linter commands. `$file` refers to the file being optimized. Disable with `["disabled"]`.
- **ruff** (recommended): `["ruff check --exit-zero --fix $file", "ruff format $file"]`
- **black**: `["black $file"]`
- `disable-imports-sorting`: Disable isort import sorting. Defaults to `false`.
- `disable-telemetry`: Disable anonymized telemetry. Defaults to `false`.
- `git-remote`: Git remote for pull requests. Defaults to `"origin"`.
- `override-fixtures`: Override pytest fixtures during optimization. Defaults to `false`.
## Example
```text
acme-project/
|- foo_module/
| |- __init__.py
| |- foo.py
| |- main.py
|- tests/
| |- __init__.py
| |- test_script.py
|- pyproject.toml
```
```toml
[tool.codeflash]
module-root = "foo_module"
tests-root = "tests"
ignore-paths = []
```

487
docs/getting-started/javascript-installation.mdx
View file

@ -1,38 +1,51 @@
---
title: "JavaScript Installation"
title: "JavaScript / TypeScript Installation"
description: "Install and configure Codeflash for your JavaScript/TypeScript project"
icon: "node-js"
keywords:
[
"installation",
"javascript",
"typescript",
"npm",
"yarn",
"pnpm",
"bun",
"jest",
"vitest",
"monorepo",
]
---
Codeflash now supports JavaScript and TypeScript projects with optimized test data serialization using V8 native serialization.
Codeflash supports JavaScript and TypeScript projects. It uses V8 native serialization for test data capture and works with Jest and Vitest test frameworks.
### Prerequisites
Before installing Codeflash for JavaScript, ensure you have:
Before installing Codeflash, ensure you have:
1. **Node.js 16 or above** installed
1. **Node.js 18 or above** installed
2. **A JavaScript/TypeScript project** with a package manager (npm, yarn, pnpm, or bun)
3. **Project dependencies installed**
Good to have (optional):
1. **Unit Tests** that Codeflash uses to ensure correctness of the optimizations
1. **Unit tests** (Jest or Vitest) — Codeflash uses them to verify correctness of optimizations
<Warning>
**Node.js Runtime Required**
**Node.js 18+ Required**
Codeflash JavaScript support uses V8 serialization API, which is available natively in Node.js. Make sure you're running on Node.js 16+ for optimal compatibility.
Codeflash requires Node.js 18 or above. Check your version:
```bash
node --version # Should show v16.0.0 or higher
node --version # Should show v18.0.0 or higher
```
</Warning>
<Steps>
<Step title="Install Codeflash CLI">
<Step title="Install the Codeflash npm package">
Install Codeflash globally or as a development dependency in your project:
Install Codeflash as a development dependency in your project:
<CodeGroup>
```bash npm
@ -50,321 +63,285 @@ pnpm add --save-dev codeflash
```bash bun
bun add --dev codeflash
```
```bash global
npm install -g codeflash
```
</CodeGroup>
<Tip>
**Development Dependency Recommended**
Codeflash is intended for development and CI workflows. Installing as a dev dependency keeps your production bundle clean.
**Dev dependency recommended** — Codeflash is for development and CI workflows. Installing as a dev dependency keeps your production bundle clean.
</Tip>
<Info>
**Codeflash also requires a Python installation** (3.9+) to run the CLI optimizer. Install the Python CLI globally:
```bash
pip install codeflash
# or
uv tool install codeflash
```
The Python CLI orchestrates the optimization pipeline, while the npm package provides the JavaScript runtime (test runners, serialization, reporters).
</Info>
</Step>
<Step title="Generate a Codeflash API Key">
Codeflash uses cloud-hosted AI models. You need an API key:
1. Visit the [Codeflash Web App](https://app.codeflash.ai/)
2. Sign up with your GitHub account (free tier available)
3. Navigate to the [API Key](https://app.codeflash.ai/app/apikeys) page to generate your key
Set it as an environment variable:
```bash
export CODEFLASH_API_KEY="your-api-key-here"
```
Or add it to your shell profile (`~/.bashrc`, `~/.zshrc`) for persistence.
</Step>
<Step title="Run Automatic Configuration">
Navigate to your project's root directory (where your `package.json` file is) and run:
Navigate to your project root (where `package.json` is) and run:
```bash
<CodeGroup>
```bash npm / yarn / pnpm
npx codeflash init
```
```bash bun
bunx codeflash init
```
```bash Global install
codeflash init
```
</CodeGroup>
When running `codeflash init`, you will see the following prompts:
### What `codeflash init` does
```text
1. Enter your Codeflash API key (or login with Codeflash)
2. Which JavaScript/TypeScript module do you want me to optimize? (e.g. src/)
3. Where are your tests located? (e.g. tests/, __tests__/, *.test.js)
4. Which test framework do you use? (jest/vitest/mocha/ava/other)
5. Which code formatter do you use? (prettier/eslint/biome/disabled)
6. Which git remote should Codeflash use for Pull Requests? (if multiple remotes exist)
7. Help us improve Codeflash by sharing anonymous usage data?
8. Install the GitHub app
9. Install GitHub actions for Continuous optimization?
Codeflash **auto-detects** most settings from your project:
| Setting | How it's detected |
|---------|------------------|
| **Module root** | Looks for `src/`, `lib/`, or the directory containing your source files |
| **Tests root** | Looks for `tests/`, `test/`, `__tests__/`, or files matching `*.test.js` / `*.spec.js` |
| **Test framework** | Checks `devDependencies` for `jest` or `vitest` |
| **Formatter** | Checks for `prettier`, `eslint`, or `biome` in dependencies and config files |
| **Module system** | Reads `"type"` field in `package.json` (ESM vs CommonJS) |
| **TypeScript** | Detects `tsconfig.json` presence |
You'll be prompted to confirm or override the detected values. The configuration is saved in your `package.json` under the `"codeflash"` key:
```json
{
"name": "my-project",
"codeflash": {
"moduleRoot": "src",
"testsRoot": "tests"
}
}
```
After you have answered these questions, the Codeflash configuration will be saved in a `codeflash.config.js` file.
<Info>
**Test Data Serialization Strategy**
Codeflash uses **V8 serialization** for JavaScript test data capture. This provides:
- ⚡ **Best performance**: 2-3x faster than alternatives
- 🎯 **Perfect type preservation**: Maintains Date, Map, Set, TypedArrays, and more
- 📦 **Compact binary storage**: Smallest file sizes
- 🔄 **Framework agnostic**: Works with React, Vue, Angular, Svelte, and vanilla JS
**No separate config file needed.** Codeflash stores all configuration inside your existing `package.json`, not in a separate config file.
</Info>
</Step>
<Step title="Generate a Codeflash API Key">
Codeflash uses cloud-hosted AI models and integrations with GitHub. If you haven't created one already, you'll need to create an API key to authorize your access.
<Step title="Install the Codeflash GitHub App (optional)">
1. Visit the [Codeflash Web App](https://app.codeflash.ai/)
2. Sign up with your GitHub account (free)
3. Navigate to the [API Key](https://app.codeflash.ai/app/apikeys) page to generate your API key
To receive optimization PRs automatically, install the Codeflash GitHub App:
<Note>
**Free Tier Available**
[Install Codeflash GitHub App](https://github.com/apps/codeflash-ai/installations/select_target)
Codeflash offers a **free tier** with a limited number of optimizations. Perfect for trying it out on small projects!
</Note>
</Step>
<Step title="Install the Codeflash GitHub App">
Finally, if you have not done so already, Codeflash will ask you to install the GitHub App in your repository.
The Codeflash GitHub App allows the codeflash-ai bot to open PRs, review code, and provide optimization suggestions.
Please [install the Codeflash GitHub
app](https://github.com/apps/codeflash-ai/installations/select_target) by choosing the repository you want to install
Codeflash on.
This enables the codeflash-ai bot to open PRs with optimization suggestions. If you skip this step, you can still optimize locally using `--no-pr`.
</Step>
</Steps>
## Framework Support
## Monorepo Setup
Codeflash JavaScript support works seamlessly with all major frameworks and testing libraries:
For monorepos (Yarn workspaces, pnpm workspaces, Lerna, Nx, Turborepo), run `codeflash init` from within each package you want to optimize:
<CardGroup cols={2}>
<Card title="Frontend Frameworks" icon="react">
- React
- Vue.js
- Angular
- Svelte
- Solid.js
</Card>
```bash
# Navigate to the specific package
cd packages/my-library
<Card title="Test Frameworks" icon="flask">
- Jest
- Vitest
- Mocha
- AVA
- Playwright
- Cypress
</Card>
# Run init from the package directory
npx codeflash init
```
<Card title="Backend" icon="server">
- Express
- NestJS
- Fastify
- Koa
- Hono
</Card>
Each package gets its own `"codeflash"` section in its `package.json`. The `moduleRoot` and `testsRoot` paths are relative to that package's `package.json`.
<Card title="Runtimes" icon="gears">
- Node.js ✅ (Recommended)
- Bun (Coming soon)
- Deno (Coming soon)
</Card>
</CardGroup>
### Example: Yarn workspaces monorepo
## Understanding V8 Serialization
```text
my-monorepo/
|- packages/
| |- core/
| | |- src/
| | |- tests/
| | |- package.json <-- codeflash config here
| |- utils/
| | |- src/
| | |- __tests__/
| | |- package.json <-- codeflash config here
|- package.json <-- root workspace (no codeflash config needed)
```
Codeflash uses Node.js's native V8 serialization API to capture and compare test data. Here's what makes it powerful:
### Type Preservation
Unlike JSON serialization, V8 serialization preserves JavaScript-specific types:
```javascript
// These types are preserved perfectly:
const testData = {
date: new Date(), // ✅ Date objects
map: new Map([['key', 'value']]), // ✅ Map instances
set: new Set([1, 2, 3]), // ✅ Set instances
buffer: Buffer.from('hello'), // ✅ Buffers
typed: new Uint8Array([1, 2, 3]), // ✅ TypedArrays
bigint: 9007199254740991n, // ✅ BigInt
regex: /pattern/gi, // ✅ RegExp
undef: undefined, // ✅ undefined (not null!)
circular: {} // ✅ Circular references
};
testData.circular.self = testData.circular;
```json
// packages/core/package.json
{
"name": "@my-org/core",
"codeflash": {
"moduleRoot": "src",
"testsRoot": "tests"
}
}
```
<Warning>
**Why Not JSON?**
JSON serialization would cause bugs to slip through:
- `Date` becomes string → date arithmetic fails silently
- `Map` becomes `{}` → `.get()` calls return undefined
- `undefined` becomes `null` → type checks break
- TypedArrays become plain objects → binary operations fail
V8 serialization catches these issues during optimization verification.
**Run codeflash from the package directory**, not the monorepo root. Codeflash needs to find the `package.json` with the `"codeflash"` config in the current working directory.
</Warning>
## Try It Out!
<Info>
**Hoisted dependencies work fine.** If your monorepo hoists `node_modules` to the root (common in Yarn Berry, pnpm with `shamefully-hoist`), Codeflash resolves modules using Node.js standard resolution and will find them correctly.
</Info>
<Tabs>
<Tab title="Quick Start">
Once configured, you can start optimizing your JavaScript/TypeScript code immediately:
## Test Framework Support
```bash
# Optimize a specific function
codeflash --file path/to/your/file.js --function functionName
| Framework | Status | Auto-detected from |
|-----------|--------|-------------------|
| **Jest** | Supported | `jest` in dependencies |
| **Vitest** | Supported | `vitest` in dependencies |
| **Mocha** | Coming soon | — |
# Or optimize all functions in your codebase
<Info>
**Functions must be exported** to be optimizable. Codeflash can only discover and optimize functions that are exported from their module (via `export`, `export default`, or `module.exports`).
</Info>
## Try It Out
Once configured, optimize your code:
<CodeGroup>
```bash Optimize a function
codeflash --file src/utils.js --function processData
```
```bash Optimize locally (no PR)
codeflash --file src/utils.ts --function processData --no-pr
```
```bash Optimize entire codebase
codeflash --all
```
</Tab>
<Tab title="TypeScript Support">
Codeflash fully supports TypeScript projects:
```bash
# Optimize TypeScript files directly
codeflash --file src/utils.ts --function processData
# Works with TSX for React components
codeflash --file src/components/DataTable.tsx --function DataTable
```bash Trace and optimize
codeflash optimize --jest
```
<Info>
Codeflash preserves TypeScript types during optimization. Your type annotations and interfaces remain intact.
</Info>
</Tab>
<Tab title="Test Framework Examples">
<Accordion title="Jest Example">
```javascript
// sum.test.js
test('adds 1 + 2 to equal 3', () => {
expect(sum(1, 2)).toBe(3);
});
// Optimize the sum function
codeflash --file sum.js --function sum
```
</Accordion>
<Accordion title="Vitest Example">
```javascript
// calculator.test.js
import { describe, it, expect } from 'vitest';
describe('calculator', () => {
it('should multiply correctly', () => {
expect(multiply(2, 3)).toBe(6);
});
});
// Optimize the multiply function
codeflash --file calculator.js --function multiply
```
</Accordion>
</Tab>
</Tabs>
</CodeGroup>
## Troubleshooting
<AccordionGroup>
<Accordion title="📦 Module not found errors">
Make sure:
- ✅ All project dependencies are installed
- ✅ Your `node_modules` directory exists
<Accordion title="Function not found or not exported">
Codeflash only optimizes **exported** functions. Make sure your function is exported:
```bash
# Reinstall dependencies
npm install
# or
yarn install
```
</Accordion>
<Accordion title="🔧 V8 serialization errors">
If you encounter serialization errors:
**Functions and classes** cannot be serialized:
```javascript
// ❌ Won't work - contains function
const data = { callback: () => {} };
// ES Modules
export function processData(data) { ... }
// or
const processData = (data) => { ... };
export { processData };
// ✅ Works - pure data
const data = { value: 42, items: [1, 2, 3] };
// CommonJS
function processData(data) { ... }
module.exports = { processData };
```
**Symbols** are not serializable:
```javascript
// ❌ Won't work
const data = { [Symbol('key')]: 'value' };
// ✅ Use string keys
const data = { key: 'value' };
```
If codeflash reports the function exists but is not exported, add an export statement.
</Accordion>
<Accordion title="🧪 No optimizations found">
Not all functions can be optimized - some code is already optimal. This is expected.
<Accordion title="codeflash npm package not found / module errors">
Ensure the codeflash npm package is installed in your project:
Use the `--verbose` flag for detailed output:
```bash
codeflash optimize --verbose
<CodeGroup>
```bash npm
npm install --save-dev codeflash
```
```bash yarn
yarn add --dev codeflash
```
```bash pnpm
pnpm add --save-dev codeflash
```
</CodeGroup>
This will show:
- 🔍 Which functions are being analyzed
- 🚫 Why certain functions were skipped
- ⚠️ Detailed error messages
- 📊 Performance analysis results
For **monorepos**, make sure it's installed in the package you're optimizing, or at the workspace root if dependencies are hoisted.
</Accordion>
<Accordion title="🔍 Test discovery issues">
Verify:
- 📁 Your test directory path is correct in `codeflash.config.js`
- 🔍 Tests are discoverable by your test framework
- 📝 Test files follow naming conventions (`*.test.js`, `*.spec.js`)
<Accordion title="Test framework not detected">
Codeflash auto-detects the test framework from your `devDependencies`. If detection fails:
1. Verify your test framework is in `devDependencies`:
```bash
npm ls jest # or: npm ls vitest
```
2. Or set it manually in `package.json`:
```json
{
"codeflash": {
"testRunner": "jest"
}
}
```
</Accordion>
<Accordion title="Jest tests timing out">
If Jest tests take too long, Codeflash has a default timeout. For large test suites:
- Use `--file` and `--function` to target specific functions instead of `--all`
- Ensure your tests don't have expensive setup/teardown that runs for every test file
- Check if `jest.config.js` has a `setupFiles` that takes a long time
</Accordion>
<Accordion title="TypeScript compilation errors">
Codeflash uses your project's TypeScript configuration. If you see TS errors:
1. Verify `npx tsc --noEmit` passes on its own
2. Check that `tsconfig.json` is in the project root or the module root
3. For projects using `moduleResolution: "bundler"`, Codeflash creates a temporary tsconfig overlay — this is expected behavior
</Accordion>
<Accordion title="Monorepo: wrong package.json detected">
Run codeflash from the correct package directory:
```bash
# Test if your test framework can discover tests
npm test -- --listTests # Jest
# or
npx vitest list # Vitest
cd packages/my-library
codeflash --file src/utils.ts --function myFunc
```
If your monorepo tool hoists dependencies, you may need to ensure the `codeflash` npm package is accessible from the package directory. For pnpm, add `.npmrc` with `shamefully-hoist=true` or use `pnpm add --filter my-library --save-dev codeflash`.
</Accordion>
<Accordion title="No optimizations found">
Not all functions can be optimized — some code is already efficient. This is normal.
For better results:
- Target functions with loops, string manipulation, or data transformations
- Ensure the function has existing tests for correctness verification
- Use `codeflash optimize --jest` to trace real execution and capture realistic inputs
</Accordion>
</AccordionGroup>
## Configuration
## Configuration Reference
Your `codeflash.config.js` file controls how Codeflash analyzes your JavaScript project:
```javascript
module.exports = {
// Source code to optimize
module: 'src',
// Test location
tests: 'tests',
// Test framework
testFramework: 'jest',
// Serialization strategy (automatically set to 'v8')
serialization: 'v8',
// Formatter
formatter: 'prettier',
// Additional options
exclude: ['node_modules', 'dist', 'build'],
verbose: false
};
```
See [JavaScript / TypeScript Configuration](/configuration/javascript) for the full list of options.
### Next Steps
- Learn about [Codeflash Concepts](/codeflash-concepts/how-codeflash-works)
- Explore [Optimization workflows](/optimizing-with-codeflash/one-function)
- Learn [how Codeflash works](/codeflash-concepts/how-codeflash-works)
- [Optimize a single function](/optimizing-with-codeflash/one-function)
- Set up [Pull Request Optimization](/optimizing-with-codeflash/codeflash-github-actions)
- Read [configuration options](/configuration) for advanced setups
- Explore [Trace and Optimize](/optimizing-with-codeflash/trace-and-optimize) for workflow optimization

28
docs/index.mdx
View file

@ -1,27 +1,38 @@
---
title: "Codeflash is an AI performance optimizer for Python code"
title: "Codeflash is an AI performance optimizer for your code"
icon: "rocket"
sidebarTitle: "Overview"
keywords: ["python", "performance", "optimization", "AI", "code analysis", "benchmarking"]
keywords: ["python", "javascript", "typescript", "performance", "optimization", "AI", "code analysis", "benchmarking"]
---
Codeflash speeds up any Python code by figuring out the best way to rewrite it while verifying that the behavior of the code is unchanged, and verifying real speed
gains through performance benchmarking.
Codeflash speeds up your code by figuring out the best way to rewrite it while verifying that the behavior is unchanged, and verifying real speed
gains through performance benchmarking. It supports **Python**, **JavaScript**, and **TypeScript**.
The optimizations Codeflash finds are generally better algorithms, opportunities to remove wasteful compute, better logic, utilizing caching and utilization of more efficient library methods. Codeflash
does not modify the system architecture of your code, but it tries to find the most efficient implementation of your current architecture.
### Get Started
<CardGroup cols={2}>
<Card title="Python Setup" icon="python" href="/getting-started/local-installation">
Install via pip, uv, or poetry
</Card>
<Card title="JavaScript / TypeScript Setup" icon="js" href="/getting-started/javascript-installation">
Install via npm, yarn, pnpm, or bun
</Card>
</CardGroup>
### How to use Codeflash
<CardGroup cols={1}>
<Card title="Optimize a Single Function" icon="bullseye" href="/optimizing-with-codeflash/one-function">
Target and optimize individual Python functions for maximum performance gains.
Target and optimize individual functions for maximum performance gains.
```bash
codeflash --file path.py --function my_function
codeflash --file path/to/file --function my_function
```
</Card>
<Card title="Optimize Pull Requests" icon="code-pull-request" href="/optimizing-with-codeflash/codeflash-github-actions">
<Card title="Optimize Pull Requests" icon="code-pull-request" href="/optimizing-with-codeflash/codeflash-github-actions">
Automatically find optimizations for Pull Requests with GitHub Actions integration.
```bash
codeflash init-actions
@ -29,7 +40,7 @@ does not modify the system architecture of your code, but it tries to find the m
</Card>
<Card title="Optimize Workflows with Tracing" icon="route" href="/optimizing-with-codeflash/trace-and-optimize">
End-to-end optimization of entire Python workflows with execution tracing.
End-to-end optimization of entire workflows with execution tracing.
```bash
codeflash optimize myscript.py
```
@ -42,7 +53,6 @@ does not modify the system architecture of your code, but it tries to find the m
```
</Card>
</CardGroup>
### How does Codeflash verify correctness?

12
docs/optimizing-with-codeflash/benchmarking.mdx
View file

@ -1,6 +1,6 @@
---
title: "Optimize Performance Benchmarks with every Pull Request"
description: "Configure and use pytest-benchmark integration for performance-critical code optimization"
description: "Configure and use benchmark integration for performance-critical code optimization"
icon: "chart-line"
sidebarTitle: Setup Benchmarks to Optimize
keywords:
@ -26,6 +26,10 @@ It will then try to optimize the new code for the benchmark and calculate the im
## Using Codeflash in Benchmark Mode
<Note>
Benchmark mode currently supports Python projects using pytest-benchmark. JavaScript/TypeScript benchmark support is coming soon.
</Note>
1. **Create a benchmarks root:**
Create a directory for benchmarks if it does not already exist.
@ -44,7 +48,7 @@ It will then try to optimize the new code for the benchmark and calculate the im
2. **Define your benchmarks:**
Currently, Codeflash only supports benchmarks written as pytest-benchmarks. Check out the [pytest-benchmark](https://pytest-benchmark.readthedocs.io/en/stable/index.html) documentation for more information on syntax.
Codeflash supports benchmarks written as pytest-benchmarks. Check out the [pytest-benchmark](https://pytest-benchmark.readthedocs.io/en/stable/index.html) documentation for more information on syntax.
For example:
@ -58,7 +62,7 @@ It will then try to optimize the new code for the benchmark and calculate the im
Note that these benchmarks should be defined in such a way that they don't take a long time to run.
The pytest-benchmark format is simply used as an interface. The plugin is actually not used - Codeflash will run these benchmarks with its own pytest plugin
The pytest-benchmark format is simply used as an interface. The plugin is actually not used - Codeflash will run these benchmarks with its own pytest plugin.
3. **Run and Test Codeflash:**
@ -74,7 +78,7 @@ It will then try to optimize the new code for the benchmark and calculate the im
codeflash --file test_file.py --benchmark --benchmarks-root path/to/benchmarks
```
4. **Run Codeflash :**
4. **Run Codeflash with GitHub Actions:**
Benchmark mode is best used together with Codeflash as a GitHub Action. This way,
Codeflash will trace through your benchmark and optimize the functions modified in your Pull Request to speed up the benchmark.

26
docs/optimizing-with-codeflash/codeflash-all.mdx
View file

@ -3,13 +3,13 @@ title: "Optimize Your Entire Codebase"
description: "Automatically optimize all codepaths in your project with Codeflash's comprehensive analysis"
icon: "database"
sidebarTitle: "Optimize Entire Codebase"
keywords: ["codebase optimization", "all functions", "batch optimization", "github app", "checkpoint", "recovery"]
keywords: ["codebase optimization", "all functions", "batch optimization", "github app", "checkpoint", "recovery", "javascript", "typescript", "python"]
---
# Optimize your entire codebase
Codeflash can optimize your entire codebase by analyzing all the functions in your project and generating optimized versions of them.
It iterates through all the functions in your codebase and optimizes them one by one.
It iterates through all the functions in your codebase and optimizes them one by one. This works for Python, JavaScript, and TypeScript projects.
To optimize your entire codebase, run the following command in your project directory:
@ -30,15 +30,27 @@ codeflash --all path/to/dir
```
<Tip>
If your project has a good number of unit tests, we can trace those to achieve higher quality results.
The following approach is recommended instead:
If your project has a good number of unit tests, tracing them achieves higher quality results.
<Tabs>
<Tab title="Python">
```bash
codeflash optimize --trace-only -m pytest tests/ ; codeflash --all
```
This will run your test suite, trace all the code covered by your tests, ensuring higher correctness guarantees
and better performance benchmarking, and help create optimizations for code where the LLMs struggle to generate and run tests.
</Tab>
<Tab title="JavaScript / TypeScript">
```bash
codeflash optimize --trace-only --jest ; codeflash --all
# or for Vitest projects
codeflash optimize --trace-only --vitest ; codeflash --all
```
</Tab>
</Tabs>
Even though `codeflash --all` discovers any existing unit tests. It currently can only discover any test that directly calls the
This runs your test suite, traces all the code covered by your tests, ensuring higher correctness guarantees
and better performance benchmarking, and helps create optimizations for code where the LLMs struggle to generate and run tests.
`codeflash --all` discovers any existing unit tests, but it currently can only discover tests that directly call the
function under optimization. Tracing all the tests helps ensure correctness for code that may be indirectly called by your tests.
</Tip>

57
docs/optimizing-with-codeflash/codeflash-github-actions.mdx
View file

@ -26,9 +26,9 @@ We highly recommend setting this up, since once you set it up all your new code
✅ A Codeflash API key from the [Codeflash Web App](https://app.codeflash.ai/)
✅ Completed [local installation](/getting-started/local-installation) with `codeflash init`
✅ Completed local installation with `codeflash init` ([Python](/getting-started/local-installation) or [JavaScript/TypeScript](/getting-started/javascript-installation))
✅ A Python project with a configured `pyproject.toml` file
✅ A configured project (`pyproject.toml` for Python, `package.json` for JavaScript/TypeScript)
</Warning>
## Setup Options
@ -113,7 +113,7 @@ jobs:
</Step>
<Step title="Choose Your Package Manager">
Customize the dependency installation based on your Python package manager:
Customize the dependency installation based on your package manager:
The workflow will need to be set up in such a way the Codeflash can create and
run tests for functionality and speed, so the stock YAML may need to be altered to
@ -121,7 +121,7 @@ suit the specific codebase. Typically the setup steps for a unit test workflow c
be copied.
<CodeGroup>
```yaml Poetry
```yaml Poetry (Python)
- name: Install Project Dependencies
run: |
python -m pip install --upgrade pip
@ -129,11 +129,11 @@ be copied.
poetry install --with dev
- name: Run Codeflash to optimize code
run: |
poetry env use python
poetry env use python
poetry run codeflash
```
```yaml uv
```yaml uv (Python)
- uses: astral-sh/setup-uv@v6
with:
enable-cache: true
@ -142,7 +142,7 @@ be copied.
run: uv run codeflash
```
```yaml pip
```yaml pip (Python)
- name: Install Project Dependencies
run: |
python -m pip install --upgrade pip
@ -151,7 +151,50 @@ be copied.
- name: Run Codeflash to optimize code
run: codeflash
```
```yaml npm (JavaScript/TypeScript)
- uses: actions/setup-node@v4
with:
node-version: '18'
- name: Install Project Dependencies
run: npm ci
- name: Run Codeflash to optimize code
run: npx codeflash
```
```yaml yarn (JavaScript/TypeScript)
- uses: actions/setup-node@v4
with:
node-version: '18'
- name: Install Project Dependencies
run: yarn install --immutable
- name: Run Codeflash to optimize code
run: yarn codeflash
```
```yaml pnpm (JavaScript/TypeScript)
- uses: pnpm/action-setup@v4
with:
version: 9
- uses: actions/setup-node@v4
with:
node-version: '18'
cache: 'pnpm'
- name: Install Project Dependencies
run: pnpm install --frozen-lockfile
- name: Run Codeflash to optimize code
run: pnpm codeflash
```
</CodeGroup>
<Info>
**Monorepo?** If your codeflash config is in a subdirectory, add `working-directory` to the steps:
```yaml
- name: Run Codeflash to optimize code
run: npx codeflash
working-directory: packages/my-library
```
</Info>
</Step>
<Step title="Add Repository Secret">

43
docs/optimizing-with-codeflash/one-function.mdx
View file

@ -1,6 +1,6 @@
---
title: "Optimize a Single Function"
description: "Target and optimize individual Python functions for maximum performance gains"
description: "Target and optimize individual functions for maximum performance gains"
icon: "bullseye"
sidebarTitle: "Optimize Single Function"
keywords:
@ -10,6 +10,9 @@ keywords:
"class methods",
"performance",
"targeted optimization",
"javascript",
"typescript",
"python",
]
---
@ -24,23 +27,55 @@ your mileage may vary.
## How to optimize a function
To optimize a function, you can run the following command in your project:
To optimize a function, run the following command in your project:
<Tabs>
<Tab title="Python">
```bash
codeflash --file path/to/your/file.py --function function_name
```
</Tab>
<Tab title="JavaScript">
```bash
codeflash --file path/to/your/file.js --function functionName
```
</Tab>
<Tab title="TypeScript">
```bash
codeflash --file path/to/your/file.ts --function functionName
```
</Tab>
</Tabs>
If you have installed the GitHub App to your repository, the above command will open a pull request with the optimized function.
If you want to optimize a function locally, you can add a `--no-pr` argument as follows:
If you want to optimize a function locally, add a `--no-pr` argument:
<Tabs>
<Tab title="Python">
```bash
codeflash --file path/to/your/file.py --function function_name --no-pr
```
</Tab>
<Tab title="JavaScript / TypeScript">
```bash
codeflash --file path/to/your/file.ts --function functionName --no-pr
```
</Tab>
</Tabs>
### Optimizing class methods
To optimize a method `method_name` in a class `ClassName`, you can run the following command:
To optimize a method `methodName` in a class `ClassName`:
<Tabs>
<Tab title="Python">
```bash
codeflash --file path/to/your/file.py --function ClassName.method_name
```
</Tab>
<Tab title="JavaScript / TypeScript">
```bash
codeflash --file path/to/your/file.ts --function ClassName.methodName
```
</Tab>
</Tabs>

88
docs/optimizing-with-codeflash/trace-and-optimize.mdx
View file

@ -1,6 +1,6 @@
---
title: "Trace & Optimize E2E Workflows"
description: "End-to-end optimization of entire Python workflows with execution tracing"
description: "End-to-end optimization of entire workflows with execution tracing"
icon: "route"
sidebarTitle: "Optimize E2E Workflows"
keywords:
@ -11,28 +11,50 @@ keywords:
"end-to-end",
"script optimization",
"context manager",
"javascript",
"typescript",
"jest",
"vitest",
]
---
Codeflash can optimize an entire Python script end-to-end by tracing the script's execution and generating Replay Tests.
Tracing follows the execution of a script, profiles it and captures inputs to all functions it called, allowing them to be replayed during optimization.
Codeflash uses these Replay Tests to optimize the most important functions called in the script, delivering the best performance for your workflow.
Codeflash can optimize an entire script or test suite end-to-end by tracing its execution and generating Replay Tests.
Tracing follows the execution of your code, profiles it and captures inputs to all functions it called, allowing them to be replayed during optimization.
Codeflash uses these Replay Tests to optimize the most important functions called in the workflow, delivering the best performance.
![Function Optimization](/images/priority-order.png)
To optimize a script, `python myscript.py`, simply replace `python` with `codeflash optimize` and run the following command:
<Tabs>
<Tab title="Python">
To optimize a script, `python myscript.py`, simply replace `python` with `codeflash optimize`:
```bash
codeflash optimize myscript.py
```
You can also optimize code called by pytest tests that you could normally run like `python -m pytest tests/`, this provides for a good workload to optimize. Run this command:
You can also optimize code called by pytest tests:
```bash
codeflash optimize -m pytest tests/
```
</Tab>
<Tab title="JavaScript / TypeScript">
To trace and optimize your Jest or Vitest tests:
The powerful `codeflash optimize` command creates high-quality optimizations, making it ideal when you need to optimize a workflow or script. The initial tracing process can be slow, so try to limit your script's runtime to under 1 minute for best results. If your workflow is longer, consider tracing it into smaller sections by using the Codeflash tracer as a context manager (point 3 below).
```bash
# Jest
codeflash optimize --jest
# Vitest
codeflash optimize --vitest
# Or trace a specific script
codeflash optimize --language javascript script.js
```
</Tab>
</Tabs>
The `codeflash optimize` command creates high-quality optimizations, making it ideal when you need to optimize a workflow or script. The initial tracing process can be slow, so try to limit your script's runtime to under 1 minute for best results.
The generated replay tests and the trace file are for the immediate optimization use, don't add them to git.
@ -61,6 +83,9 @@ This way you can be _sure_ that the optimized function causes no changes of beha
## Using codeflash optimize
<Tabs>
<Tab title="Python">
Codeflash script optimizer can be used in three ways:
1. **As an integrated command**
@ -100,10 +125,10 @@ Codeflash script optimizer can be used in three ways:
- `--timeout`: The maximum time in seconds to trace the entire workflow. Default is indefinite. This is useful while tracing really long workflows.
3. **As a Context Manager -**
3. **As a Context Manager**
To trace only specific sections of your code, You can also use the Codeflash Tracer as a context manager.
You can wrap the code you want to trace in a `with` statement as follows -
To trace only specific sections of your code, you can use the Codeflash Tracer as a context manager.
You can wrap the code you want to trace in a `with` statement as follows:
```python
from codeflash.tracer import Tracer
@ -128,3 +153,46 @@ Codeflash script optimizer can be used in three ways:
- `output`: The file to save the trace to. Default is `codeflash.trace`.
- `config_file_path`: The path to the `pyproject.toml` file which stores the Codeflash config. This is auto-discovered by default.
You can also disable the tracer in the code by setting the `disable=True` option in the `Tracer` constructor.
</Tab>
<Tab title="JavaScript / TypeScript">
The JavaScript tracer uses Babel instrumentation to capture function calls during your test suite execution.
1. **Trace your test suite**
```bash
# Jest projects
codeflash optimize --jest
# Vitest projects
codeflash optimize --vitest
# Trace a specific script
codeflash optimize --language javascript src/main.js
```
2. **Trace specific functions only**
```bash
codeflash optimize --jest --only-functions processData,transformInput
```
3. **Trace and optimize as two separate steps**
```bash
# Step 1: Create trace file
codeflash optimize --trace-only --jest --output trace_file.sqlite
# Step 2: Optimize with replay tests
codeflash --replay-test /path/to/test_replay_test_0.test.js
```
More Options:
- `--timeout`: Maximum tracing time in seconds.
- `--max-function-count`: Maximum traces per function (default: 256).
- `--only-functions`: Comma-separated list of function names to trace.
</Tab>
</Tabs>