# Getting Started Source: https://docs.codeflash.ai/claude-code-plugin/getting-started Install the Codeflash Claude Code plugin and run your first optimization This guide walks you through installing the Codeflash Claude Code plugin and running your first optimization. ## Prerequisites * **Claude Code** v2.1.38 or later * **Python projects**: [codeflash](https://pypi.org/project/codeflash/) installed in a virtual environment * **JS/TS projects**: [codeflash](https://www.npmjs.com/package/codeflash) installed as a dev dependency ## Installation ### Add the marketplace and install ```bash theme={null} /plugin marketplace add codeflash-ai/codeflash-cc-plugin ``` ```bash theme={null} /plugin install codeflash ``` ### Choose installation scope By default, plugins install at the **user** level (available across all projects). You can change this: | Scope | Flag | Effect | | -------------- | ----------------- | -------------------------------------------------------------------- | | User (default) | *(none)* | Available in all your projects locally via `~/.claude/settings.json` | | Project | `--scope project` | Shared with team with version control via `.claude/settings.json` | | Local | `--scope local` | This project only for local use, gitignored | ### Verify installation Run `/plugin` to open the plugin manager. Confirm **codeflash** appears under the **Installed** tab. ## User-invokable optimization Run the `/optimize` skill with a target file: ``` /optimize --file src/utils.py ``` Run the `/optimize` skill with a target file and a target function: ``` /optimize --file src/utils.py --function my_func ``` Run the `/optimize` skill with a natural language instruction: ``` /optimize the my_func function in utils.py ``` The plugin would work even without the command being explicitly called. ``` make my_func run faster ``` What happens behind the scenes: 1. The skill forks a background **optimizer agent** 2. It parses the instruction to figure out the file and function to optimize 3. The agent walks upward from CWD to the git root, looking for `pyproject.toml` (Python) or `package.json` (JS/TS) 4. It verifies codeflash is installed and configured 5. If configuration is missing, it auto-discovers your module root and tests directory and writes the config for you 6. It runs `codeflash --subagent` in the background with a 10-minute timeout along with the file and function argument. 7. Results are reported when optimization completes You can continue working while codeflash optimizes in the background. ## Continuous Optimization triggered on commit Whenever any new code is commited to the repository after the claude session starts, a new background codeflash **optimizer agent** will spawn automatically to optimize the new code. ## Set up auto-permissions Run `/codeflash:setup` to allow codeflash to execute automatically without permission prompts: ``` /codeflash:setup ``` This adds `Bash(*codeflash*)` to the `permissions.allow` array in `.claude/settings.json`. After this, the post-commit hook can trigger optimizations without asking each time. ## Next steps All commands, flags, and workflows Config reference for Python and JS/TS projects Common problems and fixes How the plugin works internally # Troubleshooting Source: https://docs.codeflash.ai/claude-code-plugin/troubleshooting Common problems and fixes for the Codeflash Claude Code plugin ## Plugin not appearing after install **Symptom**: `/plugin` doesn't show codeflash in the Installed tab. **Fix**: 1. Verify the marketplace was added: `/plugin marketplace add codeflash-ai/codeflash-cc-plugin` 2. Install again: `/plugin install codeflash` 3. Check you're running Claude Code v2.1.38 or later ## `/optimize` does nothing **Symptom**: Running `/optimize` produces no output or immediately returns. **Possible causes**: * No project config found. The agent walks from CWD to the git root looking for `pyproject.toml` or `package.json`. Make sure you're inside a git repository. * Codeflash CLI not installed. For Python: `pip install codeflash` in your venv. For JS/TS: `npm install --save-dev codeflash`. * The agent is running in the background. Check if you see "Codeflash is optimizing in the background" — results appear when the background task completes. ## Permission prompts every time **Symptom**: Claude asks for permission to run codeflash on every invocation. **Fix**: Run `/setup` to add `Bash(*codeflash*)` to `.claude/settings.json`. Or add it manually: ```json theme={null} { "permissions": { "allow": [ "Bash(*codeflash*)" ] } } ``` ## No venv found (Python) **Symptom**: Hook or agent reports "No Python virtual environment was found." **Fix**: 1. Create a venv: `python3 -m venv .venv` 2. Activate it: `source .venv/bin/activate` 3. Install codeflash: `pip install codeflash` 4. Restart Claude Code from within the activated venv The plugin searches for venvs in this order: 1. `/.venv` 2. `/venv` 3. `/.venv` 4. `/venv` ## Codeflash not installed (JS/TS) **Symptom**: `npx codeflash --version` fails or package not found. **Fix**: ```bash theme={null} npm install --save-dev codeflash ``` Run this in the directory containing your `package.json`. ## 10-minute timeout exceeded **Symptom**: Codeflash background task times out. This can happen on large projects. Options: * Optimize specific files instead of the entire project: `/optimize src/specific_file.py` * Target individual functions: `/optimize src/utils.py my_function` ## Formatter errors **Symptom**: Codeflash fails with formatter-related errors. **Check**: 1. Read the `formatter-cmds` (Python) or `formatterCmds` (JS/TS) in your config 2. Verify each formatter is installed: * Python: `which black` (or whichever formatter) * JS/TS: `npx prettier --version` (or whichever formatter) 3. Set `formatter-cmds = ["disabled"]` or `"formatterCmds": ["disabled"]` to skip formatting entirely # Usage Guide Source: https://docs.codeflash.ai/claude-code-plugin/usage-guide Commands, flags, and workflows for the Codeflash Claude Code plugin ## The `/optimize` skill `/optimize` is the primary command. It spawns a background optimizer agent that runs the codeflash CLI on your code. ### Syntax ``` /optimize [file] [function] [flags] ``` ### Examples | Command | Effect | | ------------------------------------ | ------------------------------------------------ | | `/optimize` | Let codeflash detect changed files automatically | | `/optimize src/utils.py` | Optimize all functions in `src/utils.py` | | `/optimize src/utils.py my_function` | Optimize only `my_function` in that file | | `/optimize --all` | Optimize the entire project | Flags can be combined: `/optimize src/utils.py my_function` ### What happens behind the scenes 1. The skill (defined in `skills/optimize/SKILL.md`) forks context and spawns the **optimizer agent** 2. The agent locates your project config (`pyproject.toml`, `package.json`, or `pom.xml`/`gradle.properties`) 3. It verifies the codeflash CLI is installed and the project is configured 4. It runs `codeflash --subagent` as a **background task** with a 10-minute timeout 5. You're notified when optimization completes with results The agent has up to **15 turns** to complete its work (install codeflash, configure the project, run optimization). ## The `/codeflash:setup` command `/codeflash:setup` configures auto-permissions so codeflash runs without prompting. ### What it does 1. Finds `.claude/settings.json` in your project root 2. Checks if `Bash(*codeflash*)` is already in `permissions.allow` 3. If not, adds it (creating the file and directory if needed) 4. Preserves any existing settings Running `/codeflash:setup` multiple times is safe — it's idempotent. If permissions are already configured, it reports "No changes needed." # How Codeflash Measures Code Runtime Source: https://docs.codeflash.ai/codeflash-concepts/benchmarking Learn how Codeflash accurately measures code performance using multiple runs and minimum timing # How Codeflash measures code runtime Codeflash reports benchmarking results that look like this: ```text theme={null} ⏱️ Runtime : 32.8 microseconds → 29.2 microseconds (best of 315 runs) ``` To measure runtime, Codeflash runs a function multiple times with several inputs and sums the minimum time for each input to get the total runtime. A simplified pseudocode of Codeflash benchmarking looks like this: ```python theme={null} loops = 0 min_input_runtime = [float('inf')] * len(test_inputs) start_time = time.time() while loops <= 5 or time.time() - start_time < 10: loops += 1 for input_index, input in enumerate(test_inputs): t = time(function_to_optimize(input)) if t < min_input_runtime[input_index]: min_input_runtime[input_index] = t total_runtime = sum(min_input_runtime) number_of_runs = loops ``` The above code runs the function multiple times on different inputs and uses the minimum time for each input. In this document we explain: * How we measure the runtime of code * How we determine if an optimization is actually faster * Why we measure the timing as best of N runs * How we measure the runtime when we run on a wide variety of test cases. ## Goals of Codeflash auto-benchmarking A core principle of Codeflash is that it makes no assumptions about which optimizations might be faster. Instead, it generates multiple possible optimizations with LLMs and automatically benchmarks the code on a variety of inputs to empirically verify if the optimization is actually faster. The goals of Codeflash auto-benchmarking are: * Accurately measure the runtime of code * Measure runtime for a wide variety of code * Measure runtime on a variety of inputs * Do all the above on a real machine, where other processes might be running and causing timing measurement noise * Finally make a binary decision whether an optimization is faster or not ## Racing Trains as an analogy Imagine you're a boss at a train company choosing between two trains to runs between San Francisco and Los Angeles. You want to determine which train is faster. You can measure their by timing how long each takes to travel between the two cities. However, real-life factors affect train speeds: rail traffic, unfavorable weather, hills, and other obstacles. These can slow them down. To settle the contest, you have a driver race the two trains at maximum possible speed. You measure the travel times between the two cities for each train. Train A took 5% less time than Train B. But the driver points out that Train B encountered poor weather, making it impossible to draw firm conclusions. Since it's crucial to know which train is truly faster, you need more data. You ask the driver to repeat the race multiple times. In this scenario, since they have plenty of time, they repeat the race 50 times. This gives us timing data (in hours) that looks like the following.

