Activate virtualenv before running codeflash

agents/optimizer.md

@@ -51,7 +51,16 @@ If no `pyproject.toml` is found, use the git repository root as the project dire
 
 ### 2. Verify Installation
 
-Run `codeflash --version`. If it succeeds, proceed to Step 3.
+First, check if codeflash is available. Look for it in this order:
+1. On PATH: `command -v codeflash`
+2. In a virtualenv: check `<project_dir>/.venv/bin/codeflash`, `<project_dir>/venv/bin/codeflash`, and similar common venv directories (`.env`, `env`)
+
+If codeflash is found inside a virtualenv, you **must activate that virtualenv** before running any codeflash commands:
+```bash
+source <venv_dir>/bin/activate
+```
+
+Run `codeflash --version` (after activation if needed). If it succeeds, proceed to Step 3.
 
 If it fails (exit code non-zero or command not found), codeflash is not installed. Ask the user whether they'd like to install it now:
 
@@ -107,20 +116,20 @@ If no file and no `--all` flag, run codeflash without `--file` or `--all` to let
 
 If the project directory from Step 1 differs from the current working directory, **`cd` to the project directory first** so that relative paths in the config resolve correctly.
 
-Execute the appropriate command **in the background** (`run_in_background: true`) with a **10-minute timeout** (`timeout: 600000`):
+If codeflash was found in a virtualenv (Step 2), **activate the virtualenv first** in the same command. Execute the appropriate command **in the background** (`run_in_background: true`) with a **10-minute timeout** (`timeout: 600000`):
 
 ```bash
 # Default: let codeflash detect changed files
-cd <project_dir> && codeflash --subagent [flags]
+source <venv>/bin/activate && cd <project_dir> && codeflash --subagent [flags]
 
 # Specific file
-cd <project_dir> && codeflash --subagent --file <path> [--function <name>] [flags]
+source <venv>/bin/activate && cd <project_dir> && codeflash --subagent --file <path> [--function <name>] [flags]
 
 # All files (only when explicitly requested with --all)
-cd <project_dir> && codeflash --subagent --all [flags]
+source <venv>/bin/activate && cd <project_dir> && codeflash --subagent --all [flags]
 ```
 
-If CWD is already the project directory, omit the `cd`.
+If codeflash is on PATH (not in a venv), omit the `source` step. If CWD is already the project directory, omit the `cd`.
 
 **IMPORTANT**: Always use `run_in_background: true` when calling the Bash tool to execute codeflash. This allows optimization to run in the background while Claude continues other work. Tell the user "Codeflash is optimizing in the background, you'll be notified when it completes" and do not wait for the result.
 

scripts/check-config.sh

