codeflash-ai · mashraf-222 · Apr 2, 2026
diff --git a/.claude/rules/architecture.md b/.claude/rules/architecture.md
@@ -21,7 +21,7 @@ codeflash/
 ├── api/                    # AI service communication
 ├── code_utils/             # Code parsing, git utilities
 ├── models/                 # Pydantic models and types
-├── languages/              # Multi-language support (Python, JavaScript/TypeScript, Java planned)
+├── languages/              # Multi-language support (Python, JavaScript/TypeScript, Java)
 │   ├── base.py                    # LanguageSupport protocol and shared data types
 │   ├── registry.py                # Language registration and lookup by extension/enum
 │   ├── current.py                 # Current language singleton (set_current_language / current_language_support)
@@ -35,11 +35,29 @@ codeflash/
 │   │   ├── test_runner.py         # Test subprocess execution for Python
 │   │   ├── instrument_codeflash_capture.py  # Instrument __init__ with capture decorators
 │   │   └── parse_line_profile_test_output.py  # Parse line profiler output
-│   └── javascript/
-│       ├── support.py             # JavaScriptSupport (LanguageSupport implementation)
-│       ├── function_optimizer.py  # JavaScriptFunctionOptimizer subclass
-│       ├── optimizer.py           # JS project root finding & module preparation
-│       └── normalizer.py          # JS/TS code normalization for deduplication
+│   ├── javascript/
+│   │   ├── support.py             # JavaScriptSupport (LanguageSupport implementation)
+│   │   ├── function_optimizer.py  # JavaScriptFunctionOptimizer subclass
+│   │   ├── optimizer.py           # JS project root finding & module preparation
+│   │   └── normalizer.py          # JS/TS code normalization for deduplication
+│   └── java/
+│       ├── support.py             # JavaSupport (LanguageSupport implementation)
+│       ├── function_optimizer.py  # JavaFunctionOptimizer subclass
+│       ├── build_tool_strategy.py # Abstract BuildToolStrategy for Maven/Gradle
+│       ├── maven_strategy.py      # Maven build tool strategy
+│       ├── gradle_strategy.py     # Gradle build tool strategy
+│       ├── build_tools.py         # Build tool detection and project info
+│       ├── build_config_strategy.py # Config read/write for pom.xml / gradle.properties
+│       ├── test_runner.py         # Test execution via Maven/Gradle
+│       ├── instrumentation.py     # Behavior capture and benchmarking instrumentation
+│       ├── discovery.py           # Function discovery using tree-sitter
+│       ├── test_discovery.py      # Test discovery for JUnit/TestNG
+│       ├── context.py             # Code context extraction
+│       ├── comparator.py          # Test result comparison
+│       ├── config.py              # Java project detection and config
+│       ├── formatter.py           # Code formatting and normalization
+│       ├── line_profiler.py       # JVM bytecode agent-based line profiling
+│       └── tracer.py              # Two-stage JFR + argument capture tracer
 ├── setup/                  # Config schema, auto-detection, first-run experience
 ├── picklepatch/            # Serialization/deserialization utilities
 ├── tracing/                # Function call tracing
@@ -57,7 +75,7 @@ codeflash/
 |------|------------|
 | CLI arguments & commands | `cli_cmds/cli.py` (parsing), `main.py` (subcommand dispatch) |
 | Optimization orchestration | `optimization/optimizer.py` → `run()` |
-| Per-function optimization | `languages/function_optimizer.py` (base), `languages/python/function_optimizer.py`, `languages/javascript/function_optimizer.py` |
+| Per-function optimization | `languages/function_optimizer.py` (base), `languages/python/function_optimizer.py`, `languages/javascript/function_optimizer.py`, `languages/java/function_optimizer.py` |
 | Function discovery | `discovery/functions_to_optimize.py` |
 | Context extraction | `languages/<lang>/context/code_context_extractor.py` |
 | Test execution | `languages/<lang>/support.py` (`run_behavioral_tests`, etc.), `verification/pytest_plugin.py` |
@@ -67,7 +85,7 @@ codeflash/
 
 ## LanguageSupport Protocol Methods
 
-Core protocol in `languages/base.py`. Each language (`PythonSupport`, `JavaScriptSupport`) implements these.
+Core protocol in `languages/base.py`. Each language (`PythonSupport`, `JavaScriptSupport`, `JavaSupport`) implements these.
 
 | Category | Method/Property | Purpose |
 |----------|----------------|---------|