With 100 data points (50 per train), determining the faster train becomes more complex. The timing data contains noise from various factors: other trains on the tracks, changing weather, and so on. This makes it challenging to determine which train is faster. Here's the crucial insight: timing noise isn't the train's fault. A train's speed is an intrinsic property, independent of external hindrances. The noise only adds time—there's no "negative noise" that makes trains go faster. Ideally, we'd measure speed with no hindrances at all, giving us clean, noise-free data that shows true speed. In reality, we can't eliminate all noise. Instead, we minimize it by focusing on the "signal"—the train's intrinsic speed—rather than the noise from hindrances. By running multiple races, we get multiple data points. Sometimes conditions are nearly perfect, allowing the train to reach maximum speed. These minimal-noise runs produce the smallest times—our "signal" that reveals the train's true capabilities. We can compare these best times to determine the faster train. The key is finding each train's minimum time between cities—this closely approximates its maximum achievable speed. ## How Codeflash benchmarks code This principle of measuring peak performance while minimizing external noise is exactly how Codeflash measures code runtime. Computer processors face various sources of noise that can increase function runtime: * Hardware: cache misses, CPU frequency scaling, etc. * Operating system: context switches, memory allocation, etc. * Programming language: garbage collection, thread scheduling, etc. Codeflash minimizes noise by running functions multiple times and taking the minimum time. This minimum typically occurs when there are fewest hindrances: the processor frequency is maximal, cache misses are minimal, and the operating system is not doing context switches. This approaches the function's true speed. When comparing an optimization to the original function, Codeflash runs both multiple times and compares their minimum times. This gives us the most accurate measurement of each function's intrinsic speed which is our signal, allowing for a meaningful comparison. We've found that running a function multiple times increases the likelihood of getting these "lucky" minimal-noise runs. To maximize this, Codeflash runs each function for 10 seconds with a minimum of 5 loops, balancing measurement accuracy with reasonable runtime. ## What happens when there are multiple inputs to a function? While this approach works well for single inputs, what about multiple inputs? Now the race runs through multiple stations: Seattle to San Francisco to Los Angeles to San Diego. We still need to determine the faster train for this route. We can only measure times between adjacent stations. Here is how the timing data looks like (in hours):

With 300 data points (50 runs × 3 segments × 2 trains) and varying conditions on each segment, determining the faster train becomes even more challenging. Which train is faster? Our insight about measuring peak performance still applies, but we need to measure each segment separately since the track differs between segments due to hills and track curves. We divide the route into segments between stations and measure each train's fastest time per segment. We find the minimum time for each segment, then sum these minimums to get the total route time. The train with the lowest sum of minimum times is fastest. This approach better captures each train's intrinsic speed because measuring shorter segments reduces the chance of encountering noise in that segment, compared to measuring the entire route. The result is more accurate timing data. Codeflash applies this same principle to functions with multiple inputs. For workloads with multiple inputs, it measures a function's intrinsic speed on each input separately. The total intrinsic runtime is the sum of these individual minimums. This approach proves highly accurate, even on noisy virtual machines. We use a 5% noise floor for runtime (10% on GitHub Actions) and only consider optimizations significant if they're at least 5% faster than the original function. This technique effectively minimizes measurement noise, giving us an accurate measure of a function's true, noise-free, intrinsic speed. # How Codeflash Measures Code Runtime on GPUs Source: https://docs.codeflash.ai/codeflash-concepts/benchmarking-gpu-code Learn how Codeflash accurately measures code performance on GPUs ## Accurate Benchmarking on GPU devices When a GPU (Graphics Processing Unit) operation is executed, it executes **asynchronously**. This means the CPU (Central Processing Unit) queues up work for the GPU and immediately continues to the next line of code - it doesn't wait for the GPU to finish. Accurate measurement of code execution on GPUs involves the insertion of synchronization barriers to ensure no pending GPU tasks are executing before and after the timing measurements are made. ## Illustration ### Without Synchronization ```mermaid actions={false} theme={null} %%{init: {'gantt': {'useWidth': 1200}}}%% gantt title CPU vs CUDA Stream Timeline (Without Synchronization) dateFormat X axisFormat %s section CPU Timer Start :milestone, m1, 0, 0 Launch Kernel 1 :active, cpu0, 0, 4 Launch Kernel 2 :active, cpu1, 4, 8 Launch Kernel 3 :active, cpu2, 8, 12 Timer End :milestone, m2, 12, 12 section CUDA Stream Waiting :done, wait, 0, 4 Kernel 1 :active, k1, 4, 11 Kernel 2 :active, k2, 11, 18 Kernel 3 :active, k3, 18, 25 section Problem Timer ends too early :done, p1, after m2, 25 ``` Here you can see that the timing statements are measuring the duration up till the end of the final kernel launch. The GPU computation hasn't completed yet, which means the timing measurement is not accurate and would affect any future inference based on this information. ### With Synchronization ```mermaid actions={false} theme={null} %%{init: {'gantt': {'useWidth': 1200}}}%% gantt title CPU vs CUDA Stream Timeline (With Synchronization) dateFormat X axisFormat %s section CPU Device Synchronization :done, wait, 0, 4 Timer Start :milestone, m1, 4, 4 Launch Kernel 1 :active, cpu0, 4, 8 Launch Kernel 2 :active, cpu1, 8, 12 Launch Kernel 3 :active, cpu2, 12, 16 Device Synchronization :done, wait, 16, 33 Timer End :milestone, m2, 33, 33 section CUDA Stream Previous Work :done, wait, 0, 4 Waiting :done, wait, 4, 8 Kernel 1 :active, k1, 8, 15 Kernel 2 :active, k2, 15, 22 Kernel 3 :active, k3, 22, 33 ``` Here you can see that a device synchronization call is made before executing the code, this ensures that the CPU waits for any pending GPU tasks to finish before starting the timer. After the launch of the final kernel, another device synchronization call is made which ensures all pending GPU tasks are finished before measuring the runtime. ## Pytorch Example Execute the following code in your Python Interpreter to get the kernel launch time (Replace `cuda` with `mps` everywhere to run on your Mac). ```python theme={null} import torch import time device = "cuda" x = torch.randn(8192, 8192, device=device) y = torch.randn(8192, 8192, device=device) t0 = time.perf_counter_ns() z = torch.matmul(x, y) t1 = time.perf_counter_ns() print(f"Without synchronize: {(t1 - t0) / 1e6:.3f} ms") ``` Now, **Restart** your interpreter and execute the following code to get the kernel execution time (Replace `cuda` with `mps` everywhere to run on your Mac). ```python theme={null} import torch import time device = "cuda" x = torch.randn(8192, 8192, device=device) y = torch.randn(8192, 8192, device=device) torch.cuda.synchronize() # clear any pending work t0 = time.perf_counter_ns() z = torch.matmul(x, y) torch.cuda.synchronize() # wait for GPU to finish t1 = time.perf_counter_ns() print(f"With synchronize: {(t1 - t0) / 1e6:.3f} ms") ``` Expected Output on CUDA ``` Without synchronize: 69.157 ms With synchronize: 152.277 ms ``` # How Codeflash measures execution time involving GPUs Codeflash automatically inserts synchronization barriers before measuring performance. It currently supports GPU code written in `Pytorch`, `Tensorflow` and `JAX` for NVIDIA GPUs (`CUDA`) and MacOS Metal Performance Shaders (`MPS`). * **PyTorch**: Uses `torch.cuda.synchronize()` (`CUDA`) or `torch.mps.synchronize()` (`MPS`) depending on the device. * **JAX**: Uses `jax.block_until_ready()` to wait for computation to complete. It works for both `CUDA` and `MPS` devices. * **TensorFlow**: Uses `tf.test.experimental.sync_devices()` for device synchronization. It works for both `CUDA` and `MPS` devices. # How Codeflash Works Source: https://docs.codeflash.ai/codeflash-concepts/how-codeflash-works Understand Codeflash's generate-and-verify approach to code optimization and correctness verification # 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**, **TypeScript**, and **Java** 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 and Java, 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 in all supported languages. #### Test Discovery 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. For Java, it finds JUnit 5, JUnit 4, and TestNG test classes. 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 To optimize code, Codeflash first gathers all necessary context from the codebase. It also line-profiles your code to understand where the bottlenecks might reside. It then calls our backend to generate several candidate optimizations. These are called "candidates" because their speed and correctness haven't been verified yet. Both properties will be verified in later steps. ## Verification of correctness

