codeflash-ai · mashraf-222 · Jan 27, 2026 · Jan 29, 2026 · Saga4 · Jan 29, 2026
diff --git a/docs/configuration.mdx b/docs/configuration.mdx
@@ -57,6 +57,15 @@ Optional Configuration:
 - `git-remote`: The git remote to use for pull requests. Defaults to `"origin"`.
 - `override-fixtures`: Override pytest fixtures during optimization. Defaults to `false`.
 
+### Overriding configuration from the CLI
+
+You can temporarily override `pyproject.toml` settings when running the CLI:
+
+- **`--config-file PATH`**: Use a different `pyproject.toml` file.
+- **`--module-root PATH`**: Override the configured `module-root`.
+- **`--tests-root PATH`**: Override the configured `tests-root`.
+- **`--benchmarks-root PATH`**: Override the configured `benchmarks-root` (also required when using `--benchmark` if it is not set here).
+
 ## Example Configuration
 
 Here's an example project with the following structure:

diff --git a/docs/editor-plugins/vscode/configuration.mdx b/docs/editor-plugins/vscode/configuration.mdx
@@ -40,14 +40,10 @@ The Codeflash extension provides a configuration interface in the sidebar where
 </Steps>
 
 <Info>
-  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
-</Info>
-
-<Info>
-  **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.
+  The configuration page appears automatically when the extension detects
+  configuration issues, and any changes you make are written to your project's
+  `pyproject.toml` file (so they are version-controlled and shared with your
+  team).
 </Info>
 
 ---

diff --git a/docs/editor-plugins/vscode/features.mdx b/docs/editor-plugins/vscode/features.mdx
@@ -65,20 +65,11 @@ The **Optimization** tab is your main interface for selecting code to optimize.
 
 ![Optimization tab with file and function selectors](../../images/optimization-tab.png)
 
-At the top of the Optimization tab, you'll find two dropdown selectors:
+At the top of the Optimization tab, you'll find:
 
-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
+1. **FILE** — pick a Python file from your workspace.
+2. **FUNCTION/METHOD** — pick a specific function or method in that file.
+3. **Optimize** — click the lightning button to queue that function for optimization.
 
 <Info>
   **Qualified Names** — Functions are displayed with their fully qualified
@@ -123,93 +114,16 @@ When you first open the Optimization tab, you'll see a "Ready to Optimize" secti
 
 ---
 
-## 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](../../images/optimized-function-tab-tasks.png)
-- **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)
-
-<Info>
-  The Tasks tab shows a badge count (e.g., "Tasks 19") indicating how many
-  optimization tasks you have in total.
-</Info>
-
----
-
-## Optimization Workflow
-
-Once you've selected functions to optimize (via any method above), here's what happens:
-
-<Steps>
-  <Step title="Queue Optimization">
-    Selected functions are added to the optimization queue. You can see them in
-    the Tasks tab.
-  </Step>
-  <Step title="Track Progress">
-    Watch the Tasks tab for real-time updates: - Generating optimization
-    candidates - Running tests to verify correctness - Benchmarking performance
-  </Step>
-  <Step title="Review Results">
-    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
-  </Step>
-  <Step title="Apply Changes">
-    Click **View Optimization** to see the full diff, then **Accept** to apply
-    the optimization, or **Reject** to dismiss it.
-  </Step>
-</Steps>
-
----
-
-## Reviewing Optimizations
-
-After an optimization completes, you can review it in the Tasks tab or via inline comments.
-
-![Detailed optimization explanation view](../../images/optimization-details-explaination.png)
-
-### 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
+## Tasks Tab and reviewing optimizations
 
-### Inline Comments
+The **Tasks** tab shows your optimization queue and completed optimizations. You can:
 
-The extension also shows inline comments on the optimized function in your editor with options to:
+- See which functions are queued or running
+- Inspect completed optimizations, including speedup and quality
+- Open the related PR (when the optimization was created via PR)
 
-- **View Patch** — See the full diff of changes
-- **Accept** — Apply the optimization to your code
-- **Reject** — Dismiss the suggestion without changes
+Click **View Optimization** on any completed item to see the diff and explanation, then apply or reject the changes.  
+You will also see inline comments on optimized functions in the editor with actions to **View Patch**, **Accept**, or **Reject**.
 
 ---
 

diff --git a/docs/editor-plugins/vscode/index.mdx b/docs/editor-plugins/vscode/index.mdx
@@ -102,18 +102,9 @@ When you first open a Python file, the extension guides you through setup:
   <Step title="Select Python Interpreter">
     **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.
 
