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.

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 service

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)
  references/                  # domain-specific deep-dive guides
  skills/                      # /codeflash-optimize, memray profiling

vendor/
  codex/                       # OpenAI Codex runtime (vendored)

evals/                         # eval templates & real-repo scenarios