The goal of correctness verification is to ensure that when the new code replaces the original code, there are no behavioral changes in the code and the rest of the system. This means the replacement should be completely safe. To verify correctness, Codeflash calls the function with numerous inputs, confirming that the new function behaves identically to the original. Codeflash verifies these specific behaviors to be correct - * function return values match exactly * inputs to function have been mutated exactly the same way as before * exception types remain consistent Additionally, Codeflash checks for sufficient line coverage of the optimized code, increasing confidence in the testing process. We recommend manually reviewing the optimized code since there might be important input cases that we haven’t verified where the behavior could differ. #### Test Generation 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. This works for Python, JavaScript, TypeScript, and Java. * **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 on your machine. For Python, it uses pytest or unittest. For JavaScript/TypeScript, it uses Jest or Vitest. For Java, it uses Maven Surefire or Gradle's test task. Running on your machine ensures access to your environment and dependencies, and provides accurate performance measurements since runtime varies by system. #### Performance benchmarking Codeflash implements [several techniques](/codeflash-concepts/benchmarking) to measure code performance accurately. In particular, it runs multiple iterations of the code in a loop to determine the best performance with the minimum runtime. Codeflash compares the performance of the original code against the optimization, requiring at least a 10% speed improvement before considering it to be faster. This approach eliminates most runtime measurement variability, even on noisy CI systems and virtual machines. The final runtime Codeflash reports is the minimum total time it took to run all the test cases. ## Creating Pull Requests Once an optimization passes all checks, Codeflash creates a pull request through the Codeflash GitHub app directly in your repository. The pull request includes the new code, the speedup percentage, an explanation of the optimization, test statistics including coverage, and the test content itself. You can review, edit, and merge the new code. # Java Configuration Source: https://docs.codeflash.ai/configuration/java Configure Codeflash for Java projects # Java Configuration Codeflash stores its configuration inside your existing build file — `pom.xml` properties for Maven projects, or `gradle.properties` for Gradle projects. No separate config file is needed. ## Maven Configuration For Maven projects, Codeflash writes properties under the `` section of your `pom.xml` with the `codeflash.` prefix: ```xml theme={null} src/main/java src/test/java origin mvn spotless:apply -DspotlessFiles=$file false src/main/java/generated/ ``` ## Gradle Configuration For Gradle projects, Codeflash writes settings to `gradle.properties` with the `codeflash.` prefix: ```properties theme={null} codeflash.moduleRoot=src/main/java codeflash.testsRoot=src/test/java codeflash.gitRemote=origin ``` Codeflash auto-detects most settings from your project structure. Running `codeflash init` will set up the correct config — manual configuration is usually not needed. For standard Maven/Gradle layouts, Codeflash may write no config at all if all defaults are correct. ## Auto-Detection When you run `codeflash init`, Codeflash inspects your project and auto-detects: | Setting | Detection logic | | ------------------ | ------------------------------------------------------------------------------------------------- | | **Source root** | Looks for `src/main/java` (Maven/Gradle standard layout), falls back to pom.xml `sourceDirectory` | | **Test root** | Looks for `src/test/java`, `test/`, `tests/` | | **Build tool** | Detects Maven (`pom.xml`) or Gradle (`build.gradle` / `build.gradle.kts`) | | **Test framework** | Checks build file dependencies for JUnit 5, JUnit 4, or TestNG | ## Configuration Options | Property | Description | Default | | ------------------ | ---------------------------------------------------------- | --------------- | | `moduleRoot` | Source directory to optimize | `src/main/java` | | `testsRoot` | Test directory | `src/test/java` | | `gitRemote` | Git remote for pull requests | `origin` | | `formatterCmds` | Code formatter command (`$file` placeholder for file path) | (none) | | `disableTelemetry` | Disable anonymized telemetry | `false` | | `ignorePaths` | Paths within source root to skip during optimization | (none) | Only non-default values are written to the config. If your project uses the standard `src/main/java` and `src/test/java` layout with the default `origin` remote, Codeflash may not need to write any config properties at all. ## Multi-Module Projects For multi-module Maven/Gradle projects, run `codeflash init` from the module you want to optimize. The config is written to that module's `pom.xml` or `gradle.properties`: ```text theme={null} my-project/ |- client/ | |- src/main/java/com/example/client/ | |- src/test/java/com/example/client/ | |- pom.xml <-- run codeflash init here |- server/ | |- src/main/java/com/example/server/ |- pom.xml ``` For non-standard layouts (like the Aerospike client where source is under `client/src/`), `codeflash init` will prompt you to override the detected paths. ## Tracer Options When using `codeflash optimize` to trace a Java program, these CLI options are available: | Option | Description | Default | | ---------------------- | -------------------------------------------------- | -------- | | `--timeout` | Maximum time (seconds) for each tracing stage | No limit | | `--max-function-count` | Maximum captures per method | 100 | | `--trace-only` | Trace and generate replay tests without optimizing | `false` | Example with timeout: ```bash theme={null} codeflash optimize --timeout 30 java -jar target/my-app.jar --app-args ``` ## Example ### Standard Maven project ```text theme={null} my-app/ |- src/ | |- main/java/com/example/ | | |- App.java | | |- Utils.java | |- test/java/com/example/ | |- AppTest.java |- pom.xml ``` Standard layout — no extra config needed. `codeflash init` detects everything automatically. ### Gradle project ```text theme={null} my-lib/ |- src/ | |- main/java/com/example/ | |- test/java/com/example/ |- build.gradle |- gradle.properties <-- codeflash config written here if overrides needed ``` Standard layout — no extra config needed. `codeflash init` detects everything automatically. # JavaScript / TypeScript Configuration Source: https://docs.codeflash.ai/configuration/javascript Configure Codeflash for JavaScript and TypeScript projects using package.json # JavaScript / TypeScript Configuration Codeflash stores its configuration in `package.json` under the `"codeflash"` key. ## Full Reference ```json theme={null} { "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`. Codeflash auto-detects most settings from your project structure. Running `codeflash init` will set up the correct config — manual configuration is usually not needed. ## 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"`, `"mocha"`. * `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 theme={null} { "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 | | **Mocha** | `mocha` in dependencies | Uses `node:assert/strict`, zero extra deps | **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;` ## Monorepo Configuration For monorepo projects (Yarn workspaces, pnpm workspaces, Lerna, Nx, Turborepo), configure each package individually: ```text theme={null} 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 theme={null} cd packages/core npx codeflash init ``` **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. ### 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 theme={null} pnpm add --filter @my-org/core --save-dev codeflash ``` ## Example ### Standard project ```text theme={null} my-app/ |- src/ | |- utils.js | |- index.js |- tests/ | |- utils.test.js |- package.json ``` ```json theme={null} { "name": "my-app", "codeflash": { "moduleRoot": "src", "testsRoot": "tests" } } ``` ### Project with co-located tests ```text theme={null} my-app/ |- src/ | |- utils.js | |- utils.test.js | |- index.js |- package.json ``` ```json theme={null} { "name": "my-app", "codeflash": { "moduleRoot": "src", "testsRoot": "src" } } ``` ### Project with scattered test folders If your tests are spread across multiple directories (e.g., `test/` at root and `__tests__/` inside `src/`), set `testsRoot` to the common ancestor: ```text theme={null} my-app/ |- src/ | |- utils/ | | |- __tests__/ | | | |- utils.test.js | | |- helpers.js | |- components/ | | |- __tests__/ | | | |- Button.test.jsx | | |- Button.jsx |- test/ | |- integration.test.js |- package.json ``` ```json theme={null} { "name": "my-app", "codeflash": { "moduleRoot": "src", "testsRoot": "." } } ``` **`testsRoot` is a single path.** Codeflash recursively searches for `*.test.js`, `*.spec.js`, and `__tests__/**/*.js` files under this directory. Setting it to `"."` (project root) discovers tests everywhere, including co-located `__tests__/` folders inside `src/`. **Monorepos with per-package tests:** Don't set `testsRoot` to the monorepo root. Instead, run codeflash from each package directory with its own config. Each package's `testsRoot` is relative to that package. ### CommonJS library with no separate test directory ```text theme={null} my-lib/ |- lib/ | |- helpers.js |- test/ | |- helpers.spec.js |- package.json ``` ```json theme={null} { "name": "my-lib", "codeflash": { "moduleRoot": "lib", "testsRoot": "test" } } ``` ## Manual Configuration (without `codeflash init`) If you prefer to configure manually or `codeflash init` doesn't detect your project correctly, add the `"codeflash"` key directly to your `package.json`: ```json theme={null} { "name": "my-project", "codeflash": { "moduleRoot": "src", "testsRoot": "tests", "testRunner": "vitest", "formatterCmds": ["prettier --write $file"], "ignorePaths": ["src/generated/", "src/vendor/"] } } ``` ### Step-by-step 1. **Set `moduleRoot`** — the directory containing your source code. Only files under this path are discovered for optimization. 2. **Set `testsRoot`** — the directory containing your tests. Codeflash searches recursively for `*.test.js`, `*.spec.js`, and `__tests__/**/*.js` files. 3. **Set `testRunner`** (optional) — `"jest"`, `"vitest"`, or `"mocha"`. Auto-detected from `devDependencies` if omitted. 4. **Set `formatterCmds`** (optional) — commands to format optimized code. `$file` is replaced with the file path. Use `["disabled"]` to skip formatting. 5. **Set `ignorePaths`** (optional) — directories to exclude from optimization (relative to `moduleRoot`). ### CLI flag overrides All config values can be overridden via CLI flags: ```bash theme={null} # Override moduleRoot and testsRoot for a single run codeflash --file src/utils.ts --function myFunc \ --module-root src \ --tests-root test \ --no-pr # Specify a directory to optimize (within moduleRoot) codeflash --all src/utils/ ``` ## FAQ Yes, as long as `testsRoot` is set to a common ancestor directory. Codeflash recursively searches for `*.test.js`, `*.spec.js`, and `__tests__/**/*.js` under `testsRoot`. For co-located tests (test files next to source files), set `testsRoot` to the same value as `moduleRoot`: ```json theme={null} { "codeflash": { "moduleRoot": "src", "testsRoot": "src" } } ``` For tests in multiple directories, set `testsRoot` to `"."` (project root) to discover them all. **Note:** `testsRoot` accepts a single path. For monorepos, run codeflash from each package directory with its own config rather than trying to cover all packages from the root. No. Codeflash recursively searches `testsRoot`, so a single path covers all nested test directories. For example, `"testsRoot": "."` discovers tests anywhere in the project: * `test/unit/*.test.js` * `src/components/__tests__/Button.test.tsx` * `lib/utils.spec.js` All of these are found with a single `testsRoot` setting. Codeflash matches tests to functions by: 1. Scanning all test files under `testsRoot` (matching `*.test.*`, `*.spec.*`, `__tests__/**/*`) 2. Parsing imports in each test file using tree-sitter 3. Matching imported function names to the target function If a test file imports `myFunction` from `./utils`, it's considered a test for `myFunction`. Override any value in `package.json` under the `"codeflash"` key. The most common overrides: ```json theme={null} { "codeflash": { "moduleRoot": "src/lib", "testsRoot": ".", "testRunner": "mocha" } } ``` Or use CLI flags for one-off overrides: `--module-root`, `--tests-root`. For internal testing and development, codeflash also reads `codeflash.yaml` files. This is useful when you don't want to modify `package.json`: ```yaml theme={null} module_root: "src" tests_root: "test" test_framework: "vitest" formatter_cmds: [] ``` Place this in the project root. The `package.json` config takes precedence if both exist. # Python Configuration Source: https://docs.codeflash.ai/configuration/python Configure Codeflash for Python projects using pyproject.toml # Python Configuration Codeflash stores its configuration in `pyproject.toml` under the `[tool.codeflash]` section. ## Full Reference ```toml theme={null} [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 theme={null} acme-project/ |- foo_module/ | |- __init__.py | |- foo.py | |- main.py |- tests/ | |- __init__.py | |- test_script.py |- pyproject.toml ``` ```toml theme={null} [tool.codeflash] module-root = "foo_module" tests-root = "tests" ignore-paths = [] ``` # Extension Configuration Source: https://docs.codeflash.ai/editor-plugins/vscode/configuration Configure Codeflash project settings through the extension # Extension Configuration Configure your Codeflash project settings through the extension's configuration page in the sidebar. *** ## Configuration Page The Codeflash extension provides a configuration interface in the sidebar where you can view and update your project's `pyproject.toml` settings. Click the **Codeflash** icon in the VS Code activity bar (left sidebar) to open the extension panel. Make sure you're on the **Optimization** tab. In the Optimization tab, look for the three vertical dots icon (`⋮`) next to the **Optimize** button. Click it to open the menu. From the dropdown menu, click **"Project Config"** to open the configuration interface. Kebab menu next to Optimize button

