> ## Documentation Index
> Fetch the complete documentation index at: https://docs.codeflash.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started

> Install the Codeflash Claude Code plugin and run your first optimization

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 theme={null}
/plugin marketplace add codeflash-ai/codeflash-cc-plugin
```

```bash theme={null}
/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>