Skip to main content
Codeflash supports Java projects using Maven or Gradle build systems. It uses a two-stage tracing approach to capture method arguments and profiling data from running Java programs, then optimizes the hottest functions.

​
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
1

Install Codeflash CLI

Codeflash CLI is a Python tool. Install it with pip:
pip install codeflash
Or with uv:
uv pip install codeflash
2

Initialize your project

Navigate to your Java project root (where pom.xml or build.gradle is) and run:
codeflash init
This will:
  • Detect your build tool (Maven/Gradle)
  • Find your source and test directories
  • Create a codeflash.toml configuration file
3

Verify setup

Check that the configuration looks correct:
cat codeflash.toml
You should see something like:
[tool.codeflash]
module-root = "src/main/java"
tests-root = "src/test/java"
language = "java"
4

Run your first optimization

Trace and optimize a running Java program:
codeflash optimize java -jar target/my-app.jar
Or with Maven:
codeflash optimize mvn exec:java -Dexec.mainClass="com.example.Main"
Codeflash will:
  1. Profile your program using JFR (Java Flight Recorder)
  2. Capture method arguments using a bytecode instrumentation agent
  3. Generate JUnit replay tests from the captured data
  4. Rank functions by performance impact
  5. Optimize the most impactful functions

​
How it works

Codeflash uses a two-stage tracing approach for Java:
  1. Stage 1 — JFR Profiling: Runs your program with Java Flight Recorder enabled to collect accurate method-level CPU profiling data. JFR has ~1% overhead and doesn’t affect JIT compilation.
  2. Stage 2 — Argument Capture: Runs your program again with a bytecode instrumentation agent that captures method arguments using Kryo serialization. Arguments are stored in an SQLite database.
The traced data is used to generate JUnit replay tests that exercise your functions with real-world inputs. Codeflash uses these tests alongside any existing unit tests to verify correctness and benchmark optimization candidates.
Your program runs twice — once for profiling, once for argument capture. This separation ensures profiling data isn’t distorted by serialization overhead.

​
Supported build tools

Build ToolDetectionTest Execution
Mavenpom.xmlMaven Surefire plugin
Gradlebuild.gradle / build.gradle.ktsGradle test task

​
Supported test frameworks

FrameworkSupport Level
JUnit 5Full support (default)
JUnit 4Full support
TestNGBasic support