diff --git a/docs/claude-code-plugin/usage-guide.mdx b/docs/claude-code-plugin/usage-guide.mdx
@@ -29,7 +29,7 @@ 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` or `package.json` or `codeflash.toml`)
+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

diff --git a/docs/configuration/java.mdx b/docs/configuration/java.mdx
@@ -1,43 +1,52 @@
 ---
 title: "Java Configuration"
-description: "Configure Codeflash for Java projects using codeflash.toml"
+description: "Configure Codeflash for Java projects"
 icon: "java"
-sidebarTitle: "Java (codeflash.toml)"
+sidebarTitle: "Java"
 keywords:
   [
     "configuration",
-    "codeflash.toml",
     "java",
     "maven",
     "gradle",
     "junit",
+    "pom.xml",
+    "gradle.properties",
   ]
 ---
 
 # Java Configuration
 
-Codeflash stores its configuration in `codeflash.toml` under the `[tool.codeflash]` section.
+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.
 
-## Full Reference
+## Maven Configuration
 
-```toml
-[tool.codeflash]
-# Required
-module-root = "src/main/java"
-tests-root = "src/test/java"
-language = "java"
+For Maven projects, Codeflash writes properties under the `<properties>` section of your `pom.xml` with the `codeflash.` prefix:
 
-# Optional
-test-framework = "junit5"        # "junit5", "junit4", or "testng"
-disable-telemetry = false
-git-remote = "origin"
-ignore-paths = ["src/main/java/generated/"]
+```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>
 ```
 
-All file paths are relative to the directory containing `codeflash.toml`.
+## 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.
+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
@@ -46,54 +55,42 @@ When you run `codeflash init`, Codeflash inspects your project and auto-detects:
 
 | Setting | Detection logic |
 |---------|----------------|
-| `module-root` | Looks for `src/main/java` (Maven/Gradle standard layout) |
-| `tests-root` | Looks for `src/test/java`, `test/`, `tests/` |
-| `language` | Detected from build files (`pom.xml`, `build.gradle`) and `.java` files |
-| `test-framework` | Checks build file dependencies for JUnit 5, JUnit 4, or TestNG |
-
-## Required Options
+| **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) |
 
-- **`module-root`**: The source directory to optimize. Only code under this directory is discovered for optimization. For standard Maven/Gradle projects, this is `src/main/java`.
-- **`tests-root`**: The directory where your tests are located. Codeflash discovers existing tests and places generated replay tests here.
-- **`language`**: Must be set to `"java"` for Java projects.
-
-## Optional Options
-
-- **`test-framework`**: Test framework. Auto-detected from build dependencies. Supported values: `"junit5"` (default), `"junit4"`, `"testng"`.
-- **`disable-telemetry`**: Disable anonymized telemetry. Defaults to `false`.
-- **`git-remote`**: Git remote for pull requests. Defaults to `"origin"`.
-- **`ignore-paths`**: Paths within `module-root` to skip during optimization.
+<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, place `codeflash.toml` at the project root and set `module-root` to the module you want to optimize:
+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
-|- codeflash.toml
-```
-
-```toml
-[tool.codeflash]
-module-root = "client/src/main/java"
-tests-root = "client/src/test/java"
-language = "java"
 ```
 
-For non-standard layouts (like the Aerospike client where source is under `client/src/`), adjust paths accordingly:
-
-```toml
-[tool.codeflash]
-module-root = "client/src"
-tests-root = "test/src"
-language = "java"
-```
+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
 
@@ -124,15 +121,9 @@ my-app/
 |  |- test/java/com/example/
 |     |- AppTest.java
 |- pom.xml
-|- codeflash.toml
 ```
 
-```toml
-[tool.codeflash]
-module-root = "src/main/java"
-tests-root = "src/test/java"
-language = "java"
-```
+Standard layout — no extra config needed. `codeflash init` detects everything automatically.
 
 ### Gradle project
 
@@ -142,12 +133,7 @@ my-lib/
 |  |- main/java/com/example/
 |  |- test/java/com/example/
 |- build.gradle
-|- codeflash.toml
+|- gradle.properties    <-- codeflash config written here if overrides needed
 ```
 
-```toml
-[tool.codeflash]
-module-root = "src/main/java"
-tests-root = "src/test/java"
-language = "java"
-```
+Standard layout — no extra config needed. `codeflash init` detects everything automatically.
diff --git a/docs/getting-started/java-installation.mdx b/docs/getting-started/java-installation.mdx
@@ -58,29 +58,31 @@ codeflash init
 This will:
 - Detect your build tool (Maven/Gradle)
 - Find your source and test directories
-- Update your pom.xml or gradle settings with codeflash java library. The java library instruments your code and verifies correctness.
+- Write Codeflash configuration to your `pom.xml` properties (Maven) or `gradle.properties` (Gradle)
 
 </Step>
 <Step title="Run your first optimization">
 
-Trace and optimize a Java program:
+Optimize a specific function:
 
 ```bash
-codeflash optimize java -jar target/my-app.jar
+codeflash --file src/main/java/com/example/Utils.java --function myMethod
 ```
 
-Or with Maven:
+Or optimize all functions in your project:
 
 ```bash
