Skip to main content
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
1

Install Codeflash CLI

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
curl -LsSf https://astral.sh/uv/install.sh | sh
Then install Codeflash as a uv tool.
uv tool install codeflash
2

Authenticate with Codeflash

Codeflash uses cloud-hosted AI models. You need to authenticate before running any commands.Option A: Browser login (recommended)
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 and sign up with your GitHub account (free tier available)
  2. Navigate to the API Key page to generate your key
  3. Set it as an environment variable:
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.
3

Initialize your project (recommended)

Navigate to your Java project root (where pom.xml or build.gradle is) and run:
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 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/).
4

Install the Codeflash GitHub App (recommended)

To have Codeflash create pull requests with optimizations automatically, install the GitHub App:Install Codeflash GitHub AppSelect 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).
5

Run your first optimization

Optimize a specific function:
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:
codeflash --file src/main/java/com/example/Utils.java --function myMethod --no-pr
Or optimize all functions in your project:
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.

​
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