Use the configuration interface to modify your `pyproject.toml` settings. Changes are saved directly to your project's configuration file. The configuration page also appears automatically when: * The extension detects your project needs configuration * You need to update existing settings * The extension detects configuration issues **Configuration is project-specific** — All settings are stored in your project's `pyproject.toml` file, not in VS Code settings. This ensures your configuration is version-controlled and shared with your team. *** ## Available Configuration Options The extension's configuration page allows you to configure the following settings in your `pyproject.toml`: ### Module Root Specifies which directory contains your Python source code to optimize. * **Setting:** `module-root` * **Example:** `"src"` or `"."` * **Purpose:** Tells Codeflash where to find functions to optimize ### Tests Root Specifies where your test files are located. * **Setting:** `tests-root` * **Example:** `"tests"` or `"test"` * **Purpose:** Tells Codeflash where to find and create test files ### Code Formatter Specifies which code formatter to use for optimized code. * **Setting:** `formatter-cmds` * **Options:** `black`, `ruff`, or custom commands * **Purpose:** Ensures optimized code matches your project's style ### Additional Settings The configuration page also supports other `pyproject.toml` settings such as: * `git-remote` — Git repository remote URL * `ignore-paths` — Paths to exclude from optimization * `override-fixtures` — Custom test fixtures * `benchmarks-root` — Directory for benchmark tests *** ## Manual Configuration You can also edit `pyproject.toml` directly if you prefer: 1. Open `pyproject.toml` in your project root 2. Locate or create the `[tool.codeflash]` section 3. Add or modify configuration options **Format carefully** — Incorrect TOML syntax will cause the extension to show configuration errors. The extension's configuration page helps prevent syntax errors. For a complete reference of all available `pyproject.toml` options, see the [Configuration Reference](/configuration). *** ## Python Interpreter Selection The extension uses the Python interpreter selected in VS Code (via the Microsoft Python extension). To change the interpreter: 1. Press `Ctrl+Shift+P` / `Cmd+Shift+P` 2. Type **"Python: Select Interpreter"** 3. Choose your project's Python environment The extension **automatically reloads** when you change the Python interpreter. Make sure Codeflash is installed in the selected environment. *** ## Configuration Validation The extension validates your configuration and shows helpful error messages if: * `pyproject.toml` is missing or has syntax errors * Required settings are not configured * Paths specified don't exist * Settings conflict with each other When configuration issues are detected, the extension displays clear error messages and suggestions for fixing them. *** ## Next Steps Learn about extension features Fix common issues Complete pyproject.toml reference # Extension Features Source: https://docs.codeflash.ai/editor-plugins/vscode/features Complete guide to VS Code extension features: inline suggestions, sidebar panel, and optimization workflow # Extension Features The Codeflash VS Code extension provides a seamless optimization experience with inline suggestions, a dedicated sidebar panel, and multiple ways to select and optimize functions. *** ## Inline Optimization Suggestions (CodeLens) The extension shows **"optimize"** hints directly above functions that can be optimized: ```python theme={null} # optimize ← Click this to start optimization def process_data(items): result = [] for item in items: if item > 0: result.append(item * 2) return result ``` **How it works:** 1. Open any Python file in your project 2. The extension analyzes your code automatically 3. Functions that can be optimized show an "optimize" hint above them CodeLens hint above function

4. Click the hint to start optimization Look for CodeLens hints above functions in your editor for quick optimization access. Functions must be inside your configured `module-root` directory to show optimization hints. Check your `pyproject.toml` if hints aren't appearing. *** ## Sidebar Panel Overview Access the Codeflash sidebar by clicking the Codeflash icon in the Activity Bar (left side of your editor). The sidebar has two main tabs: * **Optimization** — Select files and functions to optimize, or use quick actions * **Tasks** — View and manage your optimization queue and completed optimizations *** ## Optimization Tab The **Optimization** tab is your main interface for selecting code to optimize. It provides several ways to start optimizing: ### File and Function Selection Optimization tab with file and function selectors

Optimization tab with file and function selectors

At the top of the Optimization tab, you'll find two dropdown selectors: 1. **FILE** — Select a Python file from your workspace * Click the dropdown to browse and select a Python file * The placeholder shows "Select a Python file" until you make a selection 2. **FUNCTION/METHOD** — Select a specific function to optimize * This dropdown is disabled until you select a file first * Once a file is selected, it populates with all optimizable functions (qualified names) * Functions are displayed with their fully qualified names (e.g., `MyClass.my_method` or `module.function_name`) 3. **Optimize Button** — Click the **Optimize** button (with lightning bolt icon) to queue the selected function for optimization **Qualified Names** — Functions are displayed with their fully qualified names, making it easy to identify the exact function you want to optimize, including class methods and nested functions. ### Quick Action Cards Below the file/function selectors, you'll find two action cards for common optimization workflows: #### Optimize Current File * **Icon:** Lightning bolt Optimize current file quick action card

* **Action:** Analyze and optimize all functions in the currently opened file * **How to use:** Click the card to optimize all functions in the active editor tab Optimizing all functions in a large file may take time. The extension will show you the count of functions and ask for confirmation before proceeding. #### Optimize Changed Code * **Icon:** Git diff symbol (intertwined links) Optimize Changed Code quick action card

