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
CPU	CPU time, O(n²) loops, wrong containers, algorithmic complexity
Memory	Peak memory, OOM, memory leaks, RSS reduction
Async	Concurrency, event loop blocking, sequential awaits, throughput/latency
Structure	Import time, circular deps, module reorganization for performance
Deep	Cross-domain optimization — profiles all domains and iterates until plateau

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
> /codeflash-optimize scan     # quick cross-domain diagnosis (no changes)
> /codeflash-optimize review   # review current changes or a PR

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.

Repo structure

packages/
  codeflash-core/              # shared foundation (models, AI client, telemetry, git)
  codeflash-python/            # Python language CLI — extends core
  codeflash-mcp/               # MCP server (stub)
  codeflash-lsp/               # LSP server (stub)

services/
  github-app/                  # GitHub App integration (FastAPI)

plugin/                        # Claude Code plugin (language-agnostic)
  .claude-plugin/              # plugin manifest & marketplace config
  agents/                      # review & research agents
  commands/                    # codex CLI integration commands
  hooks/                       # session lifecycle & review gate hooks
  references/shared/           # shared methodology & benchmarking guides

languages/python/plugin/       # Python-specific plugin content
  agents/                      # router, domain agents (cpu, memory, async, structure),
                               # deep, setup, scan, ci, pr-prep
  references/                  # domain-specific guides (async, memory, structure,
                               # data-structures, library replacement)
  skills/                      # /codeflash-optimize, memray profiling

vendor/
  codex/                       # OpenAI Codex runtime (vendored)

docs/                          # internal guides
evals/                         # eval templates & real-repo scenarios
dist/                          # assembled plugin (generated by make build-plugin)