@@ -82,6 +82,7 @@ INSTALL_CMD="pip install codeflash"
 # --- locate codeflash binary ---------------------------------------------
 find_codeflash() {
   CODEFLASH_BIN=""
+  CODEFLASH_VENV_ACTIVATE=""
   if command -v codeflash >/dev/null 2>&1; then
     CODEFLASH_BIN="codeflash"
     return
@@ -91,6 +92,9 @@ find_codeflash() {
     for venv in ".venv" "venv" ".env" "env"; do
       if [ -x "$search_dir/$venv/bin/codeflash" ]; then
         CODEFLASH_BIN="$search_dir/$venv/bin/codeflash"
+        if [ -f "$search_dir/$venv/bin/activate" ]; then
+          CODEFLASH_VENV_ACTIVATE="$search_dir/$venv/bin/activate"
+        fi
         return
       fi
     done
@@ -124,6 +128,12 @@ if [ "$PYPROJECT_CONFIGURED" != "true" ]; then
 - First, install codeflash by running \`${INSTALL_CMD}\` in \`${CHECK_DIR}\`."
   fi
 
+  ACTIVATE_STEP=""
+  if [ -n "$CODEFLASH_VENV_ACTIVATE" ]; then
+    ACTIVATE_STEP="
+- Before running codeflash, activate the virtualenv: \`source ${CODEFLASH_VENV_ACTIVATE}\`"
+  fi
+
   SETUP_MSG="ACTION REQUIRED: This is a Python project but codeflash is not configured yet.
 
 You MUST ask the user the following two questions before proceeding with anything else:
@@ -140,7 +150,7 @@ module-root = \"<module root>\"
 tests-root = \"<tests folder>\"
 ignore-paths = []
 formatter-cmds = [\"disabled\"]
-
+${ACTIVATE_STEP}
 Once the pyproject.toml configuration is written, you MUST immediately run \`codeflash --subagent\` as a background Bash task (run_in_background: true). Do NOT skip this step."
 
   touch "$SESSION_FLAG"
@@ -151,13 +161,20 @@ Once the pyproject.toml configuration is written, you MUST immediately run \`cod
 fi
 
 # --- configured but not installed → prompt for install -------------------
+ACTIVATE_NOTE=""
+if [ -n "$CODEFLASH_VENV_ACTIVATE" ]; then
+  ACTIVATE_NOTE="
+
+Before running codeflash, activate the virtualenv: \`source ${CODEFLASH_VENV_ACTIVATE}\`"
+fi
+
 INSTALL_MSG="ACTION REQUIRED: This is a Python project with codeflash configured, but the codeflash package is not installed.
 
 You MUST ask the user if they'd like to install codeflash before proceeding with anything else. The detected install command is:
 
   ${INSTALL_CMD}
 
-If the user agrees, run the install command in \`${CHECK_DIR}\`, then proceed to run codeflash via \`codeflash --subagent\`."
+If the user agrees, run the install command in \`${CHECK_DIR}\`, then proceed to run codeflash via \`codeflash --subagent\`.${ACTIVATE_NOTE}"
 
 touch "$SESSION_FLAG"
 

scripts/check-install.sh

@@ -45,6 +45,7 @@ CHECK_DIR="${PYPROJECT_DIR:-$PWD}"
 # Locate the codeflash binary: check PATH, then .venv/bin/, then common venv paths.
 find_codeflash() {
   CODEFLASH_BIN=""
+  CODEFLASH_VENV_ACTIVATE=""
   if command -v codeflash >/dev/null 2>&1; then
     CODEFLASH_BIN="codeflash"
     return
@@ -54,6 +55,9 @@ find_codeflash() {
     for venv in ".venv" "venv" ".env" "env"; do
       if [ -x "$search_dir/$venv/bin/codeflash" ]; then
         CODEFLASH_BIN="$search_dir/$venv/bin/codeflash"
+        if [ -f "$search_dir/$venv/bin/activate" ]; then
+          CODEFLASH_VENV_ACTIVATE="$search_dir/$venv/bin/activate"
+        fi
         return
       fi
     done

scripts/suggest-optimize.sh

@@ -79,6 +79,7 @@ INSTALL_CMD="pip install codeflash"
 # Locate the codeflash binary: check PATH, then .venv/bin/, then common venv paths.
 find_codeflash() {
   CODEFLASH_BIN=""
+  CODEFLASH_VENV_ACTIVATE=""
   if command -v codeflash >/dev/null 2>&1; then
     CODEFLASH_BIN="codeflash"
     return
@@ -88,6 +89,9 @@ find_codeflash() {
     for venv in ".venv" "venv" ".env" "env"; do
       if [ -x "$search_dir/$venv/bin/codeflash" ]; then
         CODEFLASH_BIN="$search_dir/$venv/bin/codeflash"
+        if [ -f "$search_dir/$venv/bin/activate" ]; then
+          CODEFLASH_VENV_ACTIVATE="$search_dir/$venv/bin/activate"
+        fi
         return
       fi
     done
@@ -118,6 +122,12 @@ if [ "$PYPROJECT_CONFIGURED" != "true" ]; then
 - First, install codeflash by running \`${INSTALL_CMD}\` in \`${CHECK_DIR}\`."
   fi
 
+  ACTIVATE_STEP=""
+  if [ -n "$CODEFLASH_VENV_ACTIVATE" ]; then
+    ACTIVATE_STEP="
+- Before running codeflash, activate the virtualenv: \`source ${CODEFLASH_VENV_ACTIVATE}\`"
+  fi
+
   SETUP_MSG="ACTION REQUIRED: Python files were changed in the latest commit, but codeflash is not configured yet.
 
 You MUST ask the user the following two questions before proceeding with anything else:
@@ -134,7 +144,7 @@ module-root = \"<module root>\"
 tests-root = \"<tests folder>\"
 ignore-paths = []
 formatter-cmds = [\"disabled\"]
-
+${ACTIVATE_STEP}
 Once the pyproject.toml configuration is written, you MUST immediately run \`codeflash --subagent\` as a background Bash task (run_in_background: true). Do NOT skip this step."
 
   # Set flag so the Stop hook can enforce this if Claude ignores additionalContext
@@ -147,23 +157,35 @@ fi
 
 # Codeflash is configured but not installed
 if [ "$CODEFLASH_INSTALLED" != "true" ]; then
+  ACTIVATE_NOTE=""
+  if [ -n "$CODEFLASH_VENV_ACTIVATE" ]; then
+    ACTIVATE_NOTE="
+
+Before running codeflash, activate the virtualenv: \`source ${CODEFLASH_VENV_ACTIVATE}\`"
+  fi
+
   INSTALL_MSG="ACTION REQUIRED: Python files were changed in the latest commit, but codeflash is not installed.
 
 You MUST ask the user if they'd like to install codeflash before proceeding with anything else. The detected install command is:
 
   ${INSTALL_CMD}
 
-If the user agrees, run the install command in \`${CHECK_DIR}\`, then proceed to run codeflash via \`codeflash --subagent\`."
+If the user agrees, run the install command in \`${CHECK_DIR}\`, then proceed to run codeflash via \`codeflash --subagent\`.${ACTIVATE_NOTE}"
 
   jq -nc --arg ctx "$INSTALL_MSG" '{"hookSpecificOutput": {"hookEventName": "PostToolUse", "additionalContext": $ctx}}'
   exit 0
 fi
 
-# Build codeflash command, adding cd when pyproject.toml is in a parent directory
+# Build codeflash command, adding cd and venv activation as needed
+ACTIVATE_PREFIX=""
+if [ -n "$CODEFLASH_VENV_ACTIVATE" ]; then
+  ACTIVATE_PREFIX="source $CODEFLASH_VENV_ACTIVATE && "
+fi
+
 if [ -n "$PYPROJECT_DIR" ] && [ "$PYPROJECT_DIR" != "$PWD" ]; then
-  CMD="cd $PYPROJECT_DIR && $CODEFLASH_BIN --subagent"
+  CMD="${ACTIVATE_PREFIX}cd $PYPROJECT_DIR && codeflash --subagent"
 else
-  CMD="$CODEFLASH_BIN --subagent"
+  CMD="${ACTIVATE_PREFIX}codeflash --subagent"
 fi
 
 MESSAGE="Python files were changed in the latest commit. Run the following command as a background Bash task (run_in_background: true):