codeflash/docs/configuration/java.mdx

---
title: "Java Configuration"
description: "Configure Codeflash for Java projects"
icon: "java"
sidebarTitle: "Java"
keywords:
  [
    "configuration",
    "java",
    "maven",
    "gradle",
    "junit",
    "pom.xml",
    "gradle.properties",
  ]
---

# 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 `<properties>` section of your `pom.xml` with the `codeflash.` prefix:

```xml
<properties>
    <!-- Only non-default overrides are written -->
    <codeflash.moduleRoot>src/main/java</codeflash.moduleRoot>
    <codeflash.testsRoot>src/test/java</codeflash.testsRoot>
    <codeflash.gitRemote>origin</codeflash.gitRemote>
    <codeflash.formatterCmds>mvn spotless:apply -DspotlessFiles=$file</codeflash.formatterCmds>
    <codeflash.disableTelemetry>false</codeflash.disableTelemetry>
    <codeflash.ignorePaths>src/main/java/generated/</codeflash.ignorePaths>
</properties>
```

## Gradle Configuration

For Gradle projects, Codeflash writes settings to `gradle.properties` with the `codeflash.` prefix:

```properties
codeflash.moduleRoot=src/main/java
codeflash.testsRoot=src/test/java
codeflash.gitRemote=origin
```

<Info>
Codeflash auto-detects most settings from your project structure. Running `codeflash init` will set up the correct config — manual configuration is usually not needed. For standard Maven/Gradle layouts, Codeflash may write no config at all if all defaults are correct.
</Info>

## 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) |

<Info>
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.
</Info>

## 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
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
codeflash optimize --timeout 30 java -jar target/my-app.jar --app-args
```

## Example

### Standard Maven project

```text
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
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.