108 lines
5.8 KiB
Markdown
108 lines
5.8 KiB
Markdown
# 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.
|