-    <Tabs>
-      <Tab title="Select via Command Palette">
-        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)
-      </Tab>
-      <Tab title="Select via Status Bar">
-        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
-      </Tab>
-    </Tabs>
+    1. Press `Ctrl+Shift+P` (Windows/Linux) or `Cmd+Shift+P` (macOS)
+    2. Type **"Python: Select Interpreter"**
+    3. Pick the environment where you installed Codeflash (for example, your project virtual environment)
 
     <Warning>
       If you see "No Python interpreter selected" or "Codeflash not installed" errors, verify that:
@@ -135,7 +126,8 @@ When you first open a Python file, the extension guides you through setup:
 
     <Tabs>
       <Tab title="Browser Login (Recommended)">
-        Click **"Sign in with Browser"** to authenticate via OAuth. This opens your browser where you can log in with your Codeflash account.
+        - Click **"Sign in with Browser"**
+        - Log in with your Codeflash account in the browser
 
         <Tip>
           This is the easiest method — no need to copy/paste API keys!
@@ -145,9 +137,9 @@ When you first open a Python file, the extension guides you through setup:
       <Tab title="API Key">
         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
+        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
 
         <Tip>
           Don't have an account? [Sign up free at app.codeflash.ai](https://app.codeflash.ai/login)

diff --git a/docs/editor-plugins/vscode/troubleshooting.mdx b/docs/editor-plugins/vscode/troubleshooting.mdx
@@ -29,8 +29,7 @@ Solutions for common issues with the Codeflash VS Code extension.
     **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
+    3. **Reload extension** — Restart VS Code or reload the window
 
   </Accordion>
 
@@ -83,7 +82,7 @@ Solutions for common issues with the Codeflash VS Code extension.
     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
+    4. **View logs** — See the "Viewing Logs" section below
 
   </Accordion>
 

diff --git a/docs/getting-started/local-installation.mdx b/docs/getting-started/local-installation.mdx
@@ -176,6 +176,20 @@ codeflash --all # optimize the entire repo
 </Tab>
 </Tabs>
 
+### Common CLI flags
+
+For everyday use, these are the most important flags:
+
+- **`--file PATH`**: Optimize only this file.
+- **`--function NAME`**: Optimize only this function (requires `--file`).
+- **`--all [PATH]`**: Optimize all functions, optionally under a path.
+- **`--no-pr`**: Apply changes locally instead of creating a pull request.
+- **`--no-gen-tests`**: Use only existing tests, skip test generation.
+- **`--benchmark` / `--benchmarks-root PATH`**: Enable benchmark mode and point to the benchmarks directory.
+- **`--verbose` / `-v`**: Show detailed logs of what Codeflash is doing.
+- **`--verify-setup`**: Run a sample optimization to verify your installation.
+- **`--version`**: Print the Codeflash CLI version.
+
 ## Troubleshooting
 
 <AccordionGroup>

diff --git a/docs/optimizing-with-codeflash/benchmarking.mdx b/docs/optimizing-with-codeflash/benchmarking.mdx
@@ -74,6 +74,12 @@ It will then try to optimize the new code for the benchmark and calculate the im
    codeflash --file test_file.py --benchmark --benchmarks-root path/to/benchmarks
    ```
 
+   <Note>
+     If you see **"benchmarks-root must be specified"**, either set
+     `benchmarks-root` in your `pyproject.toml` or pass
+     `--benchmarks-root` on the CLI.
+   </Note>
+
 4. **Run Codeflash :**
 
    Benchmark mode is best used together with Codeflash as a GitHub Action. This way,

diff --git a/docs/optimizing-with-codeflash/one-function.mdx b/docs/optimizing-with-codeflash/one-function.mdx
@@ -37,6 +37,11 @@ If you want to optimize a function locally, you can add a `--no-pr` argument as
 codeflash --file path/to/your/file.py --function function_name --no-pr
 ```
 
+<Note>
+  If you see **"Functions outside module-root"**, make sure the file lives
+  under the `module-root` directory configured in your `pyproject.toml`.
+</Note>
+
 ### Optimizing class methods
 
 To optimize a method `method_name` in a class `ClassName`, you can run the following command:

diff --git a/docs/optimizing-with-codeflash/trace-and-optimize.mdx b/docs/optimizing-with-codeflash/trace-and-optimize.mdx
@@ -100,6 +100,12 @@ Codeflash script optimizer can be used in three ways:
 
    - `--timeout`: The maximum time in seconds to trace the entire workflow. Default is indefinite. This is useful while tracing really long workflows.
 
+   <Note>
+     Replay test files are named based on the traced script path. If you are
+     unsure where they were written, list files like
+     `tests/test_*replay*.py` in your tests directory.
+   </Note>
+
 3. **As a Context Manager -**
 
    To trace only specific sections of your code, You can also use the Codeflash Tracer as a context manager.