codeflash-ai/codeflash
1
0
Fork 0
Code Issues 18 Pull requests 33 Projects Releases Packages Wiki Activity Actions 5.0k

Merge branch 'main' into multi-language

Browse source
This commit is contained in:
Sarthak Agarwal 2026-01-21 21:52:10 +05:30 committed by GitHub
commit e823d06ad3
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
26 changed files with 2062 additions and 820 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
.gitignore vendored
View file

@ -258,6 +258,5 @@ WARP.MD
.mcp.json
.tessl/
CLAUDE.md
tessl.json
*/node_modules/*

77
AGENTS.md
View file

@ -1,77 +0,0 @@
# CodeFlash AI Agent Instructions
## Project Overview
CodeFlash is an AI-powered Python code optimizer that automatically improves code performance while maintaining correctness.
## Architecture
```
codeflash/
├── main.py # CLI entry point
├── cli_cmds/ # Command handling, console output (Rich)
├── discovery/ # Find optimizable functions
├── context/ # Extract code dependencies and imports
├── optimization/ # Generate optimized code via AI
├── verification/ # Run deterministic tests (pytest plugin)
├── benchmarking/ # Performance measurement
├── github/ # PR creation
├── api/ # AI service communication
├── code_utils/ # Code parsing, git utilities
├── models/ # Pydantic models and types
├── tracing/ # Function call tracing
├── lsp/ # IDE integration
├── telemetry/ # Sentry, PostHog
└── either.py # Functional error handling
```
## Critical Development Patterns
### Use uv, NEVER pip
**NEVER use `pip install` or `pip` commands.** This project uses `uv` exclusively for package management.
```bash
uv sync # Install dependencies (NOT pip install -r requirements.txt)
uv sync --group dev # Dev dependencies (NOT pip install -e .)
uv run pytest # Run commands (NOT python -m pytest)
uv add package # Add packages (NOT pip install package)
```
### Use libcst, not ast
Always use `libcst` for code parsing/modification to preserve formatting.
### Use Either pattern for errors
```python
from codeflash.either import is_successful
result = aiservice_client.call_llm(...)
if is_successful(result):
optimized_code = result.value
else:
error = result.error
```
### Git worktree isolation
Optimizations run in isolated worktrees:
```python
from codeflash.code_utils.git_worktree_utils import create_detached_worktree, remove_worktree
```
## Git Commits & Pull Requests
- Use conventional commit format: `fix:`, `feat:`, `refactor:`, `docs:`, `test:`, `chore:`
- Keep commits atomic - one logical change per commit
- Commit message body should be concise (1-2 sentences max)
- PR titles should also use conventional format (e.g., `fix: resolve base class dependency tracking`)
## Code Style & Conventions
- **Tooling**: Ruff for linting/formatting, mypy strict mode, pre-commit hooks
- **Line length**: 120 characters
- **Python**: 3.9+ syntax
- **Comments**: Minimal - only explain "why", not "what"
- **Docstrings**: Do not add unless explicitly requested
- **Naming**: Prefer public functions (no leading underscore) - Python doesn't have true private functions
- **Paths**: Always use absolute paths, handle encoding explicitly (UTF-8)
# Agent Rules <!-- tessl-managed -->
@.tessl/RULES.md follow the [instructions](.tessl/RULES.md)

93
CLAUDE.md Normal file
View file

@ -0,0 +1,93 @@
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Project Overview
CodeFlash is an AI-powered Python code optimizer that automatically improves code performance while maintaining correctness. It uses LLMs to generate optimization candidates, verifies correctness through test execution, and benchmarks performance improvements.
## Common Commands
```bash
# Package management (NEVER use pip)
uv sync # Install dependencies
uv sync --group dev # Install dev dependencies
uv add <package> # Add a package
# Running tests
uv run pytest tests/ # Run all tests
uv run pytest tests/test_foo.py # Run specific test file
uv run pytest tests/test_foo.py::test_bar -v # Run single test
# Type checking and linting
uv run mypy codeflash/ # Type check
uv run ruff check codeflash/ # Lint
uv run ruff format codeflash/ # Format
# Pre-commit (run before committing)
uv run pre-commit run --all-files
# Running the CLI
uv run codeflash --help
uv run codeflash init # Initialize in a project
uv run codeflash --all # Optimize entire codebase
```
## Architecture
```
codeflash/
├── main.py # CLI entry point
├── cli_cmds/ # Command handling, console output (Rich)
├── discovery/ # Find optimizable functions
├── context/ # Extract code dependencies and imports
├── optimization/ # Generate optimized code via AI
│ ├── optimizer.py # Main optimization orchestration
│ └── function_optimizer.py # Per-function optimization logic
├── verification/ # Run deterministic tests (pytest plugin)
├── benchmarking/ # Performance measurement
├── github/ # PR creation
├── api/ # AI service communication
├── code_utils/ # Code parsing, git utilities
├── models/ # Pydantic models and types
├── tracing/ # Function call tracing
├── lsp/ # IDE integration (Language Server Protocol)
├── telemetry/ # Sentry, PostHog
├── either.py # Functional Result type for error handling
└── result/ # Result types and handling
```
### Key Patterns
**Either/Result pattern for errors:**
```python
from codeflash.either import is_successful, Success, Failure
result = some_operation()
if is_successful(result):
value = result.unwrap()
else:
error = result.failure()
```
**Use libcst, not ast** - Always use `libcst` for code parsing/modification to preserve formatting.
## Code Style
- **Line length**: 120 characters
- **Python**: 3.9+ syntax
- **Tooling**: Ruff for linting/formatting, mypy strict mode, pre-commit hooks
- **Comments**: Minimal - only explain "why", not "what"
- **Docstrings**: Do not add unless explicitly requested
- **Naming**: Prefer public functions (no leading underscore) - Python doesn't have true private functions
- **Paths**: Always use absolute paths, handle encoding explicitly (UTF-8)
## Git Commits & Pull Requests
- Use conventional commit format: `fix:`, `feat:`, `refactor:`, `docs:`, `test:`, `chore:`
- Keep commits atomic - one logical change per commit
- Commit message body should be concise (1-2 sentences max)
- PR titles should also use conventional format
# Agent Rules <!-- tessl-managed -->
@.tessl/RULES.md follow the [instructions](.tessl/RULES.md)

2
codeflash/lsp/features/perform_optimization.py
View file

@ -164,4 +164,6 @@ def sync_perform_optimization(server: CodeflashLanguageServer, cancel_event: thr
"task_id": params.task_id,
"explanation": best_optimization.explanation_v2,
"optimizationReview": function_optimizer.optimization_review.capitalize(),
"original_line_profiler": original_code_baseline.line_profile_results.get("str_out", ""),
"optimized_line_profiler": best_optimization.line_profiler_test_results.get("str_out", ""),
}

54
codeflash/models/models.py
View file

@ -1,6 +1,7 @@
from __future__ import annotations
from collections import Counter, defaultdict
from functools import lru_cache
from typing import TYPE_CHECKING
import libcst as cst
@ -417,22 +418,51 @@ class TestFiles(BaseModel):
raise ValueError(msg)
def get_by_original_file_path(self, file_path: Path) -> TestFile | None:
return next((test_file for test_file in self.test_files if test_file.original_file_path == file_path), None)
normalized = self._normalize_path_for_comparison(file_path)
for test_file in self.test_files:
if test_file.original_file_path is None:
continue
normalized_test_path = self._normalize_path_for_comparison(test_file.original_file_path)
if normalized == normalized_test_path:
return test_file
return None
def get_test_type_by_instrumented_file_path(self, file_path: Path) -> TestType | None:
return next(
(
test_file.test_type
for test_file in self.test_files
if (file_path in (test_file.instrumented_behavior_file_path, test_file.benchmarking_file_path))
),
None,
)
normalized = self._normalize_path_for_comparison(file_path)
for test_file in self.test_files:
normalized_behavior_path = self._normalize_path_for_comparison(test_file.instrumented_behavior_file_path)
if normalized == normalized_behavior_path:
return test_file.test_type
if test_file.benchmarking_file_path is not None:
normalized_benchmark_path = self._normalize_path_for_comparison(test_file.benchmarking_file_path)
if normalized == normalized_benchmark_path:
return test_file.test_type
return None
def get_test_type_by_original_file_path(self, file_path: Path) -> TestType | None:
return next(
(test_file.test_type for test_file in self.test_files if test_file.original_file_path == file_path), None
)
normalized = self._normalize_path_for_comparison(file_path)
for test_file in self.test_files:
if test_file.original_file_path is None:
continue
normalized_test_path = self._normalize_path_for_comparison(test_file.original_file_path)
if normalized == normalized_test_path:
return test_file.test_type
return None
@staticmethod
@lru_cache(maxsize=4096)
def _normalize_path_for_comparison(path: Path) -> str:
"""Normalize a path for cross-platform comparison.
Resolves the path to an absolute path and handles Windows case-insensitivity.
"""
try:
resolved = str(path.resolve())
except (OSError, RuntimeError):
# If resolve fails (e.g., file doesn't exist), use absolute path
resolved = str(path.absolute())
# Only lowercase on Windows where filesystem is case-insensitive
return resolved.lower() if sys.platform == "win32" else resolved
def __iter__(self) -> Iterator[TestFile]:
return iter(self.test_files)

9
codeflash/verification/parse_test_output.py
View file

@ -774,7 +774,14 @@ def parse_test_xml(
logger.warning(f"Could not find the test for file name - {test_file_path} ")
continue
test_type = test_files.get_test_type_by_instrumented_file_path(test_file_path)
assert test_type is not None, f"Test type not found for {test_file_path}"
if test_type is None:
# Log registered paths for debugging
registered_paths = [str(tf.instrumented_behavior_file_path) for tf in test_files.test_files]
logger.warning(
f"Test type not found for '{test_file_path}'. "
f"Registered test files: {registered_paths}. Skipping test case."
)
continue
test_module_path = module_name_from_file_path(test_file_path, test_config.tests_project_rootdir)
result = testcase.is_passed # TODO: See for the cases of ERROR and SKIPPED
test_class = None

677
docs/cli-reference.mdx
View file

@ -1,677 +0,0 @@
---
title: "CLI Reference"
description: "Complete command-line reference for all Codeflash commands, flags, and options"
icon: "terminal"
sidebarTitle: "CLI Reference"
keywords:
[
"CLI",
"command line",
"commands",
"flags",
"options",
"reference",
"terminal",
]
---
# Codeflash CLI Reference
This guide covers all Codeflash CLI commands with practical examples you can run directly in your terminal.
<Info>
**Prerequisites** - Ensure Codeflash is installed in your Python environment
and you have a configured `pyproject.toml` in your project.
</Info>
---
## Quick Start
<Tabs>
<Tab title="Linux/macOS">
```bash
# Activate virtual environment (if using one)
source .venv/bin/activate
# Verify installation
codeflash --version
```
</Tab>
<Tab title="Windows">
```powershell
# Activate virtual environment (if using one)
.venv\Scripts\activate
# Verify installation
codeflash --version
```
</Tab>
</Tabs>
---
## Common Workflows
### 1. First-Time Setup
<Steps>
<Step title="Install Codeflash">
```bash
pip install codeflash
```
</Step>
<Step title="Initialize Project">
```bash
codeflash init
```
</Step>
<Step title="Verify Setup">
```bash
codeflash --verify-setup
```
</Step>
<Step title="Run First Optimization">
```bash
codeflash --file src/main.py --function my_function --no-pr
```
</Step>
</Steps>
---
### 2. Optimize a Workflow
<Steps>
<Step title="Trace Your Script">
```bash
codeflash optimize my_script.py --arg1 value1
```
</Step>
<Step title="Review Optimizations">
Check the generated PR or local changes for optimization suggestions.
</Step>
</Steps>
---
### 3. CI/CD Integration
<Steps>
<Step title="Set Up GitHub Actions">
```bash
codeflash init-actions
```
</Step>
<Step title="Merge the Workflow PR">
Review and merge the generated GitHub Actions workflow.
</Step>
<Step title="Automatic Optimization">
Codeflash will now optimize code in every PR automatically!
</Step>
</Steps>
---
## 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
<AccordionGroup>
<Accordion title="'Functions outside module-root' Error">
**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
```
</Accordion>
<Accordion title="'benchmarks-root must be specified' Error">
**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
```
</Accordion>
<Accordion title="Replay Test File Not Found">
**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
```
</Accordion>
<Accordion title="GitHub App Required">
**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
```
</Accordion>
</AccordionGroup>
---
## Core Commands
### `codeflash init`
Initialize Codeflash for your Python project. This creates the configuration in `pyproject.toml`.
<CodeGroup>
```bash Basic
codeflash init
```
```bash With Formatter Override
codeflash init --override-formatter-check
```
</CodeGroup>
<Tip>
The `init` command will guide you through an interactive setup process,
including API key configuration, module selection, and GitHub App
installation.
</Tip>
---
### `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
```
<Note>
This command creates a temporary file, runs a sample optimization, and cleans
up afterward. It takes about 3 minutes to complete.
</Note>
---
## Function Optimization
### Optimize a Single Function
Target a specific function in a file for optimization.
```bash
codeflash --file <path/to/file.py> --function <function_name>
```
<Accordion title="Complete Examples">
<Tabs>
<Tab title="Linux/macOS">
```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
```
</Tab>
<Tab title="Windows">
```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
```
</Tab>
</Tabs>
</Accordion>
<Warning>
**Important**: The file must be within your configured `module-root`
directory. Files outside `module-root` will be ignored with "Functions outside
module-root" message.
</Warning>
---
### 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/
```
<Accordion title="Complete Examples">
<Tabs>
<Tab title="Linux/macOS">
```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
```
</Tab>
<Tab title="Windows">
```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
```
</Tab>
</Tabs>
</Accordion>
---
## Trace & Optimize Workflows
### `codeflash optimize`
Trace a Python script's execution and optimize functions based on real-world usage.
```bash
codeflash optimize <script.py> [script_args]
```
<Accordion title="Complete Examples">
<Tabs>
<Tab title="Linux/macOS">
```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
```
</Tab>
<Tab title="Windows">
```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
```
</Tab>
</Tabs>
</Accordion>
---
### Trace with pytest
Optimize functions called during pytest test execution.
<Tabs>
<Tab title="Linux/macOS">
```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
```
</Tab>
<Tab title="Windows">
```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
```
</Tab>
</Tabs>
---
### Trace Only (Generate Replay Tests)
Create trace files and replay tests without running optimization.
<Tabs>
<Tab title="Linux/macOS">
```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
```
</Tab>
<Tab title="Windows">
```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
```
</Tab>
</Tabs>
<Note>
**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`.
</Note>
---
## Benchmark Mode
Optimize code based on performance benchmarks using pytest-benchmark format.
```bash
codeflash --file <file.py> --benchmark --benchmarks-root <path>
```
<Accordion title="Complete Examples">
<Tabs>
<Tab title="Linux/macOS">
```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
```
</Tab>
<Tab title="Windows">
```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
```
</Tab>
</Tabs>
</Accordion>
<Warning>
The `--benchmarks-root` directory must exist and be configured either via
`pyproject.toml` or the command-line flag.
</Warning>
---
## 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 |
<Accordion title="Complete Examples">
<Tabs>
<Tab title="Linux/macOS">
```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
```
</Tab>
<Tab title="Windows">
```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
```
</Tab>
</Tabs>
</Accordion>
---
## 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 |
<Accordion title="Complete Examples">
```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
```
</Accordion>
---
## Next Steps
<CardGroup cols={2}>
<Card title="Optimize a Function" icon="bullseye" href="/optimizing-with-codeflash/one-function">
Learn how to optimize individual functions
</Card>
<Card title="Trace & Optimize" icon="route" href="/optimizing-with-codeflash/trace-and-optimize">
Optimize entire workflows with tracing
</Card>
<Card title="GitHub Actions" icon="github" href="/optimizing-with-codeflash/codeflash-github-actions">
Set up continuous optimization
</Card>
<Card title="Configuration" icon="gear" href="/configuration">
Advanced configuration options
</Card>
</CardGroup>

191
docs/cli-reference/flags.mdx Normal file
View file

@ -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 |
<Accordion title="Complete Examples">
<Tabs>
<Tab title="Linux/macOS">
```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
```
</Tab>
<Tab title="Windows">
```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
```
</Tab>
</Tabs>
</Accordion>
---
## 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 |
<Info>
The `--output` flag specifies where to save the trace file. If not specified, it defaults to `codeflash.trace` in the current directory.
</Info>
---
## 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 |
<Accordion title="Complete Examples">
```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
```
</Accordion>
---
## 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
<CardGroup cols={2}>
<Card
title="Optimization Commands"
icon="bullseye"
href="/cli-reference/optimization"
>
Learn how to use optimization commands
</Card>
<Card
title="Troubleshooting"
icon="wrench"
href="/cli-reference/troubleshooting"
>
Fix common issues
</Card>
</CardGroup>

208
docs/cli-reference/index.mdx Normal file
View file

@ -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.
<Info>
**Prerequisites** - Ensure Codeflash is installed in your Python environment
and you have a configured `pyproject.toml` in your project.
</Info>
---
## Quick Start
<Tabs>
<Tab title="Linux/macOS">
```bash
# Activate virtual environment (if using one)
source .venv/bin/activate
# Verify installation
codeflash --version
```
</Tab>
<Tab title="Windows">
```powershell
# Activate virtual environment (if using one)
.venv\Scripts\activate
# Verify installation
codeflash --version
```
</Tab>
</Tabs>
---
## Common Workflows
### 1. First-Time Setup
<Steps>
<Step title="Install Codeflash">
```bash
pip install codeflash
```
</Step>
<Step title="Initialize Project">
```bash
codeflash init
```
</Step>
<Step title="Verify Setup">
```bash
codeflash --verify-setup
```
</Step>
<Step title="Run First Optimization">
```bash
codeflash --file src/main.py --function my_function --no-pr
```
</Step>
</Steps>
---
### 2. Optimize a Workflow
<Steps>
<Step title="Trace Your Script">
```bash
codeflash optimize my_script.py --arg1 value1
```
</Step>
<Step title="Review Optimizations">
Check the generated PR or local changes for optimization suggestions.
</Step>
</Steps>
---
### 3. CI/CD Integration
<Steps>
<Step title="Set Up GitHub Actions">
```bash
codeflash init-actions
```
</Step>
<Step title="Merge the Workflow PR">
Review and merge the generated GitHub Actions workflow.
</Step>
<Step title="Automatic Optimization">
Codeflash will now optimize code in every PR automatically!
</Step>
</Steps>
---
## 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:
<CardGroup cols={2}>
<Card
title="Setup Commands"
icon="wrench"
href="/cli-reference/setup"
>
Initialize projects, set up GitHub Actions, and verify installation
</Card>
<Card
title="Optimization Commands"
icon="bullseye"
href="/cli-reference/optimization"
>
Optimize single functions or entire codebases
</Card>
<Card
title="Tracing & Workflows"
icon="route"
href="/cli-reference/tracing"
>
Trace script execution and optimize based on real usage
</Card>
<Card
title="Flags Reference"
icon="list"
href="/cli-reference/flags"
>
Complete reference for all command-line flags
</Card>
<Card
title="Troubleshooting"
icon="wrench"
href="/cli-reference/troubleshooting"
>
Solutions for common CLI issues
</Card>
</CardGroup>
---
## Next Steps
<CardGroup cols={2}>
<Card
title="Optimize a Function"
icon="bullseye"
href="/optimizing-with-codeflash/one-function"
>
Learn how to optimize individual functions
</Card>
<Card
title="Trace & Optimize"
icon="route"
href="/optimizing-with-codeflash/trace-and-optimize"
>
Optimize entire workflows with tracing
</Card>
<Card
title="GitHub Actions"
icon="github"
href="/optimizing-with-codeflash/codeflash-github-actions"
>
Set up continuous optimization
</Card>
<Card
title="Configuration"
icon="gear"
href="/configuration"
>
Advanced configuration options
</Card>
</CardGroup>

172
docs/cli-reference/optimization.mdx Normal file
View file

@ -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 <path/to/file.py> --function <function_name>
```
<Accordion title="Complete Examples">
<Tabs>
<Tab title="Linux/macOS">
```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
```
</Tab>
<Tab title="Windows">
```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
```
</Tab>
</Tabs>
</Accordion>
<Warning>
**Important**: The file must be within your configured `module-root`
directory. Files outside `module-root` will be ignored with "Functions outside
module-root" message.
</Warning>
---
## 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/
```
<Accordion title="Complete Examples">
<Tabs>
<Tab title="Linux/macOS">
```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
```
</Tab>
<Tab title="Windows">
```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
```
</Tab>
</Tabs>
</Accordion>
<Info>
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
</Info>
---
## Benchmark Mode
Optimize code based on performance benchmarks using pytest-benchmark format.
```bash
codeflash --file <file.py> --benchmark --benchmarks-root <path>
```
<Accordion title="Complete Examples">
<Tabs>
<Tab title="Linux/macOS">
```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
```
</Tab>
<Tab title="Windows">
```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
```
</Tab>
</Tabs>
</Accordion>
<Warning>
The `--benchmarks-root` directory must exist and be configured either via
`pyproject.toml` or the command-line flag.
</Warning>
---
## Next Steps
<CardGroup cols={2}>
<Card
title="Tracing & Workflows"
icon="route"
href="/cli-reference/tracing"
>
Learn about trace-based optimization
</Card>
<Card
title="Flags Reference"
icon="list"
href="/cli-reference/flags"
>
Complete flag reference
</Card>
</CardGroup>

125
docs/cli-reference/setup.mdx Normal file
View file

@ -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`.
<CodeGroup>
```bash Basic
codeflash init
```
```bash With Formatter Override
codeflash init --override-formatter-check
```
</CodeGroup>
<Tip>
The `init` command will guide you through an interactive setup process,
including API key configuration, module selection, and GitHub App
installation.
</Tip>
**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
<Warning>
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.
</Warning>
---
## `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
<Tip>
This command is also run automatically during `codeflash init` if you choose to install the extension.
</Tip>
---
## `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
<Note>
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.
</Note>
---
## Next Steps
<CardGroup cols={2}>
<Card
title="Optimization Commands"
icon="bullseye"
href="/cli-reference/optimization"
>
Learn how to optimize functions
</Card>
<Card
title="Flags Reference"
icon="list"
href="/cli-reference/flags"
>
Complete flag reference
</Card>
</CardGroup>

213
docs/cli-reference/tracing.mdx Normal file
View file

@ -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.py> [script_args]
```
<Accordion title="Complete Examples">
<Tabs>
<Tab title="Linux/macOS">
```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
```
</Tab>
<Tab title="Windows">
```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
```
</Tab>
</Tabs>
</Accordion>
**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.
<Tabs>
<Tab title="Linux/macOS">
```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
```
</Tab>
<Tab title="Windows">
```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
```
</Tab>
</Tabs>
<Tip>
Tracing pytest tests is great for optimizing functions that are heavily used in your test suite, ensuring optimizations work correctly with your existing tests.
</Tip>
---
## Trace Only (Generate Replay Tests)
Create trace files and replay tests without running optimization.
<Tabs>
<Tab title="Linux/macOS">
```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
```
</Tab>
<Tab title="Windows">
```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
```
</Tab>
</Tabs>
<Note>
**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`.
</Note>
**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 <path/to/replay_test.py>
```
<Accordion title="Complete Examples">
<Tabs>
<Tab title="Linux/macOS">
```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
```
</Tab>
<Tab title="Windows">
```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
```
</Tab>
</Tabs>
</Accordion>
---
## Next Steps
<CardGroup cols={2}>
<Card
title="Optimization Commands"
icon="bullseye"
href="/cli-reference/optimization"
>
Learn about function optimization
</Card>
<Card
title="Flags Reference"
icon="list"
href="/cli-reference/flags"
>
Complete flag reference
</Card>
</CardGroup>

157
docs/cli-reference/troubleshooting.mdx Normal file
View file

@ -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
<AccordionGroup>
<Accordion title="'Functions outside module-root' Error">
**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
```
</Accordion>
<Accordion title="'benchmarks-root must be specified' Error">
**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
```
</Accordion>
<Accordion title="Replay Test File Not Found">
**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
```
<Note>
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`.
</Note>
</Accordion>
<Accordion title="GitHub App Required">
**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
```
</Accordion>
<Accordion title="Module Not Found Errors">
**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)"
```
</Accordion>
<Accordion title="Test Generation Fails">
**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
```
</Accordion>
<Accordion title="Optimization Timeout">
**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
```
</Accordion>
</AccordionGroup>
---
## 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 <command> --help`
---
## Next Steps
<CardGroup cols={2}>
<Card
title="Setup Commands"
icon="wrench"
href="/cli-reference/setup"
>
Review setup and initialization
</Card>
<Card
title="Flags Reference"
icon="list"
href="/cli-reference/flags"
>
Complete flag reference
</Card>
</CardGroup>

20
docs/docs.json
View file

@ -30,12 +30,24 @@
"pages": ["index"]
},
{
"group": "📖 CLI Reference",
"pages": ["cli-reference"]
"group": "📖 Codeflash CLI",
"pages": [
"cli-reference/index",
"cli-reference/setup",
"cli-reference/optimization",
"cli-reference/tracing",
"cli-reference/flags",
"cli-reference/troubleshooting"
]
},
{
"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",

48
docs/editor-plugins/vscode.mdx
View file

@ -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.

152
docs/editor-plugins/vscode/configuration.mdx Normal file
View file

@ -0,0 +1,152 @@
---
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.
![Kebab menu next to Optimize button](../../images/Select-Project-Config.png)
</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="Codeflash CLI" icon="terminal" href="/cli-reference/index">
Command-line options
</Card>
</CardGroup>

233
docs/editor-plugins/vscode/features.mdx Normal file
View file

@ -0,0 +1,233 @@
---
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
![CodeLens hint above function](../../images/CodeLens.png)
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
![Optimization tab with file and function selectors](../../images/optimization-tab.png)
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
![Optimize current file quick action card](../../images/Optimize-current-file.png)
- **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)
![Optimize Changed Code quick action card](../../images/optimize-code-diff.png)
- **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:
![Completed optimizations list in Tasks tab](../../images/optimized-function-tab-tasks.png)
- **Function Name** — The name of the optimized function
- **Status Badge** — Shows completion status with speedup information:
- "Completed (Xx Faster)" — Displays the performance improvement
- Example: "Completed (2.5x Faster)" or "Completed (Speedup: 338.66x Faster)"
- **Optimization Quality** — Some optimizations show quality ratings (e.g., "Optimization Quality: High")
- **Actions:**
- **View Optimization** button — Opens the diff view to see changes and apply them
- **View PR** button — Opens the associated pull request (if optimization was created via PR)
<Info>
The Tasks tab shows a badge count (e.g., "Tasks 19") indicating how many
optimization tasks you have in total.
</Info>
---
## Optimization Workflow
Once you've selected functions to optimize (via any method above), here's what happens:
<Steps>
<Step title="Queue Optimization">
Selected functions are added to the optimization queue. You can see them in
the Tasks tab.
</Step>
<Step title="Track Progress">
Watch the Tasks tab for real-time updates: - Generating optimization
candidates - Running tests to verify correctness - Benchmarking performance
</Step>
<Step title="Review Results">
When complete, you'll see the optimization in the Tasks tab with: - Speedup
information (e.g., "2.5x Faster") - Optimization quality rating - **View
Optimization** button to see the diff
</Step>
<Step title="Apply Changes">
Click **View Optimization** to see the full diff, then **Accept** to apply
the optimization, or **Reject** to dismiss it.
</Step>
</Steps>
---
## Reviewing Optimizations
After an optimization completes, you can review it in the Tasks tab or via inline comments.
![Detailed optimization explanation view](../../images/optimization-details-explaination.png)
### In the Tasks Tab
Click **View Optimization** on any completed optimization to see:
- Side-by-side comparison of original vs. optimized code
- Performance improvement percentage (speedup)
- Runtime comparison (original vs. optimized)
- Optimization quality rating
- Detailed explanation of what changed and why
- **Apply Optimization** button to accept the changes
### 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
View 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 [Codeflash CLI](/cli-reference/index).
---
## 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="Codeflash CLI" icon="terminal" href="/cli-reference/index">
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
View 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="Codeflash CLI" icon="terminal" href="/cli-reference/index">
Command-line interface docs
</Card>
</CardGroup>

BIN
docs/images/CodeLens.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 41 KiB

BIN
docs/images/Optimize-current-file.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 5.8 KiB

BIN
docs/images/Select-Project-Config.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 27 KiB

BIN
docs/images/optimization-details-explaination.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 183 KiB

BIN
docs/images/optimization-tab.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 12 KiB

BIN
docs/images/optimize-code-diff.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 5.9 KiB

BIN
docs/images/optimized-function-tab-tasks.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 48 KiB