Skip to main content

​
Plugin not appearing after install

Symptom: /plugin doesn’t show codeflash in the Installed tab. Fix:
  1. Verify the marketplace was added: /plugin marketplace add codeflash-ai/codeflash-cc-plugin
  2. Install again: /plugin install codeflash
  3. Check you’re running Claude Code v2.1.38 or later

​
/optimize does nothing

Symptom: Running /optimize produces no output or immediately returns. Possible causes:
  • No project config found. The agent walks from CWD to the git root looking for pyproject.toml or package.json. Make sure you’re inside a git repository.
  • Codeflash CLI not installed. For Python: pip install codeflash in your venv. For JS/TS: npm install --save-dev codeflash.
  • The agent is running in the background. Check if you see “Codeflash is optimizing in the background” — results appear when the background task completes.

​
Permission prompts every time

Symptom: Claude asks for permission to run codeflash on every invocation. Fix: Run /setup to add Bash(*codeflash*) to .claude/settings.json. Or add it manually: 
{
  "permissions": {
    "allow": [
      "Bash(*codeflash*)"
    ]
  }
}

​
No venv found (Python)

Symptom: Hook or agent reports “No Python virtual environment was found.” Fix:
  1. Create a venv: python3 -m venv .venv
  2. Activate it: source .venv/bin/activate
  3. Install codeflash: pip install codeflash
  4. Restart Claude Code from within the activated venv
The plugin searches for venvs in this order:
  1. <project_dir>/.venv
  2. <project_dir>/venv
  3. <repo_root>/.venv
  4. <repo_root>/venv

​
Codeflash not installed (JS/TS)

Symptom: npx codeflash --version fails or package not found. Fix: 
npm install --save-dev codeflash
Run this in the directory containing your package.json.

​
10-minute timeout exceeded

Symptom: Codeflash background task times out. This can happen on large projects. Options:
  • Optimize specific files instead of the entire project: /optimize src/specific_file.py
  • Target individual functions: /optimize src/utils.py my_function

​
Formatter errors

Symptom: Codeflash fails with formatter-related errors. Check:
  1. Read the formatter-cmds (Python) or formatterCmds (JS/TS) in your config
  2. Verify each formatter is installed:
    • Python: which black (or whichever formatter)
    • JS/TS: npx prettier --version (or whichever formatter)
  3. Set formatter-cmds = ["disabled"] or "formatterCmds": ["disabled"] to skip formatting entirely