-codeflash optimize mvn exec:java -Dexec.mainClass="com.example.Main"
+codeflash --all
 ```
 
 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 to create a micro-benchmark.
-4. Rank functions by performance impact
-5. Optimize the most impactful functions
+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 (if the GitHub App is installed)
+
+For advanced workflow tracing (profiling a running Java program), see [Trace & Optimize](/optimizing-with-codeflash/trace-and-optimize).
 
 </Step>
 </Steps>

diff --git a/docs/index.mdx b/docs/index.mdx
@@ -2,11 +2,11 @@
 title: "Codeflash is an AI performance optimizer for your code"
 icon: "rocket"
 sidebarTitle: "Overview"
-keywords: ["python", "javascript", "typescript", "performance", "optimization", "AI", "code analysis", "benchmarking"]
+keywords: ["python", "javascript", "typescript", "java", "performance", "optimization", "AI", "code analysis", "benchmarking"]
 ---
 
 Codeflash speeds up your code by figuring out the best way to rewrite it while verifying that the behavior is unchanged, and verifying real speed
-gains through performance benchmarking. It supports **Python**, **JavaScript**, and **TypeScript**.
+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.
@@ -15,18 +15,21 @@ does not modify the system architecture of your code, but it tries to find the m
 
 Pick your language to install and configure Codeflash:
 
-<CardGroup cols={2}>
+<CardGroup cols={3}>
   <Card title="Python" icon="python" href="/getting-started/local-installation">
     Install via pip, uv, or poetry. Configure in `pyproject.toml`.
   </Card>
   <Card title="JavaScript / TypeScript" icon="js" href="/getting-started/javascript-installation">
     Install via npm, yarn, pnpm, or bun. Configure in `package.json`. Supports Jest, Vitest, and Mocha.
   </Card>
+  <Card title="Java" icon="java" href="/getting-started/java-installation">
+    Install via uv. Supports Maven and Gradle. JUnit 5, JUnit 4, and TestNG.
+  </Card>
 </CardGroup>
 
 ### How to use Codeflash
 
-These commands work for both Python and JS/TS projects:
+These commands work for Python, JS/TS, and Java projects:
 
 <CardGroup cols={2}>
   <Card title="Optimize a Function" icon="bullseye" href="/optimizing-with-codeflash/one-function">
@@ -56,13 +59,16 @@ These commands work for both Python and JS/TS projects:
 
 ### Configuration Reference
 
-<CardGroup cols={2}>
+<CardGroup cols={3}>
   <Card title="Python Config" icon="python" href="/configuration/python">
     `pyproject.toml` reference
   </Card>
   <Card title="JS / TS Config" icon="js" href="/configuration/javascript">
     `package.json` reference — includes monorepo, scattered tests, manual setup
   </Card>
+  <Card title="Java Config" icon="java" href="/configuration/java">
+    `pom.xml` / `gradle.properties` reference
+  </Card>
 </CardGroup>
 
 ### How does Codeflash verify correctness?

diff --git a/docs/optimizing-with-codeflash/codeflash-all.mdx b/docs/optimizing-with-codeflash/codeflash-all.mdx
@@ -9,7 +9,7 @@ keywords: ["codebase optimization", "all functions", "batch optimization", "gith
 # 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, and TypeScript projects.
+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:
 

diff --git a/docs/optimizing-with-codeflash/one-function.mdx b/docs/optimizing-with-codeflash/one-function.mdx
@@ -13,6 +13,7 @@ keywords:
     "javascript",
     "typescript",
     "python",
+    "java",
   ]
 ---
 
@@ -45,6 +46,11 @@ codeflash --file path/to/your/file.js --function functionName
 codeflash --file path/to/your/file.ts --function functionName
 ```
 </Tab>
+<Tab title="Java">
+```bash
+codeflash --file src/main/java/com/example/Utils.java --function methodName
+```
+</Tab>
 </Tabs>
 
 If you have installed the GitHub App to your repository, the above command will open a pull request with the optimized function.
@@ -61,6 +67,11 @@ codeflash --file path/to/your/file.py --function function_name --no-pr
 codeflash --file path/to/your/file.ts --function functionName --no-pr
 ```
 </Tab>
+<Tab title="Java">
+```bash
+codeflash --file src/main/java/com/example/Utils.java --function methodName --no-pr
+```
+</Tab>
 </Tabs>
 
 ### Optimizing class methods
@@ -78,4 +89,9 @@ codeflash --file path/to/your/file.py --function ClassName.method_name
 codeflash --file path/to/your/file.ts --function ClassName.methodName
 ```
 </Tab>
+<Tab title="Java">
+```bash
+codeflash --file src/main/java/com/example/Utils.java --function methodName
+```
+</Tab>
 </Tabs>