codeflash-agent

A Claude Code plugin 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:

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

Local (development)

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