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

​
Choose installation scope

By default, plugins install at the user level (available across all projects). You can change this:

​
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:
Run the /optimize skill with a target file and a target function:
Run the /optimize skill with a natural language instruction:
The plugin would work even without the command being explicitly called.
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:
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