codeflash-agent/plugin

Plugin Architecture

The codeflash plugin is a multi-language Claude Code plugin for autonomous performance optimization.

Session Flow

/codeflash-optimize start
  └─ Skill asks user for context (AskUserQuestion)
  └─ Skill launches language router (FOREGROUND, run_in_background: false)
       └─ Router runs setup agent (waits for completion)
       └─ Router reads CLAUDE.md, library research, etc.
       └─ Router creates team: TeamCreate("codeflash-session")
       └─ Router creates tasks: TaskCreate("Setup", "Baseline", "Experiment loop")
       └─ Router launches optimizer (BACKGROUND, run_in_background: true)
       └─ Router STAYS ALIVE coordinating:
            ├─ Receives [baseline], [progress], [experiment] via SendMessage
            ├─ Relays progress directly to user (foreground output)
            ├─ Handles [complete] → cleanup, changelog, TeamDelete
            └─ Returns result to skill when session ends

The skill launches the language router in the foreground so its progress output streams directly to the user. The router launches the optimizer in the background as a named teammate and stays alive to coordinate via SendMessage. This is the Team Lead + Specialists pattern — the router is the team lead, the optimizer and any domain agents are specialists.

Agent Hierarchy

Tier 1: Top Router (plugin/agents/codeflash.md)
         └─ Detects language, delegates immediately

Tier 2: Language Router / Team Lead
         ├─ codeflash-python      (plugin/languages/python/agents/)
         ├─ codeflash-javascript  (plugin/languages/javascript/agents/)
         ├─ codeflash-java        (plugin/languages/java/agents/)
         └─ codeflash-go          (plugin/languages/go/agents/)
         Tools: TeamCreate, TeamDelete, Agent, SendMessage, TaskCreate/Update

Tier 3: Deep Agent / Sub-Team Lead
         ├─ codeflash-deep       (Python)
         ├─ codeflash-js-deep    (JavaScript)
         ├─ codeflash-java-deep  (Java/Kotlin)
         └─ codeflash-deep       (Go overlay)
         Tools: TeamCreate, Agent, SendMessage (can dispatch domain specialists)

Tier 4: Domain Specialists
         ├─ cpu, memory, async, structure    (Python)
         └─ cpu, memory, async, structure, bundle (JavaScript)
         Tools: SendMessage only (report to parent, no team authority)

Shared (language-agnostic):
         ├─ codeflash-researcher  (read-only, parallel investigation)
         └─ codeflash-review      (standalone or post-session gate)

File Layout

Language-agnostic (base)

• agents/codeflash.md — language router that detects the project language and delegates
• agents/codeflash-review.md — review agent (works on any language)
• agents/codeflash-researcher.md — research agent (works on any language)
• commands/ — codex CLI commands
• vendor/codex/ — codex companion scripts and schemas (vendored)
• references/shared/ — shared methodology (experiment loop, templates, benchmarks)
• hooks/ — session lifecycle and review gate hooks

Python (languages/python/)

• agents/codeflash-python.md — Python domain router (Team Lead)
• agents/codeflash-deep.md — primary optimizer (profiles all dimensions jointly)
• agents/codeflash-cpu.md, -memory.md, -async.md, -structure.md — one agent per domain
• agents/codeflash-setup.md — detects project env, installs deps
• agents/codeflash-scan.md, -ci.md, -pr-prep.md — scan, CI, and PR preparation
• skills/ — /codeflash-optimize entry point, memray profiling
• references/ — Python-specific protocol implementations + domain deep-dive docs

JavaScript (languages/javascript/)

• agents/codeflash-javascript.md — JS/TS domain router (Team Lead)
• agents/codeflash-js-deep.md — primary optimizer (profiles all dimensions jointly)
• agents/codeflash-js-cpu.md, -memory.md, -async.md, -structure.md, -bundle.md — one agent per domain (5 domains)
• agents/codeflash-js-setup.md — detects runtime/package manager, installs deps
• agents/codeflash-js-scan.md, -ci.md, -pr-prep.md — scan, CI, and PR preparation
• skills/ — /codeflash-optimize entry point, V8 profiling reference
• references/ — JS-specific references (Prisma performance, domain deep-dives)

Java/Kotlin (languages/java/)

• agents/codeflash-java.md — Java/Kotlin domain router (Team Lead)
• agents/codeflash-java-deep.md — primary optimizer (JFR/JMH, CPU, memory, GC, concurrency)
• agents/codeflash-java-cpu.md, -memory.md, -async.md, -structure.md — domain specialists
• agents/codeflash-java-setup.md — detects Maven/Gradle, JDK, JMH, representative workloads
• agents/codeflash-java-scan.md, -ci.md, -pr-prep.md — scan, CI, and PR preparation
• skills/ — /codeflash-optimize entry point and JFR profiling reference
• references/ — Java-specific JFR/JMH, E2E benchmarking, data-structure, memory, async, I/O, and worker guides

Adding a New Language

Follow this template — Team Lead + Deep Agent are required, domain specialists are added as needed:

Component	Required?	Role
codeflash-<lang>	Yes	Language Router / Team Lead (TeamCreate, Agent, SendMessage)
codeflash-<lang>-deep	Yes	Primary optimizer / Sub-Team Lead (TeamCreate, Agent, SendMessage)
codeflash-<lang>-setup	Yes	Environment setup utility (one-off, no team membership)
codeflash-<lang>-cpu	As needed	CPU/algorithm specialist (SendMessage only)
codeflash-<lang>-memory	As needed	Memory specialist (SendMessage only)
codeflash-<lang>-async	As needed	Concurrency specialist (SendMessage only)
codeflash-<lang>-structure	As needed	Module/import specialist (SendMessage only)
Language-specific domains	As needed	e.g., bundle for JS, compile for Go/Rust
codeflash-<lang>-scan	Optional	Quick diagnostic (one-off)
codeflash-<lang>-ci	Optional	CI webhook handler
codeflash-<lang>-pr-prep	Optional	PR preparation

Shared agents (codeflash-researcher, codeflash-review) work across all languages.

Build

powershell -ExecutionPolicy Bypass -File scripts/build_plugin.ps1  # Windows
python scripts/build_plugin.py                                      # Python alternative
make clean                         # remove dist-* plugin builds

Each build produces single-language plugin directories (dist-python/, dist-javascript/, dist-java/, etc.). scripts/build_plugin.ps1 and scripts/build_plugin.py copy language-agnostic files from plugin/, overlay plugin/languages/<LANG>/ (agents, references, skills), and rewrite internal paths so everything is flat. Install the built dist-java/ plugin for Java/Kotlin work so Claude Code sees one /codeflash-optimize skill and the Java agent set without duplicate language-specific skill names.