mirror of
https://github.com/codeflash-ai/codeflash.git
synced 2026-05-04 18:25:17 +00:00
add vsc extension docs
This commit is contained in:
Mohamed Ashraf
parent
e4b9c741bb
commit
e55a19154e
6 changed files with 832 additions and 50 deletions
|
|
@ -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",
|
||||
|
|
|
|||
|
|
@ -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:<br />
|
||||
[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:<br />
|
||||
[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.
|
||||
|
||||
150
docs/editor-plugins/vscode/configuration.mdx
Normal file
150
docs/editor-plugins/vscode/configuration.mdx
Normal file
|
|
@ -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.
|
||||
|
||||
<Steps>
|
||||
<Step title="Open Codeflash Sidebar">
|
||||
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.
|
||||
</Step>
|
||||
<Step title="Open Kebab Menu">
|
||||
In the Optimization tab, look for the three vertical dots icon (`⋮`) next to the **Optimize** button. Click it to open the menu.
|
||||
</Step>
|
||||
<Step title="Select Project Config">
|
||||
From the dropdown menu, click **"Project Config"** to open the configuration interface.
|
||||
</Step>
|
||||
<Step title="Update Settings">
|
||||
Use the configuration interface to modify your `pyproject.toml` settings. Changes are saved directly to your project's configuration file.
|
||||
</Step>
|
||||
</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.
|
||||
</Info>
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
|
||||
<Warning>
|
||||
**Format carefully** — Incorrect TOML syntax will cause the extension to show configuration errors. The extension's configuration page helps prevent syntax errors.
|
||||
</Warning>
|
||||
|
||||
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
|
||||
|
||||
<Info>
|
||||
The extension **automatically reloads** when you change the Python interpreter. Make sure Codeflash is installed in the selected environment.
|
||||
</Info>
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Features" icon="sparkles" href="/editor-plugins/vscode/features">
|
||||
Learn about extension features
|
||||
</Card>
|
||||
<Card title="Troubleshooting" icon="wrench" href="/editor-plugins/vscode/troubleshooting">
|
||||
Fix common issues
|
||||
</Card>
|
||||
<Card title="Project Configuration" icon="file-code" href="/configuration">
|
||||
Complete pyproject.toml reference
|
||||
</Card>
|
||||
<Card title="CLI Reference" icon="terminal" href="/cli-reference">
|
||||
Command-line options
|
||||
</Card>
|
||||
</CardGroup>
|
||||
225
docs/editor-plugins/vscode/features.mdx
Normal file
225
docs/editor-plugins/vscode/features.mdx
Normal file
|
|
@ -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
|
||||
|
||||
<Tip>
|
||||
Look for CodeLens hints above functions in your editor for quick optimization
|
||||
access.
|
||||
</Tip>
|
||||
|
||||
<Warning>
|
||||
Functions must be inside your configured `module-root` directory to show
|
||||
optimization hints. Check your `pyproject.toml` if hints aren't appearing.
|
||||
</Warning>
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
|
||||
<Info>
|
||||
**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.
|
||||
</Info>
|
||||
|
||||
### 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
|
||||
|
||||
<Warning>
|
||||
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.
|
||||
</Warning>
|
||||
|
||||
#### 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
|
||||
|
||||
<Tip>
|
||||
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.
|
||||
</Tip>
|
||||
|
||||
### 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)
|
||||
|
||||
<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.
|
||||
|
||||
### 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
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card
|
||||
title="Configuration"
|
||||
icon="gear"
|
||||
href="/editor-plugins/vscode/configuration"
|
||||
>
|
||||
Customize extension settings
|
||||
</Card>
|
||||
<Card
|
||||
title="Troubleshooting"
|
||||
icon="wrench"
|
||||
href="/editor-plugins/vscode/troubleshooting"
|
||||
>
|
||||
Fix common issues
|
||||
</Card>
|
||||
</CardGroup>
|
||||
235
docs/editor-plugins/vscode/index.mdx
Normal file
235
docs/editor-plugins/vscode/index.mdx
Normal file
|
|
@ -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.
|
||||
|
||||
<Info>
|
||||
**Works with multiple editors** — This extension is compatible with VS Code,
|
||||
Cursor, Windsurf, and other VS Code-compatible editors.
|
||||
</Info>
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
|
||||
<Tabs>
|
||||
<Tab title="VS Code Marketplace">
|
||||
The quickest way to install for VS Code users:
|
||||
|
||||
<Steps>
|
||||
<Step title="Open Extensions Panel">
|
||||
Press `Ctrl+Shift+X` (Windows/Linux) or `Cmd+Shift+X` (macOS) to open the Extensions panel.
|
||||
</Step>
|
||||
<Step title="Search for Codeflash">
|
||||
Type **"Codeflash"** in the search bar.
|
||||
</Step>
|
||||
<Step title="Install">
|
||||
Click **Install** on the Codeflash extension.
|
||||
|
||||
[Install from VS Code Marketplace →](https://marketplace.visualstudio.com/items?itemName=codeflash.codeflash)
|
||||
</Step>
|
||||
<Step title="Reload">
|
||||
Reload VS Code when prompted to activate the extension.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="VSIX (Cursor/Offline)">
|
||||
For Cursor, Windsurf, air-gapped environments, or when the Marketplace isn't available:
|
||||
|
||||
<Steps>
|
||||
<Step title="Download VSIX">
|
||||
Download the latest VSIX package from Open VSX:
|
||||
|
||||
[Download VSIX →](https://open-vsx.org/extension/codeflash/codeflash)
|
||||
</Step>
|
||||
<Step title="Open Command Palette">
|
||||
Press `Ctrl+Shift+P` (Windows/Linux) or `Cmd+Shift+P` (macOS).
|
||||
</Step>
|
||||
<Step title="Install from VSIX">
|
||||
Type and select **"Extensions: Install from VSIX…"**
|
||||
</Step>
|
||||
<Step title="Select File">
|
||||
Choose the downloaded `codeflash-*.vsix` file.
|
||||
</Step>
|
||||
<Step title="Restart Editor">
|
||||
Restart your editor to complete the installation.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
---
|
||||
|
||||
## First-Time Setup
|
||||
|
||||
When you first open a Python file, the extension guides you through setup:
|
||||
|
||||
<Steps>
|
||||
<Step title="Extension Activates">
|
||||
The Codeflash sidebar opens automatically, showing the setup wizard.
|
||||
</Step>
|
||||
<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>
|
||||
|
||||
<Warning>
|
||||
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`)
|
||||
</Warning>
|
||||
|
||||
</Step>
|
||||
<Step title="Install Codeflash Package">
|
||||
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
|
||||
```
|
||||
|
||||
</Step>
|
||||
<Step title="Authentication">
|
||||
Authenticate with Codeflash using one of two methods:
|
||||
|
||||
<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.
|
||||
|
||||
<Tip>
|
||||
This is the easiest method — no need to copy/paste API keys!
|
||||
</Tip>
|
||||
|
||||
</Tab>
|
||||
<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
|
||||
|
||||
<Tip>
|
||||
Don't have an account? [Sign up free at app.codeflash.ai](https://app.codeflash.ai/login)
|
||||
</Tip>
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
</Step>
|
||||
<Step title="Project Initialization">
|
||||
The extension runs `codeflash init` to configure your project if needed. This creates or updates your `pyproject.toml` with Codeflash settings.
|
||||
</Step>
|
||||
<Step title="Ready to Optimize">
|
||||
Once setup completes, you'll see "optimize" hints appear above your Python functions.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Note>
|
||||
If you've already run `codeflash init` via CLI, the extension detects your
|
||||
existing configuration and skips to the ready state.
|
||||
</Note>
|
||||
|
||||
### 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
|
||||
|
||||
<Info>
|
||||
The extension uses the Python interpreter selected in VS Code. Make sure Codeflash is installed in the selected environment.
|
||||
</Info>
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Features" icon="sparkles" href="/editor-plugins/vscode/features">
|
||||
Learn about all extension features
|
||||
</Card>
|
||||
<Card title="Configuration" icon="gear" href="/editor-plugins/vscode/configuration">
|
||||
Customize extension settings
|
||||
</Card>
|
||||
<Card title="Troubleshooting" icon="wrench" href="/editor-plugins/vscode/troubleshooting">
|
||||
Fix common issues
|
||||
</Card>
|
||||
<Card title="CLI Reference" icon="terminal" href="/cli-reference">
|
||||
Command-line interface docs
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
---
|
||||
|
||||
## 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)
|
||||
|
||||
215
docs/editor-plugins/vscode/troubleshooting.mdx
Normal file
215
docs/editor-plugins/vscode/troubleshooting.mdx
Normal file
|
|
@ -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
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Extension not activating">
|
||||
**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
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="No 'optimize' hints appearing">
|
||||
**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
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Python environment issues">
|
||||
**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
|
||||
```
|
||||
|
||||
<Warning>
|
||||
**Common mistake:** Having multiple Python environments and selecting one that doesn't have Codeflash installed. Always verify Codeflash is installed in your selected interpreter.
|
||||
</Warning>
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Connection or LSP errors">
|
||||
**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
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Using Cursor or custom VS Code build">
|
||||
**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
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Optimization stuck or not completing">
|
||||
**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
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="API key issues">
|
||||
**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
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
---
|
||||
|
||||
## Viewing Logs
|
||||
|
||||
For detailed debugging information:
|
||||
|
||||
<Steps>
|
||||
<Step title="Open Output Panel">
|
||||
Go to `View → Output` in the menu bar, or press `Ctrl+Shift+U` / `Cmd+Shift+U`.
|
||||
</Step>
|
||||
<Step title="Select Codeflash">
|
||||
Click the dropdown in the Output panel and select **"Codeflash"**.
|
||||
</Step>
|
||||
<Step title="Review Logs">
|
||||
Look for error messages, warnings, or stack traces that indicate the issue.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Tip>
|
||||
When reporting issues, include relevant log output to help diagnose the
|
||||
problem.
|
||||
</Tip>
|
||||
|
||||
---
|
||||
|
||||
## Requirements Checklist
|
||||
|
||||
If you're having issues, verify these requirements:
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="System Requirements">
|
||||
- [ ] VS Code 1.94.0+ (or Cursor/Windsurf)
|
||||
- [ ] Python 3.9+ installed
|
||||
- [ ] Git installed and repository initialized
|
||||
- [ ] Microsoft Python extension installed
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Project Requirements">
|
||||
- [ ] 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
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Authentication">
|
||||
- [ ] Valid Codeflash API key
|
||||
- [ ] API key entered in extension or set as environment variable
|
||||
- [ ] Network access to `app.codeflash.ai`
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
|
||||
<Info>
|
||||
When reporting issues, please include:
|
||||
- VS Code version
|
||||
- Extension version
|
||||
- Python version
|
||||
- Relevant log output from the Output panel
|
||||
- Steps to reproduce the issue
|
||||
</Info>
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Overview" icon="house" href="/editor-plugins/vscode">
|
||||
Back to extension overview
|
||||
</Card>
|
||||
<Card title="Features" icon="sparkles" href="/editor-plugins/vscode/features">
|
||||
Learn about extension features
|
||||
</Card>
|
||||
<Card title="Configuration" icon="gear" href="/editor-plugins/vscode/configuration">
|
||||
Customize extension settings
|
||||
</Card>
|
||||
<Card title="CLI Reference" icon="terminal" href="/cli-reference">
|
||||
Command-line interface docs
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
Loading…
Reference in a new issue