codeflash-agent/plugin/README.md

# 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/)
         Tools: TeamCreate, TeamDelete, Agent, SendMessage, TaskCreate/Update

Tier 3: Deep Agent / Sub-Team Lead
         ├─ codeflash-deep     (Python)
         └─ codeflash-js-deep  (JavaScript)
         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)

## 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
make build-plugin                  # default: LANG=python → dist/ is a Python-only plugin
make build-plugin LANG=javascript  # dist/ is a JavaScript-only plugin
make clean                         # remove dist/
```

Each build produces a **single-language plugin** in `dist/`. The Makefile copies language-agnostic files from `plugin/`, overlays `plugin/languages/<LANG>/` (agents, references, skills), and rewrites internal paths so everything is flat. You pick the language at build time — there is no multi-language dist yet, because loading all languages at once is extremely heavy on context and compute.