Merge pull request #1857 from codeflash-ai/docs/cc-plugin-documentation
docs: add comprehensive documentation for codeflash-cc-plugin
This commit is contained in:
Sarthak Agarwal
GitHub
commit
73eeb86e7a
8 changed files with 257 additions and 1123 deletions
|
|
@ -1 +0,0 @@
|
|||
|
||||
|
|
@ -1 +0,0 @@
|
|||
|
||||
109
docs/claude-code-plugin/getting-started.mdx
Normal file
109
docs/claude-code-plugin/getting-started.mdx
Normal file
|
|
@ -0,0 +1,109 @@
|
|||
---
|
||||
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
|
||||
```
|
||||
|
||||
```bash
|
||||
/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 locally via `~/.claude/settings.json` |
|
||||
| Project | `--scope project` | Shared with team with version control via `.claude/settings.json` |
|
||||
| Local | `--scope local` | This 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
|
||||
|
||||
<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>
|
||||
87
docs/claude-code-plugin/troubleshooting.mdx
Normal file
87
docs/claude-code-plugin/troubleshooting.mdx
Normal file
|
|
@ -0,0 +1,87 @@
|
|||
---
|
||||
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`.
|
||||
|
||||
## 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
|
||||
53
docs/claude-code-plugin/usage-guide.mdx
Normal file
53
docs/claude-code-plugin/usage-guide.mdx
Normal file
|
|
@ -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>
|
||||
|
||||
|
|
@ -1,26 +0,0 @@
|
|||
---
|
||||
title: "Manual Configuration"
|
||||
description: "Configure Codeflash for your project"
|
||||
icon: "gear"
|
||||
sidebarTitle: "Manual Configuration"
|
||||
keywords:
|
||||
[
|
||||
"configuration",
|
||||
"setup",
|
||||
"settings",
|
||||
]
|
||||
---
|
||||
|
||||
# Manual Configuration
|
||||
|
||||
Codeflash is installed and configured on a per-project basis.
|
||||
`codeflash init` should guide you through the configuration process, but if you need to manually configure Codeflash or set advanced settings, follow the guide for your language:
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Python Configuration" icon="python" href="/configuration/python">
|
||||
Configure via `pyproject.toml`
|
||||
</Card>
|
||||
<Card title="JavaScript / TypeScript Configuration" icon="js" href="/configuration/javascript">
|
||||
Configure via `package.json`
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
|
@ -67,6 +67,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"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
|
|
|
|||
File diff suppressed because it is too large
Load diff
Loading…
Reference in a new issue