Skip to main content
This guide walks you through installing the Codeflash Claude Code plugin and running your first optimization.

​
Prerequisites

  • Claude Code v2.1.38 or later
  • Python projects: codeflash installed in a virtual environment
  • JS/TS projects: codeflash installed as a dev dependency

​
Installation

​
Add the marketplace and install

/plugin marketplace add codeflash-ai/codeflash-cc-plugin

/plugin install codeflash

​
Choose installation scope

By default, plugins install at the user level (available across all projects). You can change this:
ScopeFlagEffect
User (default)(none)Available in all your projects locally via ~/.claude/settings.json
Project--scope projectShared with team with version control via .claude/settings.json
Local--scope localThis project only for local use, gitignored

​
Verify installation

Run /plugin to open the plugin manager. Confirm codeflash appears under the Installed tab.

​
User-invokable optimization

Run the /optimize skill with a target file: 
/optimize --file src/utils.py
Run the /optimize skill with a target file and a target function: 
/optimize --file src/utils.py --function my_func
Run the /optimize skill with a natural language instruction: 
/optimize the my_func function in utils.py
The plugin would work even without the command being explicitly called. 
make my_func run faster
What happens behind the scenes:
  1. The skill forks a background optimizer agent
  2. It parses the instruction to figure out the file and function to optimize
  3. The agent walks upward from CWD to the git root, looking for pyproject.toml (Python) or package.json (JS/TS)
  4. It verifies codeflash is installed and configured
  5. If configuration is missing, it auto-discovers your module root and tests directory and writes the config for you
  6. It runs codeflash --subagent in the background with a 10-minute timeout along with the file and function argument.
  7. Results are reported when optimization completes
You can continue working while codeflash optimizes in the background.

​
Continuous Optimization triggered on commit

Whenever any new code is commited to the repository after the claude session starts, a new background codeflash optimizer agent will spawn automatically to optimize the new code.

​
Set up auto-permissions

Run /codeflash:setup to allow codeflash to execute automatically without permission prompts: 
/codeflash:setup
This adds Bash(*codeflash*) to the permissions.allow array in .claude/settings.json. After this, the post-commit hook can trigger optimizations without asking each time.

​
Next steps

Usage Guide

All commands, flags, and workflows

Configuration

Config reference for Python and JS/TS projects

Troubleshooting

Common problems and fixes

Architecture

How the plugin works internally