# codeflash-agent

A [Claude Code plugin](https://docs.anthropic.com/en/docs/claude-code/plugins) for autonomous Python runtime performance optimization. Profiles code, implements optimizations, benchmarks before and after, and iterates until plateau.

## Domains

| Domain | When to use |
|--------|-------------|
| **Memory** | Peak memory, OOM, memory leaks, RSS reduction |
| **Async** | Concurrency, event loop blocking, sequential awaits, throughput/latency |
| **Data Structures** | CPU time, O(n²) loops, wrong containers, algorithmic complexity |
| **Structure** | Import time, circular deps, module reorganization for performance |

The agent auto-detects which domain(s) apply based on your request.

## Install

Inside Claude Code, run:

```
/plugin marketplace add codeflash-ai/codeflash-agent
/plugin install codeflash-agent@codeflash
```

### Team setup

Add to your repo's `.claude/settings.json` so everyone on the team gets it automatically:

```json
{
  "extraKnownMarketplaces": {
    "codeflash": {
      "source": {
        "source": "github",
        "repo": "codeflash-ai/codeflash-agent"
      }
    }
  },
  "enabledPlugins": {
    "codeflash-agent@codeflash": true
  }
}
```

### Local (development)

```bash
git clone https://github.com/codeflash-ai/codeflash-agent.git
claude --plugin-dir ./codeflash-agent
```

## Usage

The agent triggers automatically when you describe a performance problem:

```
> Our /process endpoint takes 5s but individual calls should only take 500ms each
> test_process_large_file is using 3GB, find ways to reduce it
> process_records is too slow, it's doing O(n²) lookups
```

Or use the slash command:

```
> /codeflash-optimize start    # begin a new session
> /codeflash-optimize resume   # continue from where you left off
> /codeflash-optimize status   # check progress
```

## How it works

1. **Discovery** — reads project structure, detects package manager, identifies target code
2. **Baseline** — profiles the target before making any changes (mandatory)
3. **Analysis** — ranks bottlenecks by measured impact, not source-reading intuition
4. **Experiment loop** — implements fixes one at a time, re-profiles after each, keeps or discards based on measured improvement
5. **Plateau detection** — stops when gains diminish or stall

Session state persists in `HANDOFF.md` and `results.tsv`, so you can resume across conversations.

## Plugin structure

```
.claude-plugin/plugin.json    # plugin manifest
agents/codeflash.md           # router — detects domain, launches specialized agent
agents/codeflash-cpu.md       # data structures & algorithmic optimization
agents/codeflash-memory.md    # memory profiling & reduction
agents/codeflash-async.md     # async concurrency optimization
agents/codeflash-structure.md # module structure & import optimization
agents/codeflash-setup.md     # project environment setup
agents/references/            # domain-specific deep-dive guides
skills/codeflash-optimize/    # /codeflash-optimize slash command
```