codeflash-agent/README.md

# 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 |
|--------|-------------|
| **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:

```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
> /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)
```