* **Action:** Optimize functions in your Git diff * **How to use:** Click the card to automatically detect and optimize all modified functions in your current Git changes This is perfect for optimizing code you've just changed before committing. The extension will only optimize functions that are part of your current changes. ### Getting Started Section When you first open the Optimization tab, you'll see a "Ready to Optimize" section with: * A brief description: "AI-powered Python optimization with automatic testing & benchmarking" * A **View Documentation** button to access help and guides *** ## Tasks Tab The **Tasks** tab shows your optimization queue and completed optimizations. Switch to this tab to: * View all queued optimizations * Track progress of running optimizations * Review completed optimizations ### Empty State When you haven't started any optimizations yet, the Tasks tab shows: * A rocket icon * "No optimizations yet" message * Instructions: "Add functions to the queue by clicking the small optimize button above a function" ### Completed Optimizations Once optimizations complete, you'll see a list showing: Completed optimizations list in Tasks tab

Completed optimizations list in Tasks tab

* **Function Name** — The name of the optimized function * **Status Badge** — Shows completion status with speedup information: * "Completed (Xx Faster)" — Displays the performance improvement * Example: "Completed (2.5x Faster)" or "Completed (Speedup: 338.66x Faster)" * **Optimization Quality** — Some optimizations show quality ratings (e.g., "Optimization Quality: High") * **Actions:** * **View Optimization** button — Opens the diff view to see changes and apply them * **View PR** button — Opens the associated pull request (if optimization was created via PR) The Tasks tab shows a badge count (e.g., "Tasks 19") indicating how many optimization tasks you have in total. *** ## Optimization Workflow Once you've selected functions to optimize (via any method above), here's what happens: Selected functions are added to the optimization queue. You can see them in the Tasks tab. Watch the Tasks tab for real-time updates: - Generating optimization candidates - Running tests to verify correctness - Benchmarking performance When complete, you'll see the optimization in the Tasks tab with: - Speedup information (e.g., "2.5x Faster") - Optimization quality rating - **View Optimization** button to see the diff Click **View Optimization** to see the full diff, then **Accept** to apply the optimization, or **Reject** to dismiss it. *** ## Reviewing Optimizations After an optimization completes, you can review it in the Tasks tab or via inline comments. Detailed optimization explanation view

