# 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

```bash
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.