92 lines
3 KiB
Markdown
92 lines
3 KiB
Markdown
# 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
|
|
```
|