From e55a19154eff61a8fb3a669575f395df1eb7e042 Mon Sep 17 00:00:00 2001 From: Mohamed Ashraf Date: Fri, 16 Jan 2026 14:35:24 +0200 Subject: [PATCH 1/3] add vsc extension docs --- docs/docs.json | 9 +- docs/editor-plugins/vscode.mdx | 48 ---- docs/editor-plugins/vscode/configuration.mdx | 150 +++++++++++ docs/editor-plugins/vscode/features.mdx | 225 +++++++++++++++++ docs/editor-plugins/vscode/index.mdx | 235 ++++++++++++++++++ .../editor-plugins/vscode/troubleshooting.mdx | 215 ++++++++++++++++ 6 files changed, 832 insertions(+), 50 deletions(-) delete mode 100644 docs/editor-plugins/vscode.mdx create mode 100644 docs/editor-plugins/vscode/configuration.mdx create mode 100644 docs/editor-plugins/vscode/features.mdx create mode 100644 docs/editor-plugins/vscode/index.mdx create mode 100644 docs/editor-plugins/vscode/troubleshooting.mdx diff --git a/docs/docs.json b/docs/docs.json index 680707a9c..b469f19cb 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -31,8 +31,13 @@ "pages": ["cli-reference"] }, { - "group": "🛠 IDE Extensions", - "pages": ["editor-plugins/vscode"] + "group": "🛠 IDE Extension", + "pages": [ + "editor-plugins/vscode/index", + "editor-plugins/vscode/features", + "editor-plugins/vscode/configuration", + "editor-plugins/vscode/troubleshooting" + ] }, { "group": "⚡ Optimizing with Codeflash", diff --git a/docs/editor-plugins/vscode.mdx b/docs/editor-plugins/vscode.mdx deleted file mode 100644 index 2c2204ecd..000000000 --- a/docs/editor-plugins/vscode.mdx +++ /dev/null @@ -1,48 +0,0 @@ -# VS Code Extension & VSIX Installation - -Bring Codeflash directly into your editor with the Visual Studio Code extension. The extension surfaces optimization suggestions inline, and keeps the CLI workflow close at hand with more visual experience in editor. - -## Requirements - -- VS Code 1.94.0 or later (Code, VS Code Desktop, Cursor, Windsurf and other VS Code–compatible editors supported) -- Python 3.9+ -- Git repository initialized for your project -- Codeflash CLI installed and initialized with `codeflash init` (Extension will also walkthrough with interactive onboarding) - -## Install from the Marketplace - -1. Open VS Code and head to the Extensions panel. -2. Search for **“Codeflash”** or open the listing directly:
- [Install from VS Code Marketplace →](https://marketplace.visualstudio.com/items?itemName=codeflash.codeflash) -3. Click **Install** and reload VS Code when prompted. - -That’s it! As soon as you open a Python file inside a project that has already run `codeflash init`, the extension analyses the codebase and starts surfacing optimization opportunities. - -## Install via VSIX (Cursor, offline, or air‑gapped environments) - -Some environments—Cursor, Windows without Marketplace access, or air-gapped machines—require installing from a VSIX package. - -1. Download the latest VSIX build from Open VSX:
- [Download VSIX →](https://open-vsx.org/extension/codeflash/codeflash) -2. In VS Code, run the command palette (`Cmd/Ctrl + Shift + P`) and select **Extensions: Install from VSIX…** -3. Choose the downloaded `codeflash-*.vsix` file and restart the editor. - -## Initial Setup Checklist -- The complete Setup flow is within extension to initialize codeflash LSP server - -## Everyday Workflow - -- **Inline suggestions:** Optimizable functions display a “optimize” hint above the function definition. And once optimized they will show a comment where you can click it to preview and apply improvements. -- **Sidebar overview:** Use the Codeflash panel to review queued, inprogress, and completed optimizations. -- **Targeted runs:** Trigger “Optimize Changed Functions” from the extension to focus on recent uncommited edits. -- **Pair with CLI:** For batch workflows (`codeflash --all`), you can still run the CLI. The extension will pick up the results when you return to the editor. - -## Troubleshooting - -| Issue | Quick Fix | -| ----- | --------- | -| Using Cursor / custom VS Code build | Install via VSIX and restart the editor. | -| Still stuck? | Reach out on [Discord](https://www.codeflash.ai/discord) or file an issue on [GitHub](https://github.com/codeflash-ai/codeflash/issues). | - -With the extension in place, you can review, accept, or iterate on optimizations without leaving your editor—perfect for maintaining focus while keeping performance top of mind. - diff --git a/docs/editor-plugins/vscode/configuration.mdx b/docs/editor-plugins/vscode/configuration.mdx new file mode 100644 index 000000000..4ba552a2b --- /dev/null +++ b/docs/editor-plugins/vscode/configuration.mdx @@ -0,0 +1,150 @@ +--- +title: "Extension Configuration" +description: "Configure Codeflash project settings through the extension" +icon: "gear" +sidebarTitle: "Configuration" +keywords: + [ + "configuration", + "settings", + "pyproject.toml", + "project configuration", + ] +--- + +# Extension Configuration + +Configure your Codeflash project settings through the extension's configuration page in the sidebar. + +--- + +## Configuration Page + +The Codeflash extension provides a configuration interface in the sidebar where you can view and update your project's `pyproject.toml` settings. + + + + Click the **Codeflash** icon in the VS Code activity bar (left sidebar) to open the extension panel. Make sure you're on the **Optimization** tab. + + + In the Optimization tab, look for the three vertical dots icon (`⋮`) next to the **Optimize** button. Click it to open the menu. + + + From the dropdown menu, click **"Project Config"** to open the configuration interface. + + + Use the configuration interface to modify your `pyproject.toml` settings. Changes are saved directly to your project's configuration file. + + + + + 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 + + + + **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. + + +--- + +## Available Configuration Options + +The extension's configuration page allows you to configure the following settings in your `pyproject.toml`: + +### Module Root + +Specifies which directory contains your Python source code to optimize. + +- **Setting:** `module-root` +- **Example:** `"src"` or `"."` +- **Purpose:** Tells Codeflash where to find functions to optimize + +### Tests Root + +Specifies where your test files are located. + +- **Setting:** `tests-root` +- **Example:** `"tests"` or `"test"` +- **Purpose:** Tells Codeflash where to find and create test files + +### Code Formatter + +Specifies which code formatter to use for optimized code. + +- **Setting:** `formatter-cmds` +- **Options:** `black`, `ruff`, or custom commands +- **Purpose:** Ensures optimized code matches your project's style + +### Additional Settings + +The configuration page also supports other `pyproject.toml` settings such as: + +- `git-remote` — Git repository remote URL +- `ignore-paths` — Paths to exclude from optimization +- `override-fixtures` — Custom test fixtures +- `benchmarks-root` — Directory for benchmark tests + +--- + +## Manual Configuration + +You can also edit `pyproject.toml` directly if you prefer: + +1. Open `pyproject.toml` in your project root +2. Locate or create the `[tool.codeflash]` section +3. Add or modify configuration options + + + **Format carefully** — Incorrect TOML syntax will cause the extension to show configuration errors. The extension's configuration page helps prevent syntax errors. + + +For a complete reference of all available `pyproject.toml` options, see the [Configuration Reference](/configuration). + +--- + +## Python Interpreter Selection + +The extension uses the Python interpreter selected in VS Code (via the Microsoft Python extension). To change the interpreter: + +1. Press `Ctrl+Shift+P` / `Cmd+Shift+P` +2. Type **"Python: Select Interpreter"** +3. Choose your project's Python environment + + + The extension **automatically reloads** when you change the Python interpreter. Make sure Codeflash is installed in the selected environment. + + +--- + +## Configuration Validation + +The extension validates your configuration and shows helpful error messages if: + +- `pyproject.toml` is missing or has syntax errors +- Required settings are not configured +- Paths specified don't exist +- Settings conflict with each other + +When configuration issues are detected, the extension displays clear error messages and suggestions for fixing them. + +--- + +## Next Steps + + + + Learn about extension features + + + Fix common issues + + + Complete pyproject.toml reference + + + Command-line options + + diff --git a/docs/editor-plugins/vscode/features.mdx b/docs/editor-plugins/vscode/features.mdx new file mode 100644 index 000000000..5b975d505 --- /dev/null +++ b/docs/editor-plugins/vscode/features.mdx @@ -0,0 +1,225 @@ +--- +title: "Extension Features" +description: "Complete guide to VS Code extension features: inline suggestions, sidebar panel, and optimization workflow" +icon: "sparkles" +sidebarTitle: "Features" +keywords: ["features", "CodeLens", "sidebar", "optimization", "workflow"] +--- + +# Extension Features + +The Codeflash VS Code extension provides a seamless optimization experience with inline suggestions, a dedicated sidebar panel, and multiple ways to select and optimize functions. + +--- + +## Inline Optimization Suggestions (CodeLens) + +The extension shows **"optimize"** hints directly above functions that can be optimized: + +```python +# optimize ← Click this to start optimization +def process_data(items): + result = [] + for item in items: + if item > 0: + result.append(item * 2) + return result +``` + +**How it works:** + +1. Open any Python file in your project +2. The extension analyzes your code automatically +3. Functions that can be optimized show an "optimize" hint above them +4. Click the hint to start optimization + + + Look for CodeLens hints above functions in your editor for quick optimization + access. + + + + Functions must be inside your configured `module-root` directory to show + optimization hints. Check your `pyproject.toml` if hints aren't appearing. + + +--- + +## Sidebar Panel Overview + +Access the Codeflash sidebar by clicking the Codeflash icon in the Activity Bar (left side of your editor). + +The sidebar has two main tabs: + +- **Optimization** — Select files and functions to optimize, or use quick actions +- **Tasks** — View and manage your optimization queue and completed optimizations + +--- + +## Optimization Tab + +The **Optimization** tab is your main interface for selecting code to optimize. It provides several ways to start optimizing: + +### File and Function Selection + +At the top of the Optimization tab, you'll find two dropdown selectors: + +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 + + + **Qualified Names** — Functions are displayed with their fully qualified + names, making it easy to identify the exact function you want to optimize, + including class methods and nested functions. + + +### Quick Action Cards + +Below the file/function selectors, you'll find two action cards for common optimization workflows: + +#### Optimize Current File + +- **Icon:** Lightning bolt +- **Action:** Analyze and optimize all functions in the currently opened file +- **How to use:** Click the card to optimize all functions in the active editor tab + + + Optimizing all functions in a large file may take time. The extension will + show you the count of functions and ask for confirmation before proceeding. + + +#### Optimize Changed Code + +- **Icon:** Git diff symbol (intertwined links) +- **Action:** Optimize functions in your Git diff +- **How to use:** Click the card to automatically detect and optimize all modified functions in your current Git changes + + + This is perfect for optimizing code you've just changed before committing. The + extension will only optimize functions that are part of your current changes. + + +### Getting Started Section + +When you first open the Optimization tab, you'll see a "Ready to Optimize" section with: + +- A brief description: "AI-powered Python optimization with automatic testing & benchmarking" +- A **View Documentation** button to access help and guides + +--- + +## 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: + +- **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) + + + The Tasks tab shows a badge count (e.g., "Tasks 19") indicating how many + optimization tasks you have in total. + + +--- + +## Optimization Workflow + +Once you've selected functions to optimize (via any method above), here's what happens: + + + + Selected functions are added to the optimization queue. You can see them in + the Tasks tab. + + + Watch the Tasks tab for real-time updates: - Generating optimization + candidates - Running tests to verify correctness - Benchmarking performance + + + 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 + + + Click **View Optimization** to see the full diff, then **Accept** to apply + the optimization, or **Reject** to dismiss it. + + + +--- + +## Reviewing Optimizations + +After an optimization completes, you can review it in the Tasks tab or via inline comments. + +### 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 + +### Inline Comments + +The extension also shows inline comments on the optimized function in your editor with options to: + +- **View Patch** — See the full diff of changes +- **Accept** — Apply the optimization to your code +- **Reject** — Dismiss the suggestion without changes + +--- + +## Next Steps + + + + Customize extension settings + + + Fix common issues + + diff --git a/docs/editor-plugins/vscode/index.mdx b/docs/editor-plugins/vscode/index.mdx new file mode 100644 index 000000000..e5d042dda --- /dev/null +++ b/docs/editor-plugins/vscode/index.mdx @@ -0,0 +1,235 @@ +--- +title: "VS Code Extension" +description: "Optimize Python code directly in your editor with one-click AI-powered optimizations" +icon: "code" +sidebarTitle: "Overview" +keywords: + [ + "VS Code", + "extension", + "Cursor", + "Windsurf", + "IDE", + "editor", + "CodeLens", + "optimization", + ] +--- + +# VS Code Extension + +Bring Codeflash directly into your editor. See optimization suggestions inline, track progress in real-time, and apply performance improvements without leaving your code. + + + **Works with multiple editors** — This extension is compatible with VS Code, + Cursor, Windsurf, and other VS Code-compatible editors. + + +--- + +## Requirements + +Before installing the extension, ensure you have: + +- **VS Code 1.94.0+** (or Cursor, Windsurf, or other VS Code-compatible editor) +- **Python 3.9+** installed and available in your PATH +- **Git repository** initialized for your project +- **Microsoft Python extension** installed (the Codeflash extension depends on it) + +--- + +## Installation + + + + The quickest way to install for VS Code users: + + + + Press `Ctrl+Shift+X` (Windows/Linux) or `Cmd+Shift+X` (macOS) to open the Extensions panel. + + + Type **"Codeflash"** in the search bar. + + + Click **Install** on the Codeflash extension. + + [Install from VS Code Marketplace →](https://marketplace.visualstudio.com/items?itemName=codeflash.codeflash) + + + Reload VS Code when prompted to activate the extension. + + + + + + + For Cursor, Windsurf, air-gapped environments, or when the Marketplace isn't available: + + + + Download the latest VSIX package from Open VSX: + + [Download VSIX →](https://open-vsx.org/extension/codeflash/codeflash) + + + Press `Ctrl+Shift+P` (Windows/Linux) or `Cmd+Shift+P` (macOS). + + + Type and select **"Extensions: Install from VSIX…"** + + + Choose the downloaded `codeflash-*.vsix` file. + + + Restart your editor to complete the installation. + + + + + + +--- + +## First-Time Setup + +When you first open a Python file, the extension guides you through setup: + + + + The Codeflash sidebar opens automatically, showing the setup wizard. + + + **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. + + + + 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) + + + 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 + + + + + If you see "No Python interpreter selected" or "Codeflash not installed" errors, verify that: + - You've selected the correct Python interpreter + - Codeflash is installed in that environment (`pip install codeflash`) + + + + + If Codeflash is not installed in your selected Python environment, the extension prompts you to install it. Click the **"Install codeflash Python package"** button or run: + + ```bash + pip install codeflash + ``` + + + + Authenticate with Codeflash using one of two methods: + + + + Click **"Sign in with Browser"** to authenticate via OAuth. This opens your browser where you can log in with your Codeflash account. + + + This is the easiest method — no need to copy/paste API keys! + + + + + 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 + + + Don't have an account? [Sign up free at app.codeflash.ai](https://app.codeflash.ai/login) + + + + + + + + The extension runs `codeflash init` to configure your project if needed. This creates or updates your `pyproject.toml` with Codeflash settings. + + + Once setup completes, you'll see "optimize" hints appear above your Python functions. + + + + + If you've already run `codeflash init` via CLI, the extension detects your + existing configuration and skips to the ready state. + + +### Changing the Python Interpreter + +If you need to switch to a different Python environment later: + +1. **Use VS Code's interpreter selector**: `Ctrl+Shift+P` → "Python: Select Interpreter" +2. **The extension automatically reloads** when you change interpreters + + + The extension uses the Python interpreter selected in VS Code. Make sure Codeflash is installed in the selected environment. + + +--- + +## Quick Start + +Once installed, here's the basic workflow: + +1. **Open a Python file** in your project +2. **See "optimize" hints** appear above functions +3. **Click to optimize** — the extension handles the rest +4. **Review and accept** optimizations via inline comments + +For detailed feature documentation, see [Features](/editor-plugins/vscode/features). + +--- + +## Using with CLI + +The extension works alongside the Codeflash CLI. You can: + +- **Use CLI for batch operations** — Run `codeflash --all` for large-scale optimization +- **Use extension for interactive work** — Optimize individual functions as you code +- **Mix both** — The extension picks up CLI results when you return to the editor + +For CLI documentation, see the [CLI Reference](/cli-reference). + +--- + +## Next Steps + + + + Learn about all extension features + + + Customize extension settings + + + Fix common issues + + + Command-line interface docs + + + +--- + +## Need Help? + +- **Discord** — [Join our community](https://www.codeflash.ai/discord) +- **GitHub Issues** — [Report bugs or request features](https://github.com/codeflash-ai/codeflash/issues) +- **Documentation** — [Full docs at docs.codeflash.ai](https://docs.codeflash.ai) + diff --git a/docs/editor-plugins/vscode/troubleshooting.mdx b/docs/editor-plugins/vscode/troubleshooting.mdx new file mode 100644 index 000000000..38162c0eb --- /dev/null +++ b/docs/editor-plugins/vscode/troubleshooting.mdx @@ -0,0 +1,215 @@ +--- +title: "Extension Troubleshooting" +description: "Fix common issues with the Codeflash VS Code extension" +icon: "wrench" +sidebarTitle: "Troubleshooting" +keywords: + [ + "troubleshooting", + "errors", + "issues", + "problems", + "debugging", + "logs", + ] +--- + +# Extension Troubleshooting + +Solutions for common issues with the Codeflash VS Code extension. + +--- + +## Common Issues + + + + **Symptoms:** No Codeflash icon in sidebar, no "optimize" hints appearing. + + **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 + + + + + **Symptoms:** Extension is active but no hints above functions. + + **Solutions:** + 1. **Wait for analysis** — The extension needs time to analyze your code + 2. **Check module-root** — Functions must be inside your `module-root` directory (check `pyproject.toml`) + 3. **Run codeflash init** — Ensure project is initialized: run `codeflash init` in terminal + 4. **Check function requirements** — Functions need a `return` statement and shouldn't be properties + + + + + **Symptoms:** "No Python interpreter selected", "Codeflash not installed", or wrong Python version errors. + + **Solutions:** + + 1. **Select the correct Python interpreter:** + - Press `Ctrl+Shift+P` / `Cmd+Shift+P` + - Type **"Python: Select Interpreter"** + - Choose the environment where Codeflash is installed + + 2. **Verify Codeflash is installed in that environment:** + ```bash + # Check which Python is active + which python # Linux/macOS + (Get-Command python).Source # Windows PowerShell + + # Check if Codeflash is installed + python -c "import codeflash; print(codeflash.__version__)" + ``` + + 3. **Install Codeflash if missing:** + ```bash + pip install codeflash + ``` + + + **Common mistake:** Having multiple Python environments and selecting one that doesn't have Codeflash installed. Always verify Codeflash is installed in your selected interpreter. + + + + + + **Symptoms:** "Failed to connect" or language server errors. + + **Solutions:** + 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 + + + + + **Symptoms:** Extension doesn't install from Marketplace. + + **Solution:** Install via VSIX instead: + 1. Download from [Open VSX](https://open-vsx.org/extension/codeflash/codeflash) + 2. Install using VS Code's extension installation feature + 3. Restart the editor + + + + + **Symptoms:** Optimization appears to hang or never finishes. + + **Solutions:** + 1. **Check sidebar status** — Look for error messages in the Codeflash sidebar + 2. **Check network** — Ensure stable internet connection + 3. **View logs** — Check `View → Output → Codeflash` for errors + 4. **Clear tasks** — Use the sidebar to clear completed or failed tasks + 5. **Reload extension** — Restart VS Code or reload the window + + + + + **Symptoms:** Authentication errors, "invalid API key" messages. + + **Solutions:** + 1. **Verify API key** — Check your key at [app.codeflash.ai](https://app.codeflash.ai) + 2. **Re-enter key** — The extension may prompt you to re-enter your API key + 3. **Check environment variable** — If using `CODEFLASH_API_KEY`, ensure it's set correctly + 4. **Reload extension** — Restart VS Code or reload the window + + + + +--- + +## Viewing Logs + +For detailed debugging information: + + + + Go to `View → Output` in the menu bar, or press `Ctrl+Shift+U` / `Cmd+Shift+U`. + + + Click the dropdown in the Output panel and select **"Codeflash"**. + + + Look for error messages, warnings, or stack traces that indicate the issue. + + + + + When reporting issues, include relevant log output to help diagnose the + problem. + + +--- + +## Requirements Checklist + +If you're having issues, verify these requirements: + + + + - [ ] VS Code 1.94.0+ (or Cursor/Windsurf) + - [ ] Python 3.9+ installed + - [ ] Git installed and repository initialized + - [ ] Microsoft Python extension installed + + + + + - [ ] Project has been initialized with `codeflash init` + - [ ] `pyproject.toml` exists with `[tool.codeflash]` section + - [ ] `module-root` is correctly configured + - [ ] Python files are inside the `module-root` directory + + + + + - [ ] Valid Codeflash API key + - [ ] API key entered in extension or set as environment variable + - [ ] Network access to `app.codeflash.ai` + + + + +--- + +## Still Need Help? + +If you're still experiencing issues: + +- **Discord** — [Join our community](https://www.codeflash.ai/discord) for real-time help +- **GitHub Issues** — [Report bugs](https://github.com/codeflash-ai/codeflash/issues) with detailed reproduction steps +- **Documentation** — [Full docs](https://docs.codeflash.ai) for reference + + + When reporting issues, please include: + - VS Code version + - Extension version + - Python version + - Relevant log output from the Output panel + - Steps to reproduce the issue + + +--- + +## Next Steps + + + + Back to extension overview + + + Learn about extension features + + + Customize extension settings + + + Command-line interface docs + + + From 03d4dcced8790db2ffc3558d3a7f5f8e85354e2c Mon Sep 17 00:00:00 2001 From: Mohamed Ashraf Date: Fri, 16 Jan 2026 15:10:09 +0200 Subject: [PATCH 2/3] update naming for CLI Reference to be Codeflash CLI --- docs/cli-reference.mdx | 6 +++--- docs/docs.json | 2 +- docs/editor-plugins/vscode/configuration.mdx | 2 +- docs/editor-plugins/vscode/index.mdx | 4 ++-- docs/editor-plugins/vscode/troubleshooting.mdx | 2 +- 5 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/cli-reference.mdx b/docs/cli-reference.mdx index 174ca7945..8068f57cb 100644 --- a/docs/cli-reference.mdx +++ b/docs/cli-reference.mdx @@ -1,8 +1,8 @@ --- -title: "CLI Reference" +title: "Codeflash CLI" description: "Complete command-line reference for all Codeflash commands, flags, and options" icon: "terminal" -sidebarTitle: "CLI Reference" +sidebarTitle: "Codeflash CLI" keywords: [ "CLI", @@ -15,7 +15,7 @@ keywords: ] --- -# Codeflash CLI Reference +# Codeflash Codeflash CLI This guide covers all Codeflash CLI commands with practical examples you can run directly in your terminal. diff --git a/docs/docs.json b/docs/docs.json index b469f19cb..76d1fc0ed 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -27,7 +27,7 @@ "pages": ["index"] }, { - "group": "📖 CLI Reference", + "group": "📖 Codeflash CLI", "pages": ["cli-reference"] }, { diff --git a/docs/editor-plugins/vscode/configuration.mdx b/docs/editor-plugins/vscode/configuration.mdx index 4ba552a2b..719457e3d 100644 --- a/docs/editor-plugins/vscode/configuration.mdx +++ b/docs/editor-plugins/vscode/configuration.mdx @@ -144,7 +144,7 @@ When configuration issues are detected, the extension displays clear error messa Complete pyproject.toml reference - + Command-line options diff --git a/docs/editor-plugins/vscode/index.mdx b/docs/editor-plugins/vscode/index.mdx index e5d042dda..3d1b9e152 100644 --- a/docs/editor-plugins/vscode/index.mdx +++ b/docs/editor-plugins/vscode/index.mdx @@ -204,7 +204,7 @@ The extension works alongside the Codeflash CLI. You can: - **Use extension for interactive work** — Optimize individual functions as you code - **Mix both** — The extension picks up CLI results when you return to the editor -For CLI documentation, see the [CLI Reference](/cli-reference). +For CLI documentation, see the [Codeflash CLI](/cli-reference). --- @@ -220,7 +220,7 @@ For CLI documentation, see the [CLI Reference](/cli-reference). Fix common issues - + Command-line interface docs diff --git a/docs/editor-plugins/vscode/troubleshooting.mdx b/docs/editor-plugins/vscode/troubleshooting.mdx index 38162c0eb..73fb88111 100644 --- a/docs/editor-plugins/vscode/troubleshooting.mdx +++ b/docs/editor-plugins/vscode/troubleshooting.mdx @@ -208,7 +208,7 @@ If you're still experiencing issues: Customize extension settings - + Command-line interface docs From 9871ce23af781916d39f6223c88766ad7d3db768 Mon Sep 17 00:00:00 2001 From: Mohamed Ashraf Date: Fri, 16 Jan 2026 15:20:07 +0200 Subject: [PATCH 3/3] break down cli-reference docs to multiple pages --- docs/cli-reference.mdx | 677 ------------------ docs/cli-reference/flags.mdx | 191 +++++ docs/cli-reference/index.mdx | 208 ++++++ docs/cli-reference/optimization.mdx | 172 +++++ docs/cli-reference/setup.mdx | 125 ++++ docs/cli-reference/tracing.mdx | 213 ++++++ docs/cli-reference/troubleshooting.mdx | 157 ++++ docs/docs.json | 9 +- docs/editor-plugins/vscode/configuration.mdx | 2 +- docs/editor-plugins/vscode/index.mdx | 4 +- .../editor-plugins/vscode/troubleshooting.mdx | 2 +- 11 files changed, 1078 insertions(+), 682 deletions(-) delete mode 100644 docs/cli-reference.mdx create mode 100644 docs/cli-reference/flags.mdx create mode 100644 docs/cli-reference/index.mdx create mode 100644 docs/cli-reference/optimization.mdx create mode 100644 docs/cli-reference/setup.mdx create mode 100644 docs/cli-reference/tracing.mdx create mode 100644 docs/cli-reference/troubleshooting.mdx diff --git a/docs/cli-reference.mdx b/docs/cli-reference.mdx deleted file mode 100644 index 8068f57cb..000000000 --- a/docs/cli-reference.mdx +++ /dev/null @@ -1,677 +0,0 @@ ---- -title: "Codeflash CLI" -description: "Complete command-line reference for all Codeflash commands, flags, and options" -icon: "terminal" -sidebarTitle: "Codeflash CLI" -keywords: - [ - "CLI", - "command line", - "commands", - "flags", - "options", - "reference", - "terminal", - ] ---- - -# Codeflash Codeflash CLI - -This guide covers all Codeflash CLI commands with practical examples you can run directly in your terminal. - - - **Prerequisites** - Ensure Codeflash is installed in your Python environment - and you have a configured `pyproject.toml` in your project. - - ---- - - -## Quick Start - - - - ```bash - # Activate virtual environment (if using one) - source .venv/bin/activate - - # Verify installation - codeflash --version - ``` - - - - ```powershell - # Activate virtual environment (if using one) - .venv\Scripts\activate - - # Verify installation - codeflash --version - ``` - - - - ---- - -## Common Workflows - -### 1. First-Time Setup - - - -```bash -pip install codeflash -``` - - -```bash -codeflash init -``` - - -```bash -codeflash --verify-setup -``` - - -```bash -codeflash --file src/main.py --function my_function --no-pr -``` - - - ---- - -### 2. Optimize a Workflow - - - -```bash -codeflash optimize my_script.py --arg1 value1 -``` - - -Check the generated PR or local changes for optimization suggestions. - - - ---- - -### 3. CI/CD Integration - - - -```bash -codeflash init-actions -``` - - -Review and merge the generated GitHub Actions workflow. - - -Codeflash will now optimize code in every PR automatically! - - - ---- - -## Help & Version - -```bash -# Display version -codeflash --version - -# Main help -codeflash --help - -# Subcommand help -codeflash optimize --help -codeflash init --help -``` - ---- - -## Complete Flag Reference - -### Main Command Flags - -| Flag | Type | Description | -|------|------|-------------| -| `--file` | `PATH` | Optimize only this file | -| `--function` | `NAME` | Optimize only this function (requires `--file`) | -| `--all` | `[PATH]` | Optimize all functions. Optional path to start from | -| `--replay-test` | `PATH` | Path to replay test file(s) | -| `--benchmark` | flag | Enable benchmark mode | -| `--no-pr` | flag | Don't create PR, update locally | -| `--no-gen-tests` | flag | Don't generate tests | -| `--no-draft` | flag | Skip draft PRs | -| `--worktree` | flag | Use git worktree | -| `--staging-review` | flag | Upload to staging | -| `--verbose` / `-v` | flag | Verbose debug output | -| `--verify-setup` | flag | Run setup verification | -| `--version` | flag | Show version | - -### Configuration Override Flags - -| Flag | Type | Description | -|------|------|-------------| -| `--config-file` | `PATH` | Path to pyproject.toml | -| `--module-root` | `PATH` | Python module root directory | -| `--tests-root` | `PATH` | Tests directory | -| `--benchmarks-root` | `PATH` | Benchmarks directory | - -### Optimize Subcommand Flags - -| Flag | Type | Description | -|------|------|-------------| -| `--output` | `PATH` | Trace file output path (default: `codeflash.trace`) | -| `--timeout` | `INT` | Maximum trace time in seconds | -| `--max-function-count` | `INT` | Max times to trace a function (default: 100) | -| `--config-file-path` | `PATH` | Path to pyproject.toml | -| `--trace-only` | flag | Only trace, don't optimize | - ---- - - -## Troubleshooting - - - - **Problem**: Function not found because file is outside `module-root`. - - **Solution**: Ensure your file is within the `module-root` directory specified in `pyproject.toml`. - - ```bash - # Check your module-root - grep "module-root" pyproject.toml - - # Use the correct path (e.g., if module-root is "src") - codeflash --file src/myfile.py --function my_function --no-pr - ``` - - - - **Problem**: Using `--benchmark` without specifying benchmarks directory. - - **Solution**: Either add `benchmarks-root` to `pyproject.toml` or use the flag: - - ```bash - codeflash --file src/app.py --benchmark --benchmarks-root tests/benchmarks --no-pr - ``` - - - - **Problem**: Replay test filename doesn't match expected path. - - **Solution**: Replay tests include the module path in their name. Check the actual filename: - - ```bash - # Linux/macOS - ls tests/test_*replay*.py - - # Windows - dir tests\test_*replay*.py - ``` - - - - **Problem**: PR creation fails due to missing GitHub App. - - **Solution**: Install the Codeflash GitHub App or use `--no-pr` for local optimization: - - ```bash - # Local optimization - codeflash --file src/app.py --function main --no-pr - - # Or install the GitHub App - # https://github.com/apps/codeflash-ai/installations/select_target - ``` - - - - - ---- - -## Core Commands - -### `codeflash init` - -Initialize Codeflash for your Python project. This creates the configuration in `pyproject.toml`. - - -```bash Basic -codeflash init -``` - -```bash With Formatter Override -codeflash init --override-formatter-check -``` - - - - The `init` command will guide you through an interactive setup process, - including API key configuration, module selection, and GitHub App - installation. - - ---- - -### `codeflash init-actions` - -Set up GitHub Actions workflow for continuous optimization on every pull request. - -```bash -codeflash init-actions -``` - -This command: -- Creates a workflow file in `.github/workflows/` -- Opens a PR with the workflow configuration -- Requires the Codeflash GitHub App to be installed - ---- - -### `codeflash vscode-install` - -Install the Codeflash extension for VS Code, Cursor, or Windsurf. - -```bash -codeflash vscode-install -``` - ---- - -### `codeflash --verify-setup` - -Verify your Codeflash installation by running a sample optimization. - -```bash -codeflash --verify-setup -``` - - - This command creates a temporary file, runs a sample optimization, and cleans - up afterward. It takes about 3 minutes to complete. - - ---- - -## Function Optimization - -### Optimize a Single Function - -Target a specific function in a file for optimization. - -```bash -codeflash --file --function -``` - - - - - ```bash - # Basic optimization (creates PR) - codeflash --file src/utils.py --function calculate_metrics - - # Local optimization only (no PR) - codeflash --file src/utils.py --function calculate_metrics --no-pr - - # With verbose output - codeflash --file src/utils.py --function calculate_metrics --no-pr --verbose - ``` - - - - ```powershell - # Basic optimization (creates PR) - codeflash --file src\utils.py --function calculate_metrics - - # Local optimization only (no PR) - codeflash --file src\utils.py --function calculate_metrics --no-pr - - # With verbose output - codeflash --file src\utils.py --function calculate_metrics --no-pr --verbose - ``` - - - - - - - **Important**: The file must be within your configured `module-root` - directory. Files outside `module-root` will be ignored with "Functions outside - module-root" message. - - ---- - -### Optimize All Functions - -Optimize all functions in your entire codebase or a specific directory. - -```bash -# Optimize entire codebase -codeflash --all - -# Optimize specific directory -codeflash --all src/core/ -``` - - - - - ```bash - # Optimize all (creates PRs) - codeflash --all - - # Optimize all locally (no PRs) - codeflash --all --no-pr - - # Optimize specific directory - codeflash --all src/algorithms/ --no-pr - - # Skip draft PRs in CI - codeflash --all --no-draft - ``` - - - - ```powershell - # Optimize all (creates PRs) - codeflash --all - - # Optimize all locally (no PRs) - codeflash --all --no-pr - - # Optimize specific directory - codeflash --all src\algorithms\ --no-pr - - # Skip draft PRs in CI - codeflash --all --no-draft - ``` - - - - - ---- - -## Trace & Optimize Workflows - -### `codeflash optimize` - -Trace a Python script's execution and optimize functions based on real-world usage. - -```bash -codeflash optimize [script_args] -``` - - - - - ```bash - # Basic trace and optimize - codeflash optimize app.py - - # With script arguments - codeflash optimize process.py --input data.csv --output results.json - - # Custom trace output file - codeflash optimize app.py --output custom_trace.trace - - # With timeout (30 seconds) - codeflash optimize long_running_script.py --timeout 30 - - # Limit function trace count - codeflash optimize app.py --max-function-count 50 - - # Specify config file - codeflash optimize app.py --config-file-path pyproject.toml - - # Local only (no PR) - codeflash optimize app.py --no-pr - ``` - - - - ```powershell - # Basic trace and optimize - codeflash optimize app.py - - # With script arguments - codeflash optimize process.py --input data.csv --output results.json - - # Custom trace output file - codeflash optimize app.py --output custom_trace.trace - - # With timeout (30 seconds) - codeflash optimize long_running_script.py --timeout 30 - - # Limit function trace count - codeflash optimize app.py --max-function-count 50 - - # Specify config file - codeflash optimize app.py --config-file-path pyproject.toml - - # Local only (no PR) - codeflash optimize app.py --no-pr - ``` - - - - - ---- - -### Trace with pytest - -Optimize functions called during pytest test execution. - - - - ```bash - # Trace pytest tests - codeflash optimize -m pytest tests/ - - # Trace specific test file - codeflash optimize -m pytest tests/test_core.py - - # With pytest arguments - codeflash optimize -m pytest tests/ -v --tb=short - ``` - - - - ```powershell - # Trace pytest tests - codeflash optimize -m pytest tests\ - - # Trace specific test file - codeflash optimize -m pytest tests\test_core.py - - # With pytest arguments - codeflash optimize -m pytest tests\ -v --tb=short - ``` - - - - ---- - -### Trace Only (Generate Replay Tests) - -Create trace files and replay tests without running optimization. - - - - ```bash - # Trace only - generates replay test - codeflash optimize app.py --output trace_file.trace --trace-only - - # Then optimize using the replay test - codeflash --replay-test tests/test_app_py__replay_test_0.py --no-pr - ``` - - - - ```powershell - # Trace only - generates replay test - codeflash optimize app.py --output trace_file.trace --trace-only - - # Then optimize using the replay test - codeflash --replay-test tests\test_app_py__replay_test_0.py --no-pr - ``` - - - - - - **Replay test naming**: Files are named based on the traced script path. For - `src/app.py`, the replay test will be named like - `test_srcapp_py__replay_test_0.py`. - - ---- - -## Benchmark Mode - -Optimize code based on performance benchmarks using pytest-benchmark format. - -```bash -codeflash --file --benchmark --benchmarks-root -``` - - - - - ```bash - # With benchmarks-root flag - codeflash --file src/core.py --benchmark --benchmarks-root tests/benchmarks --no-pr - - # If benchmarks-root is in pyproject.toml - codeflash --file src/core.py --benchmark --no-pr - ``` - - - - ```powershell - # With benchmarks-root flag - codeflash --file src\core.py --benchmark --benchmarks-root tests\benchmarks --no-pr - - # If benchmarks-root is in pyproject.toml - codeflash --file src\core.py --benchmark --no-pr - ``` - - - - - - - The `--benchmarks-root` directory must exist and be configured either via - `pyproject.toml` or the command-line flag. - - ---- - -## Configuration Flags - -Override configuration settings from the command line. - -| Flag | Description | -|------|-------------| -| `--config-file` | Path to `pyproject.toml` with Codeflash config | -| `--module-root` | Path to Python module to optimize | -| `--tests-root` | Path to test directory | -| `--benchmarks-root` | Path to benchmarks directory | - - - - - ```bash - # Override config file location - codeflash --file src/app.py --function main --config-file configs/pyproject.toml --no-pr - - # Override module root - codeflash --file src/app.py --function main --module-root src --no-pr - - # Override tests root - codeflash --file src/app.py --function main --tests-root tests/unit --no-pr - - # Combine multiple overrides - codeflash --file src/app.py --function main \ - --module-root src \ - --tests-root tests \ - --no-pr - ``` - - - - ```powershell - # Override config file location - codeflash --file src\app.py --function main --config-file configs\pyproject.toml --no-pr - - # Override module root - codeflash --file src\app.py --function main --module-root src --no-pr - - # Override tests root - codeflash --file src\app.py --function main --tests-root tests\unit --no-pr - ``` - - - - - ---- - -## Behavior Flags - -| Flag | Description | -|------|-------------| -| `--no-pr` | Run locally without creating a pull request | -| `--no-gen-tests` | Use only existing tests, skip test generation | -| `--no-draft` | Skip optimization for draft PRs (CI mode) | -| `--worktree` | Use git worktree for isolated optimization | -| `--staging-review` | Upload optimizations to staging for review | -| `--verbose` / `-v` | Enable verbose debug logging | - - -```bash -# Local optimization only -codeflash --file src/app.py --function main --no-pr - -# Use only existing tests -codeflash --file src/app.py --function main --no-gen-tests --no-pr - -# Enable verbose logging -codeflash --file src/app.py --function main --verbose --no-pr - -# Use worktree for isolation -codeflash --file src/app.py --function main --worktree --no-pr - -# Upload to staging -codeflash --all --staging-review --no-pr -``` - - - ---- - -## Next Steps - - - - Learn how to optimize individual functions - - - Optimize entire workflows with tracing - - - Set up continuous optimization - - - Advanced configuration options - - - diff --git a/docs/cli-reference/flags.mdx b/docs/cli-reference/flags.mdx new file mode 100644 index 000000000..ad9fc5f31 --- /dev/null +++ b/docs/cli-reference/flags.mdx @@ -0,0 +1,191 @@ +--- +title: "Flags Reference" +description: "Complete reference for all Codeflash CLI flags and options" +icon: "list" +sidebarTitle: "Flags Reference" +keywords: ["flags", "options", "arguments", "command line"] +--- + +# Flags Reference + +Complete reference for all Codeflash CLI flags and command-line options. + +--- + +## Main Command Flags + +| Flag | Type | Description | +|------|------|-------------| +| `--file` | `PATH` | Optimize only this file | +| `--function` | `NAME` | Optimize only this function (requires `--file`) | +| `--all` | `[PATH]` | Optimize all functions. Optional path to start from | +| `--replay-test` | `PATH` | Path to replay test file(s) | +| `--benchmark` | flag | Enable benchmark mode | +| `--no-pr` | flag | Don't create PR, update locally | +| `--no-gen-tests` | flag | Don't generate tests | +| `--no-draft` | flag | Skip draft PRs | +| `--worktree` | flag | Use git worktree | +| `--staging-review` | flag | Upload to staging | +| `--verbose` / `-v` | flag | Verbose debug output | +| `--verify-setup` | flag | Run setup verification | +| `--version` | flag | Show version | + +--- + +## Configuration Override Flags + +Override settings from `pyproject.toml` via command line. + +| Flag | Type | Description | +|------|------|-------------| +| `--config-file` | `PATH` | Path to pyproject.toml | +| `--module-root` | `PATH` | Python module root directory | +| `--tests-root` | `PATH` | Tests directory | +| `--benchmarks-root` | `PATH` | Benchmarks directory | + + + + + ```bash + # Override config file location + codeflash --file src/app.py --function main --config-file configs/pyproject.toml --no-pr + + # Override module root + codeflash --file src/app.py --function main --module-root src --no-pr + + # Override tests root + codeflash --file src/app.py --function main --tests-root tests/unit --no-pr + + # Combine multiple overrides + codeflash --file src/app.py --function main \ + --module-root src \ + --tests-root tests \ + --no-pr + ``` + + + ```powershell + # Override config file location + codeflash --file src\app.py --function main --config-file configs\pyproject.toml --no-pr + + # Override module root + codeflash --file src\app.py --function main --module-root src --no-pr + + # Override tests root + codeflash --file src\app.py --function main --tests-root tests\unit --no-pr + ``` + + + + +--- + +## Optimize Subcommand Flags + +Flags specific to the `codeflash optimize` command. + +| Flag | Type | Description | +|------|------|-------------| +| `--output` | `PATH` | Trace file output path (default: `codeflash.trace`) | +| `--timeout` | `INT` | Maximum trace time in seconds | +| `--max-function-count` | `INT` | Max times to trace a function (default: 100) | +| `--config-file-path` | `PATH` | Path to pyproject.toml | +| `--trace-only` | flag | Only trace, don't optimize | + + + The `--output` flag specifies where to save the trace file. If not specified, it defaults to `codeflash.trace` in the current directory. + + +--- + +## Behavior Flags + +Control how Codeflash behaves during optimization. + +| Flag | Description | +|------|-------------| +| `--no-pr` | Run locally without creating a pull request | +| `--no-gen-tests` | Use only existing tests, skip test generation | +| `--no-draft` | Skip optimization for draft PRs (CI mode) | +| `--worktree` | Use git worktree for isolated optimization | +| `--staging-review` | Upload optimizations to staging for review | +| `--verbose` / `-v` | Enable verbose debug logging | + + +```bash +# Local optimization only +codeflash --file src/app.py --function main --no-pr + +# Use only existing tests +codeflash --file src/app.py --function main --no-gen-tests --no-pr + +# Enable verbose logging +codeflash --file src/app.py --function main --verbose --no-pr + +# Use worktree for isolation +codeflash --file src/app.py --function main --worktree --no-pr + +# Upload to staging +codeflash --all --staging-review --no-pr +``` + + +--- + +## Flag Combinations + +Common flag combinations for different use cases: + +### Local Development + +```bash +# Optimize locally with verbose output +codeflash --file src/app.py --function main --no-pr --verbose +``` + +### CI/CD Pipeline + +```bash +# Skip draft PRs and use existing tests only +codeflash --all --no-draft --no-gen-tests +``` + +### Debugging + +```bash +# Trace only with custom output and timeout +codeflash optimize app.py --trace-only --output debug.trace --timeout 60 +``` + +### Custom Configuration + +```bash +# Override multiple config settings +codeflash --file src/app.py --function main \ + --module-root src \ + --tests-root tests/unit \ + --benchmarks-root tests/benchmarks \ + --no-pr +``` + +--- + +## Next Steps + + + + Learn how to use optimization commands + + + Fix common issues + + + diff --git a/docs/cli-reference/index.mdx b/docs/cli-reference/index.mdx new file mode 100644 index 000000000..f91fb2e1b --- /dev/null +++ b/docs/cli-reference/index.mdx @@ -0,0 +1,208 @@ +--- +title: "CLI Reference" +description: "Complete command-line reference for Codeflash CLI commands, flags, and options" +icon: "terminal" +sidebarTitle: "Overview" +keywords: + [ + "CLI", + "command line", + "commands", + "flags", + "options", + "reference", + "terminal", + ] +--- + +# Codeflash CLI Reference + +Complete command-line reference for all Codeflash commands, flags, and options with practical examples you can run directly in your terminal. + + + **Prerequisites** - Ensure Codeflash is installed in your Python environment + and you have a configured `pyproject.toml` in your project. + + +--- + +## Quick Start + + + + ```bash + # Activate virtual environment (if using one) + source .venv/bin/activate + + # Verify installation + codeflash --version + ``` + + + ```powershell + # Activate virtual environment (if using one) + .venv\Scripts\activate + + # Verify installation + codeflash --version + ``` + + + +--- + +## Common Workflows + +### 1. First-Time Setup + + + + ```bash + pip install codeflash + ``` + + + ```bash + codeflash init + ``` + + + ```bash + codeflash --verify-setup + ``` + + + ```bash + codeflash --file src/main.py --function my_function --no-pr + ``` + + + +--- + +### 2. Optimize a Workflow + + + + ```bash + codeflash optimize my_script.py --arg1 value1 + ``` + + + Check the generated PR or local changes for optimization suggestions. + + + +--- + +### 3. CI/CD Integration + + + + ```bash + codeflash init-actions + ``` + + + Review and merge the generated GitHub Actions workflow. + + + Codeflash will now optimize code in every PR automatically! + + + +--- + +## Help & Version + +```bash +# Display version +codeflash --version + +# Main help +codeflash --help + +# Subcommand help +codeflash optimize --help +codeflash init --help +``` + +--- + +## Documentation Structure + +This CLI reference is organized into the following sections: + + + + Initialize projects, set up GitHub Actions, and verify installation + + + Optimize single functions or entire codebases + + + Trace script execution and optimize based on real usage + + + Complete reference for all command-line flags + + + Solutions for common CLI issues + + + +--- + +## Next Steps + + + + Learn how to optimize individual functions + + + Optimize entire workflows with tracing + + + Set up continuous optimization + + + Advanced configuration options + + + diff --git a/docs/cli-reference/optimization.mdx b/docs/cli-reference/optimization.mdx new file mode 100644 index 000000000..34284e4b0 --- /dev/null +++ b/docs/cli-reference/optimization.mdx @@ -0,0 +1,172 @@ +--- +title: "Optimization Commands" +description: "Optimize single functions or entire codebases with Codeflash CLI" +icon: "bullseye" +sidebarTitle: "Optimization Commands" +keywords: ["optimization", "function", "file", "all", "commands"] +--- + +# Optimization Commands + +Commands for optimizing individual functions or entire codebases. + +--- + +## Optimize a Single Function + +Target a specific function in a file for optimization. + +```bash +codeflash --file --function +``` + + + + + ```bash + # Basic optimization (creates PR) + codeflash --file src/utils.py --function calculate_metrics + + # Local optimization only (no PR) + codeflash --file src/utils.py --function calculate_metrics --no-pr + + # With verbose output + codeflash --file src/utils.py --function calculate_metrics --no-pr --verbose + ``` + + + ```powershell + # Basic optimization (creates PR) + codeflash --file src\utils.py --function calculate_metrics + + # Local optimization only (no PR) + codeflash --file src\utils.py --function calculate_metrics --no-pr + + # With verbose output + codeflash --file src\utils.py --function calculate_metrics --no-pr --verbose + ``` + + + + + + **Important**: The file must be within your configured `module-root` + directory. Files outside `module-root` will be ignored with "Functions outside + module-root" message. + + +--- + +## Optimize All Functions + +Optimize all functions in your entire codebase or a specific directory. + +```bash +# Optimize entire codebase +codeflash --all + +# Optimize specific directory +codeflash --all src/core/ +``` + + + + + ```bash + # Optimize all (creates PRs) + codeflash --all + + # Optimize all locally (no PRs) + codeflash --all --no-pr + + # Optimize specific directory + codeflash --all src/algorithms/ --no-pr + + # Skip draft PRs in CI + codeflash --all --no-draft + ``` + + + ```powershell + # Optimize all (creates PRs) + codeflash --all + + # Optimize all locally (no PRs) + codeflash --all --no-pr + + # Optimize specific directory + codeflash --all src\algorithms\ --no-pr + + # Skip draft PRs in CI + codeflash --all --no-draft + ``` + + + + + + When using `--all`, Codeflash will: + - Discover all optimizable functions in your codebase + - Create separate PRs for each function (or update locally with `--no-pr`) + - Process functions in batches to avoid overwhelming your repository + + +--- + +## Benchmark Mode + +Optimize code based on performance benchmarks using pytest-benchmark format. + +```bash +codeflash --file --benchmark --benchmarks-root +``` + + + + + ```bash + # With benchmarks-root flag + codeflash --file src/core.py --benchmark --benchmarks-root tests/benchmarks --no-pr + + # If benchmarks-root is in pyproject.toml + codeflash --file src/core.py --benchmark --no-pr + ``` + + + ```powershell + # With benchmarks-root flag + codeflash --file src\core.py --benchmark --benchmarks-root tests\benchmarks --no-pr + + # If benchmarks-root is in pyproject.toml + codeflash --file src\core.py --benchmark --no-pr + ``` + + + + + + The `--benchmarks-root` directory must exist and be configured either via + `pyproject.toml` or the command-line flag. + + +--- + +## Next Steps + + + + Learn about trace-based optimization + + + Complete flag reference + + + diff --git a/docs/cli-reference/setup.mdx b/docs/cli-reference/setup.mdx new file mode 100644 index 000000000..c9a3be441 --- /dev/null +++ b/docs/cli-reference/setup.mdx @@ -0,0 +1,125 @@ +--- +title: "Setup Commands" +description: "Initialize projects, set up GitHub Actions, and verify Codeflash installation" +icon: "wrench" +sidebarTitle: "Setup Commands" +keywords: ["setup", "init", "installation", "github actions", "verify"] +--- + +# Setup Commands + +Commands for initializing Codeflash in your project, setting up continuous optimization, and verifying your installation. + +--- + +## `codeflash init` + +Initialize Codeflash for your Python project. This creates the configuration in `pyproject.toml`. + + +```bash Basic +codeflash init +``` + +```bash With Formatter Override +codeflash init --override-formatter-check +``` + + + + The `init` command will guide you through an interactive setup process, + including API key configuration, module selection, and GitHub App + installation. + + +**What it does:** + +- Prompts for your Python module directory (`module-root`) +- Prompts for your test directory (`tests-root`) +- Configures code formatter preferences +- Sets up telemetry preferences +- Optionally installs the Codeflash VS Code extension +- Optionally sets up GitHub Actions workflow + +--- + +## `codeflash init-actions` + +Set up GitHub Actions workflow for continuous optimization on every pull request. + +```bash +codeflash init-actions +``` + +**What it does:** + +- Creates a workflow file in `.github/workflows/` +- Opens a PR with the workflow configuration +- Requires the Codeflash GitHub App to be installed + + + This command requires the Codeflash GitHub App to be installed on your repository. If you haven't installed it, you'll be prompted with a link to do so. + + +--- + +## `codeflash vscode-install` + +Install the Codeflash extension for VS Code, Cursor, or Windsurf. + +```bash +codeflash vscode-install +``` + +**What it does:** + +- Detects which editor you're using (VS Code, Cursor, or Windsurf) +- Downloads and installs the appropriate extension +- Works with both Marketplace and Open VSX sources + + + This command is also run automatically during `codeflash init` if you choose to install the extension. + + +--- + +## `codeflash --verify-setup` + +Verify your Codeflash installation by running a sample optimization. + +```bash +codeflash --verify-setup +``` + +**What it does:** + +- Creates a temporary demo file +- Runs a sample optimization +- Verifies all components are working correctly +- Cleans up the demo file afterward + + + This command takes about 3 minutes to complete. It's a great way to ensure everything is set up correctly before optimizing your actual code. + + +--- + +## Next Steps + + + + Learn how to optimize functions + + + Complete flag reference + + + diff --git a/docs/cli-reference/tracing.mdx b/docs/cli-reference/tracing.mdx new file mode 100644 index 000000000..c2394a6d5 --- /dev/null +++ b/docs/cli-reference/tracing.mdx @@ -0,0 +1,213 @@ +--- +title: "Tracing & Workflows" +description: "Trace script execution and optimize functions based on real-world usage" +icon: "route" +sidebarTitle: "Tracing & Workflows" +keywords: ["tracing", "optimize", "workflow", "replay test", "pytest"] +--- + +# Tracing & Workflows + +Trace Python script execution and optimize functions based on real-world usage patterns. + +--- + +## `codeflash optimize` + +Trace a Python script's execution and optimize functions based on real-world usage. + +```bash +codeflash optimize [script_args] +``` + + + + + ```bash + # Basic trace and optimize + codeflash optimize app.py + + # With script arguments + codeflash optimize process.py --input data.csv --output results.json + + # Custom trace output file + codeflash optimize app.py --output custom_trace.trace + + # With timeout (30 seconds) + codeflash optimize long_running_script.py --timeout 30 + + # Limit function trace count + codeflash optimize app.py --max-function-count 50 + + # Specify config file + codeflash optimize app.py --config-file-path pyproject.toml + + # Local only (no PR) + codeflash optimize app.py --no-pr + ``` + + + ```powershell + # Basic trace and optimize + codeflash optimize app.py + + # With script arguments + codeflash optimize process.py --input data.csv --output results.json + + # Custom trace output file + codeflash optimize app.py --output custom_trace.trace + + # With timeout (30 seconds) + codeflash optimize long_running_script.py --timeout 30 + + # Limit function trace count + codeflash optimize app.py --max-function-count 50 + + # Specify config file + codeflash optimize app.py --config-file-path pyproject.toml + + # Local only (no PR) + codeflash optimize app.py --no-pr + ``` + + + + +**How it works:** + +1. Runs your script with the provided arguments +2. Traces all function calls during execution +3. Identifies which functions are called and how often +4. Generates replay tests based on actual usage +5. Optimizes the traced functions + +--- + +## Trace with pytest + +Optimize functions called during pytest test execution. + + + + ```bash + # Trace pytest tests + codeflash optimize -m pytest tests/ + + # Trace specific test file + codeflash optimize -m pytest tests/test_core.py + + # With pytest arguments + codeflash optimize -m pytest tests/ -v --tb=short + ``` + + + ```powershell + # Trace pytest tests + codeflash optimize -m pytest tests\ + + # Trace specific test file + codeflash optimize -m pytest tests\test_core.py + + # With pytest arguments + codeflash optimize -m pytest tests\ -v --tb=short + ``` + + + + + Tracing pytest tests is great for optimizing functions that are heavily used in your test suite, ensuring optimizations work correctly with your existing tests. + + +--- + +## Trace Only (Generate Replay Tests) + +Create trace files and replay tests without running optimization. + + + + ```bash + # Trace only - generates replay test + codeflash optimize app.py --output trace_file.trace --trace-only + + # Then optimize using the replay test + codeflash --replay-test tests/test_app_py__replay_test_0.py --no-pr + ``` + + + ```powershell + # Trace only - generates replay test + codeflash optimize app.py --output trace_file.trace --trace-only + + # Then optimize using the replay test + codeflash --replay-test tests\test_app_py__replay_test_0.py --no-pr + ``` + + + + + **Replay test naming**: Files are named based on the traced script path. For + `src/app.py`, the replay test will be named like + `test_srcapp_py__replay_test_0.py`. + + +**Use cases for trace-only:** + +- Generate replay tests for later optimization +- Debug tracing issues without running full optimization +- Create reusable test cases from script execution + +--- + +## Replay Test Optimization + +Optimize functions using previously generated replay tests. + +```bash +codeflash --replay-test +``` + + + + + ```bash + # Optimize using replay test + codeflash --replay-test tests/test_app_py__replay_test_0.py --no-pr + + # Multiple replay tests + codeflash --replay-test tests/test_*.py --no-pr + ``` + + + ```powershell + # Optimize using replay test + codeflash --replay-test tests\test_app_py__replay_test_0.py --no-pr + + # Multiple replay tests (use Get-ChildItem for globbing) + codeflash --replay-test (Get-ChildItem tests\test_*.py) --no-pr + ``` + + + + +--- + +## Next Steps + + + + Learn about function optimization + + + Complete flag reference + + + diff --git a/docs/cli-reference/troubleshooting.mdx b/docs/cli-reference/troubleshooting.mdx new file mode 100644 index 000000000..7c8134242 --- /dev/null +++ b/docs/cli-reference/troubleshooting.mdx @@ -0,0 +1,157 @@ +--- +title: "CLI Troubleshooting" +description: "Solutions for common Codeflash CLI issues and errors" +icon: "wrench" +sidebarTitle: "Troubleshooting" +keywords: ["troubleshooting", "errors", "issues", "problems", "debugging"] +--- + +# CLI Troubleshooting + +Solutions for common issues when using the Codeflash CLI. + +--- + +## Common Issues + + + + **Problem**: Function not found because file is outside `module-root`. + + **Solution**: Ensure your file is within the `module-root` directory specified in `pyproject.toml`. + + ```bash + # Check your module-root + grep "module-root" pyproject.toml + + # Use the correct path (e.g., if module-root is "src") + codeflash --file src/myfile.py --function my_function --no-pr + ``` + + + + **Problem**: Using `--benchmark` without specifying benchmarks directory. + + **Solution**: Either add `benchmarks-root` to `pyproject.toml` or use the flag: + + ```bash + codeflash --file src/app.py --benchmark --benchmarks-root tests/benchmarks --no-pr + ``` + + + + **Problem**: Replay test filename doesn't match expected path. + + **Solution**: Replay tests include the module path in their name. Check the actual filename: + + ```bash + # Linux/macOS + ls tests/test_*replay*.py + + # Windows + dir tests\test_*replay*.py + ``` + + + Replay test files are named based on the traced script path. For `src/app.py`, + the replay test will be named like `test_srcapp_py__replay_test_0.py`. + + + + + **Problem**: PR creation fails due to missing GitHub App. + + **Solution**: Install the Codeflash GitHub App or use `--no-pr` for local optimization: + + ```bash + # Local optimization + codeflash --file src/app.py --function main --no-pr + + # Or install the GitHub App + # https://github.com/apps/codeflash-ai/installations/select_target + ``` + + + + **Problem**: Codeflash can't find your Python modules. + + **Solution**: + + 1. Verify `module-root` is correctly set in `pyproject.toml` + 2. Ensure you're running from the project root + 3. Check that your Python environment has all dependencies installed + + ```bash + # Verify module-root + cat pyproject.toml | grep module-root + + # Check Python path + python -c "import sys; print(sys.path)" + ``` + + + + **Problem**: Codeflash can't generate tests for your function. + + **Solution**: + + 1. Ensure your function has a return statement + 2. Check that the function is not a property or class method with special decorators + 3. Use `--no-gen-tests` to skip test generation and use existing tests only + + ```bash + codeflash --file src/app.py --function main --no-gen-tests --no-pr + ``` + + + + **Problem**: Optimization takes too long or times out. + + **Solution**: + + 1. Use `--verbose` to see what's happening + 2. For tracing, use `--timeout` to limit trace duration + 3. For large functions, consider breaking them down + + ```bash + # Limit trace time + codeflash optimize app.py --timeout 30 + + # See detailed progress + codeflash --file src/app.py --function main --verbose --no-pr + ``` + + + +--- + +## Getting Help + +If you're still experiencing issues: + +1. **Check the logs**: Use `--verbose` flag to see detailed output +2. **Verify setup**: Run `codeflash --verify-setup` to check your installation +3. **Check configuration**: Ensure `pyproject.toml` is correctly configured +4. **View help**: Run `codeflash --help` or `codeflash --help` + +--- + +## Next Steps + + + + Review setup and initialization + + + Complete flag reference + + + diff --git a/docs/docs.json b/docs/docs.json index 76d1fc0ed..a36fc82dc 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -28,7 +28,14 @@ }, { "group": "📖 Codeflash CLI", - "pages": ["cli-reference"] + "pages": [ + "cli-reference/index", + "cli-reference/setup", + "cli-reference/optimization", + "cli-reference/tracing", + "cli-reference/flags", + "cli-reference/troubleshooting" + ] }, { "group": "🛠 IDE Extension", diff --git a/docs/editor-plugins/vscode/configuration.mdx b/docs/editor-plugins/vscode/configuration.mdx index 719457e3d..76a2b1178 100644 --- a/docs/editor-plugins/vscode/configuration.mdx +++ b/docs/editor-plugins/vscode/configuration.mdx @@ -144,7 +144,7 @@ When configuration issues are detected, the extension displays clear error messa Complete pyproject.toml reference - + Command-line options diff --git a/docs/editor-plugins/vscode/index.mdx b/docs/editor-plugins/vscode/index.mdx index 3d1b9e152..f598fe594 100644 --- a/docs/editor-plugins/vscode/index.mdx +++ b/docs/editor-plugins/vscode/index.mdx @@ -204,7 +204,7 @@ The extension works alongside the Codeflash CLI. You can: - **Use extension for interactive work** — Optimize individual functions as you code - **Mix both** — The extension picks up CLI results when you return to the editor -For CLI documentation, see the [Codeflash CLI](/cli-reference). +For CLI documentation, see the [Codeflash CLI](/cli-reference/index). --- @@ -220,7 +220,7 @@ For CLI documentation, see the [Codeflash CLI](/cli-reference). Fix common issues - + Command-line interface docs diff --git a/docs/editor-plugins/vscode/troubleshooting.mdx b/docs/editor-plugins/vscode/troubleshooting.mdx index 73fb88111..7af38446c 100644 --- a/docs/editor-plugins/vscode/troubleshooting.mdx +++ b/docs/editor-plugins/vscode/troubleshooting.mdx @@ -208,7 +208,7 @@ If you're still experiencing issues: Customize extension settings - + Command-line interface docs