codeflash-ai · aseembits93 · Mar 17, 2026 · Mar 17, 2026 · Mar 20, 2026 · Mar 20, 2026
diff --git a/docs/FRICTIONLESS_SETUP_PLAN.md b/docs/FRICTIONLESS_SETUP_PLAN.md
diff --git a/docs/JS_PROMPT_PARITY_RECOMMENDATIONS.md b/docs/JS_PROMPT_PARITY_RECOMMENDATIONS.md
diff --git a/docs/claude-code-plugin/getting-started.mdx b/docs/claude-code-plugin/getting-started.mdx
@@ -0,0 +1,95 @@
+---
+title: "Getting Started"
+description: "Install the Codeflash Claude Code plugin and run your first optimization"
+icon: "rocket"
+sidebarTitle: "Getting Started"
+---
+
+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](https://pypi.org/project/codeflash/) installed in a virtual environment
+- **JS/TS projects**: [codeflash](https://www.npmjs.com/package/codeflash) installed as a dev dependency
+
+## Installation
+
+### Add the marketplace and install
+
+```bash
+/plugin marketplace add codeflash-ai/codeflash-cc-plugin
+/plugin install codeflash
+```
+
+Or from a local clone:
+
+```bash
+git clone https://github.com/codeflash-ai/codeflash-cc-plugin.git
+/plugin marketplace add ./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:
+
+| Scope | Flag | Effect |
+|-------|------|--------|
+| User (default) | _(none)_ | Available in all your projects |
+| Project | `--scope project` | Shared with team via `.claude/settings.json` |
+| Local | `--scope local` | This project only, gitignored |
+
+```bash
+/plugin install codeflash --scope project
+```
+
+### Verify installation
+
+Run `/plugin` to open the plugin manager. Confirm **codeflash** appears under the **Installed** tab.
+
+## First optimization
+
+Run the `/optimize` skill with a target file:
+
+```
+/optimize src/utils.py
+```
+
+What happens behind the scenes:
+
+1. The skill forks a background **optimizer agent**
+2. The agent walks upward from CWD to the git root, looking for `pyproject.toml` (Python) or `package.json` (JS/TS)
+3. It verifies codeflash is installed and configured
+4. If configuration is missing, it auto-discovers your module root and tests directory and writes the config for you
+5. It runs `codeflash --subagent` in the background with a 10-minute timeout
+6. Results are reported when optimization completes
+
+You can continue working while codeflash optimizes in the background.
+
+## 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
+
+<CardGroup cols={2}>
+  <Card title="Usage Guide" icon="book" href="/claude-code-plugin/usage-guide">
+    All commands, flags, and workflows
+  </Card>
+  <Card title="Configuration" icon="gear" href="/claude-code-plugin/configuration">
+    Config reference for Python and JS/TS projects
+  </Card>
+  <Card title="Troubleshooting" icon="wrench" href="/claude-code-plugin/troubleshooting">
+    Common problems and fixes
+  </Card>
+  <Card title="Architecture" icon="sitemap" href="/claude-code-plugin/architecture">
+    How the plugin works internally
+  </Card>
+</CardGroup>
diff --git a/docs/claude-code-plugin/troubleshooting.mdx b/docs/claude-code-plugin/troubleshooting.mdx
@@ -0,0 +1,114 @@
+---
+title: "Troubleshooting"
+description: "Common problems and fixes for the Codeflash Claude Code plugin"
+icon: "wrench"
+sidebarTitle: "Troubleshooting"
+---
+
+## 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:
+
+```json
+{
+  "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**:
+
+```bash
+npm install --save-dev codeflash
+```
+
+Run this in the directory containing your `package.json`.
+
+## Hook not triggering after commits
+
+**Symptom**: You commit Python/JS/TS files but don't see optimization suggestions.
+
+**Check**:
+1. Verify the hook is registered: look for `hooks/hooks.json` in the plugin directory
+2. Check the debug log: `cat /tmp/codeflash-hook-debug.log`
+3. Ensure commits touch `.py`, `.js`, `.ts`, `.jsx`, or `.tsx` files
+4. The hook only detects commits made **during the current session** (after the transcript file was created). Commits from before starting Claude Code won't trigger it.
+
+## Hook triggering repeatedly
+
+**Symptom**: The hook keeps suggesting optimization for the same commits.
+
+This shouldn't happen due to deduplication (the hook tracks seen commit hashes in `$TRANSCRIPT_DIR/codeflash-seen`). If it does:
+
+1. Check the seen-marker file exists in the transcript directory
+2. Look at `/tmp/codeflash-hook-debug.log` for the dedup logic trace
+3. If commit hashes changed (e.g., amended commits), the hook treats them as new
+
+## "Attempting to repair broken tests..."
+
+<Info>
+This is **normal codeflash behavior**, not an error. Codeflash generates tests and sometimes needs to fix them. Let it continue.
+</Info>
+
+## 10-minute timeout exceeded
+
+**Symptom**: Codeflash background task times out.
+
+This can happen on large projects or with `--all`. Options:
+- Optimize specific files instead of the entire project: `/optimize src/specific_file.py`
+- Target individual functions: `/optimize src/utils.py my_function`
+- The `--all` flag scans every function, which naturally takes longer
+
+## 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
diff --git a/docs/claude-code-plugin/usage-guide.mdx b/docs/claude-code-plugin/usage-guide.mdx
@@ -0,0 +1,53 @@
+---
+title: "Usage Guide"
+description: "Commands, flags, and workflows for the Codeflash Claude Code plugin"
+icon: "book"
+sidebarTitle: "Usage Guide"
+---
+
+## The `/optimize` skill
+
+`/optimize` is the primary command. It spawns a background optimizer agent that runs the codeflash CLI on your code.
+
+### Syntax
+
+```
+/optimize [file] [function] [flags]
+```
+
+### Examples
+
+| Command | Effect |
+|---------|--------|
+| `/optimize` | Let codeflash detect changed files automatically |
+| `/optimize src/utils.py` | Optimize all functions in `src/utils.py` |
+| `/optimize src/utils.py my_function` | Optimize only `my_function` in that file |
+| `/optimize --all` | Optimize the entire project |
+
+Flags can be combined: `/optimize src/utils.py my_function`
+
+### What happens behind the scenes
+
+1. The skill (defined in `skills/optimize/SKILL.md`) forks context and spawns the **optimizer agent**
+2. The agent locates your project config (`pyproject.toml` or `package.json` or `codeflash.toml`)
+3. It verifies the codeflash CLI is installed and the project is configured
+4. It runs `codeflash --subagent` as a **background task** with a 10-minute timeout
+5. You're notified when optimization completes with results
+
+The agent has up to **15 turns** to complete its work (install codeflash, configure the project, run optimization).
+
+## The `/codeflash:setup` command
+
+`/codeflash:setup` configures auto-permissions so codeflash runs without prompting.
+
+### What it does
+
+1. Finds `.claude/settings.json` in your project root
+2. Checks if `Bash(*codeflash*)` is already in `permissions.allow`
+3. If not, adds it (creating the file and directory if needed)
+4. Preserves any existing settings
+
+<Info>
+Running `/codeflash:setup` multiple times is safe — it's idempotent. If permissions are already configured, it reports "No changes needed."
+</Info>
+
diff --git a/docs/configuration.mdx b/docs/configuration.mdx
diff --git a/docs/docs.json b/docs/docs.json
@@ -65,6 +65,14 @@
               "editor-plugins/vscode/configuration",
               "editor-plugins/vscode/troubleshooting"
             ]
+          },
+          {
+            "group": "Claude Code Plugin",
+            "pages": [
+              "claude-code-plugin/getting-started",
+              "claude-code-plugin/usage-guide",
+              "claude-code-plugin/troubleshooting"
+            ]
           }
         ]
       }