### In the Tasks Tab Click **View Optimization** on any completed optimization to see: * Side-by-side comparison of original vs. optimized code * Performance improvement percentage (speedup) * Runtime comparison (original vs. optimized) * Optimization quality rating * Detailed explanation of what changed and why * **Apply Optimization** button to accept the changes ### Inline Comments The extension also shows inline comments on the optimized function in your editor with options to: * **View Patch** — See the full diff of changes * **Accept** — Apply the optimization to your code * **Reject** — Dismiss the suggestion without changes *** ## Next Steps Customize extension settings Fix common issues # VS Code Extension Source: https://docs.codeflash.ai/editor-plugins/vscode/index Optimize Python code directly in your editor with one-click AI-powered optimizations # VS Code Extension Bring Codeflash directly into your editor. See optimization suggestions inline, track progress in real-time, and apply performance improvements without leaving your code. **Works with multiple editors** — This extension is compatible with VS Code, Cursor, Windsurf, and other VS Code-compatible editors. *** ## Requirements Before installing the extension, ensure you have: * **VS Code 1.94.0+** (or Cursor, Windsurf, or other VS Code-compatible editor) * **Python 3.9+** installed and available in your PATH * **Git repository** initialized for your project * **Microsoft Python extension** installed (the Codeflash extension depends on it) *** ## Installation The quickest way to install for VS Code users: Press `Ctrl+Shift+X` (Windows/Linux) or `Cmd+Shift+X` (macOS) to open the Extensions panel. Type **"Codeflash"** in the search bar. Click **Install** on the Codeflash extension. [Install from VS Code Marketplace →](https://marketplace.visualstudio.com/items?itemName=codeflash.codeflash) Reload VS Code when prompted to activate the extension. For Cursor, Windsurf, air-gapped environments, or when the Marketplace isn't available: Download the latest VSIX package from Open VSX: [Download VSIX →](https://open-vsx.org/extension/codeflash/codeflash) Press `Ctrl+Shift+P` (Windows/Linux) or `Cmd+Shift+P` (macOS). Type and select **"Extensions: Install from VSIX…"** Choose the downloaded `codeflash-*.vsix` file. Restart your editor to complete the installation. *** ## First-Time Setup When you first open a Python file, the extension guides you through setup: The Codeflash sidebar opens automatically, showing the setup wizard. **This step is critical.** The extension uses the Python interpreter selected in VS Code to run Codeflash. Make sure you select the interpreter from the environment where Codeflash is installed. 1. Press `Ctrl+Shift+P` (Windows/Linux) or `Cmd+Shift+P` (macOS) 2. Type **"Python: Select Interpreter"** 3. Choose the Python environment where you installed Codeflash (e.g., your project's virtual environment) 1. Look at the bottom-left status bar in VS Code 2. Click on the Python version shown 3. Select your project's Python interpreter from the list If you see "No Python interpreter selected" or "Codeflash not installed" errors, verify that: * You've selected the correct Python interpreter * Codeflash is installed in that environment (`pip install codeflash`) If Codeflash is not installed in your selected Python environment, the extension prompts you to install it. Click the **"Install codeflash Python package"** button or run: ```bash theme={null} pip install codeflash ``` Authenticate with Codeflash using one of two methods: Click **"Sign in with Browser"** to authenticate via OAuth. This opens your browser where you can log in with your Codeflash account. This is the easiest method — no need to copy/paste API keys! If you prefer to use an API key, you can: 1. **Generate an API key** in the [Codeflash web app](https://app.codeflash.ai) 2. **Copy the API key** from your account settings 3. **Paste it** into the extension's authentication prompt Don't have an account? [Sign up free at app.codeflash.ai](https://app.codeflash.ai/login) The extension runs `codeflash init` to configure your project if needed. This creates or updates your `pyproject.toml` with Codeflash settings. Once setup completes, you'll see "optimize" hints appear above your Python functions. If you've already run `codeflash init` via CLI, the extension detects your existing configuration and skips to the ready state. ### Changing the Python Interpreter If you need to switch to a different Python environment later: 1. **Use VS Code's interpreter selector**: `Ctrl+Shift+P` → "Python: Select Interpreter" 2. **The extension automatically reloads** when you change interpreters The extension uses the Python interpreter selected in VS Code. Make sure Codeflash is installed in the selected environment. *** ## Quick Start Once installed, here's the basic workflow: 1. **Open a Python file** in your project 2. **See "optimize" hints** appear above functions 3. **Click to optimize** — the extension handles the rest 4. **Review and accept** optimizations via inline comments For detailed feature documentation, see [Features](/editor-plugins/vscode/features). *** ## Using with CLI The extension works alongside the Codeflash CLI. You can: * **Use CLI for batch operations** — Run `codeflash --all` for large-scale optimization * **Use extension for interactive work** — Optimize individual functions as you code * **Mix both** — The extension picks up CLI results when you return to the editor *** ## Next Steps Learn about all extension features Customize extension settings Fix common issues *** ## Need Help? * **Discord** — [Join our community](https://www.codeflash.ai/discord) * **GitHub Issues** — [Report bugs or request features](https://github.com/codeflash-ai/codeflash/issues) * **Documentation** — [Full docs at docs.codeflash.ai](https://docs.codeflash.ai) # Extension Troubleshooting Source: https://docs.codeflash.ai/editor-plugins/vscode/troubleshooting Fix common issues with the Codeflash VS Code extension # Extension Troubleshooting Solutions for common issues with the Codeflash VS Code extension. *** ## Common Issues **Symptoms:** No Codeflash icon in sidebar, no "optimize" hints appearing. **Solutions:** 1. **Check Python file is open** — The extension activates when you open a `.py` file 2. **Verify Python extension** — Ensure Microsoft Python extension is installed 3. **Check Output logs** — Go to `View → Output` and select "Codeflash" from the dropdown 4. **Reload extension** — Restart VS Code or reload the window **Symptoms:** Extension is active but no hints above functions. **Solutions:** 1. **Wait for analysis** — The extension needs time to analyze your code 2. **Check module-root** — Functions must be inside your `module-root` directory (check `pyproject.toml`) 3. **Run codeflash init** — Ensure project is initialized: run `codeflash init` in terminal 4. **Check function requirements** — Functions need a `return` statement and shouldn't be properties **Symptoms:** "No Python interpreter selected", "Codeflash not installed", or wrong Python version errors. **Solutions:** 1. **Select the correct Python interpreter:** * Press `Ctrl+Shift+P` / `Cmd+Shift+P` * Type **"Python: Select Interpreter"** * Choose the environment where Codeflash is installed 2. **Verify Codeflash is installed in that environment:** ```bash theme={null} # Check which Python is active which python # Linux/macOS (Get-Command python).Source # Windows PowerShell # Check if Codeflash is installed python -c "import codeflash; print(codeflash.__version__)" ``` 3. **Install Codeflash if missing:** ```bash theme={null} pip install codeflash ``` **Common mistake:** Having multiple Python environments and selecting one that doesn't have Codeflash installed. Always verify Codeflash is installed in your selected interpreter. **Symptoms:** "Failed to connect" or language server errors. **Solutions:** 1. **Reload extension** — Restart VS Code or reload the window 2. **Check network** — Ensure you can reach `app.codeflash.ai` 3. **Verify API key** — Check your API key is valid 4. **View logs** — Check `View → Output → Codeflash` for details **Symptoms:** Extension doesn't install from Marketplace. **Solution:** Install via VSIX instead: 1. Download from [Open VSX](https://open-vsx.org/extension/codeflash/codeflash) 2. Install using VS Code's extension installation feature 3. Restart the editor **Symptoms:** Optimization appears to hang or never finishes. **Solutions:** 1. **Check sidebar status** — Look for error messages in the Codeflash sidebar 2. **Check network** — Ensure stable internet connection 3. **View logs** — Check `View → Output → Codeflash` for errors 4. **Clear tasks** — Use the sidebar to clear completed or failed tasks 5. **Reload extension** — Restart VS Code or reload the window **Symptoms:** Authentication errors, "invalid API key" messages. **Solutions:** 1. **Verify API key** — Check your key at [app.codeflash.ai](https://app.codeflash.ai) 2. **Re-enter key** — The extension may prompt you to re-enter your API key 3. **Check environment variable** — If using `CODEFLASH_API_KEY`, ensure it's set correctly 4. **Reload extension** — Restart VS Code or reload the window *** ## Viewing Logs For detailed debugging information: Go to `View → Output` in the menu bar, or press `Ctrl+Shift+U` / `Cmd+Shift+U`. Click the dropdown in the Output panel and select **"Codeflash"**. Look for error messages, warnings, or stack traces that indicate the issue. When reporting issues, include relevant log output to help diagnose the problem. *** ## Requirements Checklist If you're having issues, verify these requirements: * [ ] VS Code 1.94.0+ (or Cursor/Windsurf) * [ ] Python 3.9+ installed * [ ] Git installed and repository initialized * [ ] Microsoft Python extension installed * [ ] Project has been initialized with `codeflash init` * [ ] `pyproject.toml` exists with `[tool.codeflash]` section * [ ] `module-root` is correctly configured * [ ] Python files are inside the `module-root` directory * [ ] Valid Codeflash API key * [ ] API key entered in extension or set as environment variable * [ ] Network access to `app.codeflash.ai` *** ## Still Need Help? If you're still experiencing issues: * **Discord** — [Join our community](https://www.codeflash.ai/discord) for real-time help * **GitHub Issues** — [Report bugs](https://github.com/codeflash-ai/codeflash/issues) with detailed reproduction steps * **Documentation** — [Full docs](https://docs.codeflash.ai) for reference When reporting issues, please include: * VS Code version * Extension version * Python version * Relevant log output from the Output panel * Steps to reproduce the issue *** ## Next Steps Back to extension overview Learn about extension features Customize extension settings # Java Installation Source: https://docs.codeflash.ai/getting-started/java-installation Install and configure Codeflash for your Java project Codeflash supports optimizing Java projects using Maven or Gradle build systems. It works in two main ways: 1. Codeflash can optimize new java code written in a Pull Request through Github Actions. 2. Codeflash can optimize real workloads end to end. It uses a two-stage tracing approach to capture method arguments and profiling data from running Java program, then optimizes the hottest functions with that data. ### Prerequisites Before installing Codeflash, ensure you have: 1. **Java 11 or above** installed 2. **Maven or Gradle** as your build tool 3. **A Java project** with source code under a standard directory layout Good to have (optional): 1. **Unit tests** (JUnit 5 or JUnit 4) — Codeflash uses them alongside traced replay tests to verify correctness Codeflash uses Python to run its CLI. You can use uv as a package manager and installer for Python programs. To install uv, run the following or [see these instructions](https://docs.astral.sh/uv/getting-started/installation/) ```bash theme={null} curl -LsSf https://astral.sh/uv/install.sh | sh ``` Then install Codeflash as a uv tool. ```bash theme={null} uv tool install codeflash ``` Codeflash uses cloud-hosted AI models. You need to authenticate before running any commands. **Option A: Browser login (recommended)** ```bash theme={null} codeflash auth login ``` This opens your browser to sign in with your GitHub account. Your API key is saved automatically to your shell profile. If you're on a remote server without a browser, a URL will be displayed that you can open on any device. **Option B: API key** 1. Visit the [Codeflash Web App](https://app.codeflash.ai/) and sign up with your GitHub account (free tier available) 2. Navigate to the [API Key](https://app.codeflash.ai/app/apikeys) page to generate your key 3. Set it as an environment variable: ```bash theme={null} export CODEFLASH_API_KEY="your-api-key-here" ``` Add this to your shell profile (`~/.bashrc`, `~/.zshrc`) so it persists across sessions. If you skip this step, `codeflash init` will prompt you to authenticate interactively. Navigate to your Java project root (where `pom.xml` or `build.gradle` is) and run: ```bash theme={null} codeflash init ``` The init command will: 1. **Auto-detect your project** — find your build tool, source root (e.g., `src/main/java`), test root (e.g., `src/test/java`), and test framework 2. **Confirm settings** — show the detected values and ask if you want to change anything 3. **Configure formatter** — let you set up a code formatter (e.g., Spotless, google-java-format) 4. **Install GitHub App** — offer to set up the [Codeflash GitHub App](https://github.com/apps/codeflash-ai/installations/select_target) for automatic PR creation (see next step) 5. **Install GitHub Actions** — offer to add a CI workflow for automated optimization on PRs Only non-default settings are written to your `pom.xml` properties (Maven) or `gradle.properties` (Gradle). For standard layouts, no config changes are needed. **Can I skip init?** Yes. For standard Maven/Gradle projects, Codeflash auto-detects your project structure from `pom.xml` or `build.gradle` at runtime. If you're already authenticated and your project uses a standard layout (`src/main/java`, `src/test/java`), you can skip straight to optimizing. Init is recommended because it also sets up the GitHub App and Actions workflow, and lets you override paths for non-standard project layouts (e.g., multi-module projects where source is under `client/src/`). To have Codeflash create pull requests with optimizations automatically, install the GitHub App: [Install Codeflash GitHub App](https://github.com/apps/codeflash-ai/installations/select_target) Select the repositories you want Codeflash to optimize. This allows the codeflash-ai bot to open PRs with optimization suggestions in your repository. If you prefer to try Codeflash locally first, you can skip this step and use the `--no-pr` flag to apply optimizations directly to your local files (see next step). Optimize a specific function: ```bash theme={null} codeflash --file src/main/java/com/example/Utils.java --function myMethod ``` If you installed the GitHub App, Codeflash will create a pull request with the optimization. If you haven't installed the app yet, or prefer to review changes locally first, add `--no-pr`: ```bash theme={null} codeflash --file src/main/java/com/example/Utils.java --function myMethod --no-pr ``` Or optimize all functions in your project: ```bash theme={null} codeflash --all ``` Codeflash will: 1. Discover optimizable functions in your source code 2. Generate tests and optimization candidates using AI 3. Verify correctness by running tests (JUnit 5, JUnit 4, or TestNG) 4. Benchmark performance improvements 5. Create a pull request with the optimization (or apply locally with `--no-pr`) For advanced workflow tracing (profiling a running Java program), see [Trace & Optimize](/optimizing-with-codeflash/trace-and-optimize). ## Supported build tools | Build Tool | Detection | Test Execution | | ---------- | ----------------------------------- | --------------------- | | **Maven** | `pom.xml` | Maven Surefire plugin | | **Gradle** | `build.gradle` / `build.gradle.kts` | Gradle test task | ## Supported test frameworks | Framework | Support Level | | ----------- | ---------------------- | | **JUnit 5** | Full support (default) | | **JUnit 4** | Full support | | **TestNG** | Basic support | # JavaScript / TypeScript Installation Source: https://docs.codeflash.ai/getting-started/javascript-installation Install and configure Codeflash for your JavaScript/TypeScript project 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, ensure you have: 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** (Jest or Vitest) — Codeflash uses them to verify correctness of optimizations **Node.js 18+ Required** Codeflash requires Node.js 18 or above. Check your version: ```bash theme={null} node --version # Should show v18.0.0 or higher ``` Install Codeflash as a development dependency in your project: ```bash npm theme={null} npm install --save-dev codeflash ``` ```bash yarn theme={null} yarn add --dev codeflash ``` ```bash pnpm theme={null} pnpm add --save-dev codeflash ``` ```bash bun theme={null} bun add --dev codeflash ``` **Dev dependency recommended** — Codeflash is for development and CI workflows. Installing as a dev dependency keeps your production bundle clean. **One-time setup required.** The Codeflash optimizer runs on Python behind the scenes. After installing the npm package, run: ```bash theme={null} npx codeflash setup ``` This automatically creates an isolated Python environment — no global installs or manual Python management needed. After setup, all Codeflash commands run through `npx codeflash` which uses the installed binary automatically. 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 theme={null} export CODEFLASH_API_KEY="your-api-key-here" ``` Or add it to your shell profile (`~/.bashrc`, `~/.zshrc`) for persistence. Navigate to your project root (where `package.json` is) and run: ```bash npm / yarn / pnpm theme={null} npx codeflash init ``` ```bash bun theme={null} bunx codeflash init ``` ```bash Global install theme={null} codeflash init ``` ### What `codeflash init` does 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 theme={null} { "name": "my-project", "codeflash": { "moduleRoot": "src", "testsRoot": "tests" } } ``` **No separate config file needed.** Codeflash stores all configuration inside your existing `package.json`, not in a separate config file. To receive optimization PRs automatically, install the Codeflash GitHub App: [Install Codeflash GitHub App](https://github.com/apps/codeflash-ai/installations/select_target) 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`. ## Monorepo Setup For monorepos (Yarn workspaces, pnpm workspaces, Lerna, Nx, Turborepo), run `codeflash init` from within each package you want to optimize: ```bash theme={null} # Navigate to the specific package cd packages/my-library # Run init from the package directory npx codeflash init ``` Each package gets its own `"codeflash"` section in its `package.json`. The `moduleRoot` and `testsRoot` paths are relative to that package's `package.json`. ### Example: Yarn workspaces monorepo ```text theme={null} 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) ``` ```json theme={null} // packages/core/package.json { "name": "@my-org/core", "codeflash": { "moduleRoot": "src", "testsRoot": "tests" } } ``` **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. **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. ## Test Framework Support | Framework | Status | Auto-detected from | | ---------- | --------- | ------------------------ | | **Jest** | Supported | `jest` in dependencies | | **Vitest** | Supported | `vitest` in dependencies | | **Mocha** | Supported | `mocha` in dependencies | **Mocha projects** use `node:assert/strict` for generated tests (zero extra dependencies). Mocha's `describe`/`it` globals are used automatically — no imports needed. **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`). ## Try It Out Once configured, optimize your code: ```bash Optimize a function theme={null} codeflash --file src/utils.js --function processData ``` ```bash Optimize locally (no PR) theme={null} codeflash --file src/utils.ts --function processData --no-pr ``` ```bash Optimize entire codebase theme={null} codeflash --all ``` ```bash Dry run (see what would be optimized) theme={null} codeflash --all --dry-run ``` ## Troubleshooting Codeflash only optimizes **exported** functions. Make sure your function is exported: ```javascript theme={null} // ES Modules export function processData(data) { ... } // or const processData = (data) => { ... }; export { processData }; // CommonJS function processData(data) { ... } module.exports = { processData }; ``` If codeflash reports the function exists but is not exported, add an export statement. Ensure the codeflash npm package is installed in your project: ```bash npm theme={null} npm install --save-dev codeflash ``` ```bash yarn theme={null} yarn add --dev codeflash ``` ```bash pnpm theme={null} pnpm add --save-dev codeflash ``` For **monorepos**, make sure it's installed in the package you're optimizing, or at the workspace root if dependencies are hoisted. Codeflash auto-detects the test framework from your `devDependencies`. If detection fails: 1. Verify your test framework is in `devDependencies`: ```bash theme={null} npm ls jest # or: npm ls vitest ``` 2. Or set it manually in `package.json`: ```json theme={null} { "codeflash": { "testRunner": "jest" } } ``` 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 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 Run codeflash from the correct package directory: ```bash theme={null} 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`. 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 ## Configuration Reference See [JavaScript / TypeScript Configuration](/configuration/javascript) for the full list of options. ### Next Steps * 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) * Explore [Trace and Optimize](/optimizing-with-codeflash/trace-and-optimize) for workflow optimization # Python Installation Source: https://docs.codeflash.ai/getting-started/local-installation Install and configure Codeflash for your Python project in minutes Codeflash is installed and configured on a per-project basis. ### Prerequisites Before installing Codeflash, ensure you have: 1. **Python 3.9 or above** installed 2. **A Python project** with a virtual environment 3. **Project dependencies installed** in your virtual environment Good to have (optional): 1. **Unit Tests** that Codeflash uses to ensure correctness of the optimizations **Virtual Environment Required** Always install Codeflash in your project's virtual environment, not globally. Make sure your virtual environment is activated before proceeding. ```bash theme={null} source venv/bin/activate # On Linux/Mac # or venv\Scripts\activate # On Windows ``` You can install Codeflash locally for a project by running the following command in the project's virtual environment: ```bash theme={null} pip install codeflash ``` **Codeflash is a Development Dependency** We recommend installing Codeflash as a development dependency. Codeflash is intended to be used in development workflows locally and as part of CI. Try to always use the latest version of Codeflash as it improves quickly. ```bash uv theme={null} uv add --dev codeflash ``` ```bash poetry theme={null} poetry add codeflash@latest --group dev ``` Navigate to your project's root directory (where your `pyproject.toml` file is or should be) and run: ```bash theme={null} codeflash init ``` If you don't have a pyproject.toml file yet, the codeflash init command will ask you to create one **What's pyproject.toml?** `pyproject.toml` is a configuration file that is used to specify build and tool settings for Python projects. `pyproject.toml` is the modern replacement for setup.py and requirements.txt files. When running `codeflash init`, you will see the following prompts: ```text theme={null} 1. Enter your Codeflash API key (or login with Codeflash) 2. Which Python module do you want me to optimize going forward? (e.g. my_module) 3. Where are your tests located? (e.g. tests/) 4. Which code formatter do you use? (black/ruff/other/disabled) 5. Which git remote should Codeflash use for Pull Requests? (if multiple remotes exist) 6. Help us improve Codeflash by sharing anonymous usage data? 7. Install the GitHub app 8. Install GitHub actions for Continuous optimization? ``` After you have answered these questions, the Codeflash configuration will be saved in the `pyproject.toml` file. 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. 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 **Free Tier Available** Codeflash offers a **free tier** with a limited number of optimizations. Perfect for trying it out on small projects! 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 access to your repository to 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. To understand the configuration options, and set more advanced options, see the [Manual Configuration](/configuration) page. ## Try It Out! Once configured, you can start optimizing your code immediately: ```bash theme={null} # Optimize a specific function codeflash --file path/to/your/file.py --function function_name # Or optimize all functions in your codebase codeflash --all ``` Want to see Codeflash in action and don't know what code to optimize? Check out our **optimize-me** repository with code ready to optimize. **What's included:** * Sample Python code with performance issues * Tests for verification * Pre-configured `pyproject.toml` Fork the [optimize-me](https://github.com/codeflash-ai/optimize-me) repo to your GitHub account by clicking "Fork" on the top of the page. This allows Codeflash to open Pull Requests with the optimizations it found on your forked repo. ```bash theme={null} git clone https://github.com/your_github_username/optimize-me.git cd optimize-me ``` ````bash python -m venv .venv source .venv/bin/activate pip install -r theme={null} requirements.txt pip install codeflash ``` ```bash codeflash init # Use your own API key codeflash --all # optimize the entire repo ```` ## Troubleshooting Make sure: * ✅ Your virtual environment is activated * ✅ All project dependencies are installed ```bash theme={null} # Verify your virtual environment is active which python # Should show path to your venv # Install missing dependencies pip install -r requirements.txt ``` Do know that not all functions can be optimized as no optimization opportunities may exist for them. This is fine and expected. To investigate further, use the `--verbose` flag for detailed output: ```bash theme={null} codeflash optimize --verbose ``` This will show: * 🔍 Which functions are being analyzed * 🚫 Why certain functions were skipped * ⚠️ Detailed error messages * 📊 Performance analysis results Verify: * 📁 Your test directory path is correct in `pyproject.toml` * 🔍 Tests are discoverable by your test framework * 📝 Test files follow naming conventions (`test_*.py` for pytest) ```bash theme={null} # Test if pytest can discover your tests pytest --collect-only # Check your pyproject.toml configuration cat pyproject.toml | grep -A 8 "\[tool.codeflash\]" ``` ### Next Steps * Learn about [Codeflash Concepts](/codeflash-concepts/how-codeflash-works) * Explore [Optimization workflows](/optimizing-with-codeflash/one-function) * Set up [Pull Request Optimization](/optimizing-with-codeflash/codeflash-github-actions) * Read [configuration options](/configuration) for advanced setups # Getting the Best Out of Codeflash Source: https://docs.codeflash.ai/getting-the-best-out-of-codeflash Tips, recommendations, and best practices for maximizing Codeflash's optimization capabilities Codeflash is a powerful tool; here are our recommendations based on how the Codeflash team and our customers use Codeflash. ### Install the GitHub App and actions workflow After you install Codeflash on an actively developed project, [installing the GitHub Actions](optimizing-with-codeflash/codeflash-github-actions) will automatically optimize your code whenever new pull requests are opened. This ensures you get the best version of any changes you make to your code without any extra effort. We find that PRs are also the best time to review these changes, because the code is fresh in your mind. ### Find and optimize entire scripts with the Codeflash Tracer Find the best results by running [Codeflash Optimize](optimizing-with-codeflash/trace-and-optimize) on your script to optimize it. This internally runs a profiler, captures inputs to all the functions your script calls, and uses those inputs to create Replay tests and benchmarks. The optimizations you get with this method, show you how much faster your workflow will get plus guarantee that your workflow won't break if you merge in the optimizations. ### Find optimizations on your whole codebase with `codeflash --all` If you have a lot of existing code, run [`codeflash --all`](optimizing-with-codeflash/codeflash-all) to discover and fix any slow code in your project. Codeflash will open new pull requests for any optimizations it finds, and you can review and merge them at your own pace. It is first recommended to trace your tests to achieve higher quality optimizations with this approach ```bash theme={null} codeflash optimize --trace-only -m pytest tests/ ; codeflash --all ``` ### Review the PRs Codeflash opens We're constantly improving Codeflash and the underlying AI models it uses. The state of the art changes weekly, and you can be confident the optimizer will always use the best performing LLMs to find optimizations for your code. That said, because Codeflash uses generative AI, it's still possible that the optimized code may actually have different behavior than the original code under certain conditions. Please review all the PRs that Codeflash opens to ensure that the optimized code is correct, just as you would review any other PR opened by a team member. And don't forget to send us feedback on how we can improve Codeflash - we're always listening! # Codeflash is an AI performance optimizer for your code Source: https://docs.codeflash.ai/index 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**, **TypeScript**, and **Java**. 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 Pick your language to install and configure Codeflash: Install via pip, uv, or poetry. Configure in `pyproject.toml`. Install via npm, yarn, pnpm, or bun. Configure in `package.json`. Supports Jest, Vitest, and Mocha. Install via uv. Supports Maven and Gradle. JUnit 5, JUnit 4, and TestNG. ### How to use Codeflash These commands work for Python, JS/TS, and Java projects: ```bash theme={null} codeflash --file path/to/file --function my_function ``` ```bash theme={null} codeflash --all ``` ```bash theme={null} codeflash optimize myscript.py ``` ```bash theme={null} codeflash init-actions ``` ### Configuration Reference `pyproject.toml` reference `package.json` reference — includes monorepo, scattered tests, manual setup `pom.xml` / `gradle.properties` reference ### How does Codeflash verify correctness? Codeflash verifies the correctness of the optimizations it finds by generating and running new regression tests, as well as any existing tests you may already have. Codeflash tries to ensure that your code behaves the same way before and after the optimization. This offers high confidence that the behavior of your code remains unchanged. ### Continuous Optimization Because Codeflash is an automated process, the main way to use it is by installing it as a GitHub action and have it optimize the new code on every pull request. When Codeflash finds an optimization, it will ask you to review it. It will write a detailed explanation of the changes it made, and include all relevant info like % speed increase and proofs of correctness. This is a great way to ensure that your code, your team's code and your AI Agent's code are optimized for performance before it causes a performance regression. We call this *Continuous Optimization*. ## Questions or Feedback? Your feedback will help us make codeflash better, faster. If you have any questions or feedback, use the Intercom button in the lower right, join our [Discord](https://www.codeflash.ai/discord), or drop us a note at [contact@codeflash.ai](mailto:contact@codeflash.ai) - we read every message! # Optimize Performance Benchmarks with every Pull Request Source: https://docs.codeflash.ai/optimizing-with-codeflash/benchmarking Configure and use benchmark integration for performance-critical code optimization (Python only) **Performance-critical optimization** - Define benchmarks for your most important code sections and let Codeflash optimize and measure the real-world impact of every optimization on your performance metrics. Benchmark mode is an easy way to define workflows that are performance-critical and need to be optimized and run fast. Codeflash will run the benchmark, understand how the current code change in the Pull Request is affecting the benchmark. It will then try to optimize the new code for the benchmark and calculate the impact of any optimization on the speed of that benchmark. ## Using Codeflash in Benchmark Mode Benchmark mode currently supports Python projects using pytest-benchmark. JavaScript/TypeScript benchmark support is coming soon. 1. **Create a benchmarks root:** Create a directory for benchmarks if it does not already exist. In your pyproject.toml, add the path to the 'benchmarks-root' section. ```toml theme={null} [tool.codeflash] # All paths are relative to this pyproject.toml's directory. module-root = "inference" tests-root = "tests" benchmarks-root = "tests/benchmarks" # add your benchmarks root dir here ignore-paths = [] formatter-cmds = ["disabled"] ``` 2. **Define your benchmarks:** 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: ```python theme={null} from core.bubble_sort import sorter def test_sort(benchmark): result = benchmark(sorter, list(reversed(range(500)))) assert result == list(range(500)) ``` 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. 3. **Run and Test Codeflash:** Run Codeflash with the `--benchmark` flag. Note that benchmark mode cannot be used with `--all`. ```bash theme={null} codeflash --file test_file.py --benchmark ``` If you did not define your benchmarks-root in your pyproject.toml, you can do: ```bash theme={null} codeflash --file test_file.py --benchmark --benchmarks-root path/to/benchmarks ``` 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. It will also report the impact of Codeflash's optimizations on your benchmarks. Use `codeflash init` for an easy way to set up Codeflash as a GitHub Action. After that, you can add the `--benchmark` argument to codeflash to enable benchmarks optimization. ```bash theme={null} codeflash --benchmark ``` ## How it works 1. Codeflash identifies benchmarks in the benchmarks-root directory. 2. The benchmarks are run so that runtime statistics and inputs can be recorded. 3. Replay tests are generated so the performance of optimization candidates on the exact inputs used in the benchmarks can be measured. 4. If an optimization candidate is verified to be correct, the speedup of the optimization is calculated for each benchmark. 5. Codeflash then reports the impact of the optimization on each benchmark. Using Codeflash with benchmarks is a great way to find optimizations that really matter. # Optimize Your Entire Codebase Source: https://docs.codeflash.ai/optimizing-with-codeflash/codeflash-all Automatically optimize all codepaths in your project with Codeflash's comprehensive analysis # 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. This works for Python, JavaScript, TypeScript, and Java projects. To optimize your entire codebase, run the following command in your project directory: ```bash theme={null} codeflash --all ``` This requires the Codeflash GitHub App to be installed in your repository. This is a powerful feature that can help you optimize your entire codebase in one go. It also discovers and runs any unit tests covering the function under optimization. Since it runs on all the functions in your codebase, it can take some time to complete, please be patient. As this runs you will see Codeflash opening pull requests for each function it successfully optimizes. If you only want to optimize a subdirectory you can run: ```bash theme={null} codeflash --all path/to/dir ``` If your project has a good number of unit tests, tracing them achieves higher quality results. ```bash theme={null} codeflash optimize --trace-only -m pytest tests/ ; codeflash --all ``` ```bash theme={null} codeflash optimize --trace-only --jest ; codeflash --all # or for Vitest projects codeflash optimize --trace-only --vitest ; codeflash --all ``` ```bash theme={null} codeflash optimize --timeout 60 java -cp target/classes com.example.Main ; codeflash --all ``` 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. ## Important considerations * **Dedicated Optimization Machine:** Optimizing the entire codebase may require considerable time—up to one day. It's recommended to allocate a dedicated machine specifically for this long-running optimization task. * **Minimize Background Processes:** To achieve optimal results, avoid running other processes on the optimization machine. Additional processes can introduce noise into Codeflash's runtime measurements, reducing the quality of the optimizations. Although Codeflash tolerates some runtime fluctuations, minimizing noise ensures the highest optimization quality. * **Checkpoint and Recovery:** Codeflash automatically creates checkpoints as it identifies optimizations. If the optimization process is interrupted or encounters issues, you can resume the process by re-running `codeflash --all`. The command will prompt you to continue from the most recent checkpoint. # Auto Optimize Pull Requests Source: https://docs.codeflash.ai/optimizing-with-codeflash/codeflash-github-actions Automatically optimize new code in pull requests with Codeflash GitHub Actions workflow Optimizing new code in Pull Requests is the best way to ensure that all code you and your team ship is always performant. Automating optimization in the Pull Request stage is how most teams use Codeflash, to continuously find optimizations for their new code. To scan new code for performance optimizations, Codeflash uses a GitHub Action workflow which runs the Codeflash optimization logic on the new code in every pull request. If the action workflow finds an optimization, it communicates with the Codeflash GitHub App and asks it to suggest new changes to the pull request. We highly recommend setting this up, since once you set it up all your new code gets optimized. ## Pull Request Optimization 30 seconds demo