# qainsights/jmeter-ai architecture

> Architecture diagram of the GitHub repository qainsights/jmeter-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/qainsights/jmeter-ai
- Repository: https://github.com/qainsights/jmeter-ai
- Video tour (about a minute): https://gitdiagram.com/qainsights/jmeter-ai/video

## Overview

Feather Wand is a JMeter plugin that brings AI chat and test-plan operations into the JMeter GUI. Users submit context-aware prompts or invoke agent tools; provider services return responses, while agent handlers can inspect and modify the live plan or run tests. Separate workflows record browser traffic into a plan and identify/apply correlations. The README also describes refactoring, special commands, CLI terminal access, attachments, persistent conversations, model selection, and a companion pet. Paths reflect the supplied tree; unsampled subsystem wiring is shown only where documented capabilities establish it.

Main entry points: [`src/main/java/org/qainsights/jmeter/ai/gui/AiChatPanel.java`](https://github.com/qainsights/jmeter-ai/blob/main/src/main/java/org/qainsights/jmeter/ai/gui/AiChatPanel.java) (Chat panel), [`src/main/java/org/qainsights/jmeter/ai/service/AiService.java`](https://github.com/qainsights/jmeter-ai/blob/main/src/main/java/org/qainsights/jmeter/ai/service/AiService.java) (AI services), [`src/main/java/org/qainsights/jmeter/ai/agent/tool/handlers/ReadToolHandlers.java`](https://github.com/qainsights/jmeter-ai/blob/main/src/main/java/org/qainsights/jmeter/ai/agent/tool/handlers/ReadToolHandlers.java) (Plan tool handlers), [`src/main/java/org/qainsights/jmeter/ai/record/RecordingWorkflowService.java`](https://github.com/qainsights/jmeter-ai/blob/main/src/main/java/org/qainsights/jmeter/ai/record/RecordingWorkflowService.java) (Recording workflow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_chat["Chat and providers"]
  node_chatui["Chat panel<br/>[AiChatPanel.java]"]
  node_attachments["Attachments"]
  node_sessions[("Chat sessions")]
  node_services["AI services<br/>[AiService.java]"]
  node_terminal["AI CLI terminal"]
end

subgraph group_agent["Agent and plans"]
  node_agentui["Agent chat<br/>[AiChatPanel.java]"]
  node_agent["JMeter agent<br/>[JMeterAgent.java]"]
  node_loop["Agent loop<br/>[AgentLoop.java]"]
  node_registry["Tool registry"]
  node_handlers["Plan tool handlers"]
end

subgraph group_record["Browser recording"]
  node_recordui["Recording controls"]
  node_recordflow["Recording workflow"]
  node_browser["Browser session"]
  node_proxy["JMeter proxy"]
end

subgraph group_commands["Commands and correlation"]
  node_correlation["Correlation engine"]
  node_correlationui["Correlation review"]
  node_injector["Correlation injector"]
  node_commands["Plan commands"]
  node_refactor["Code refactoring"]
end

subgraph group_support["JMeter integrations"]
  node_jmeter["JMeter plan"]
  node_testcontrol["Test execution"]
  node_pet["Companion pet<br/>[PetBootstrap.java]"]
end

node_user(("JMeter user"))
node_llms(("LLM providers"))

node_user -->|"sends prompts"| node_chatui
node_chatui -->|"prepares files"| node_attachments
node_chatui -->|"requests responses"| node_services
node_services -->|"calls model APIs"| node_llms
node_services -->|"streams answers"| node_chatui
node_chatui -->|"saves conversations"| node_sessions
node_user -->|"opens terminal"| node_terminal
node_user -->|"requests plan edits"| node_agentui
node_agentui -->|"starts agent"| node_agent
node_agent -->|"runs turns"| node_loop
node_loop -->|"dispatches tools"| node_registry
node_registry -->|"executes tools"| node_handlers
node_handlers -->|"reads and edits"| node_jmeter
node_handlers -->|"runs or stops"| node_testcontrol
node_user -->|"starts recording"| node_recordui
node_recordui -->|"configures session"| node_recordflow
node_recordflow -->|"drives browser"| node_browser
node_browser -->|"requests planning"| node_llms
node_recordflow -->|"starts capture"| node_proxy
node_proxy -->|"records samplers"| node_jmeter
node_user -->|"requests analysis"| node_correlation
node_correlation -->|"presents candidates"| node_correlationui
node_correlationui -->|"applies selections"| node_injector
node_injector -->|"updates plan"| node_jmeter
node_user -->|"invokes commands"| node_commands
node_commands -->|"requests optimization"| node_services
node_user -->|"requests refactoring"| node_refactor
node_refactor -->|"requests code changes"| node_services
node_testcontrol -.->|"reports run status"| node_pet

click node_chatui "https://github.com/qainsights/jmeter-ai/blob/main/src/main/java/org/qainsights/jmeter/ai/gui/AiChatPanel.java"
click node_attachments "https://github.com/qainsights/jmeter-ai/blob/main/src/main/java/org/qainsights/jmeter/ai/service/attach/AttachmentRegistry.java"
click node_sessions "https://github.com/qainsights/jmeter-ai/blob/main/src/main/java/org/qainsights/jmeter/ai/service/session/ConversationStore.java"
click node_services "https://github.com/qainsights/jmeter-ai/blob/main/src/main/java/org/qainsights/jmeter/ai/service/AiService.java"
click node_terminal "https://github.com/qainsights/jmeter-ai/blob/main/src/main/java/org/qainsights/jmeter/ai/claudecode/ClaudeCodePanel.java"
click node_agentui "https://github.com/qainsights/jmeter-ai/blob/main/src/main/java/org/qainsights/jmeter/ai/gui/AiChatPanel.java"
click node_agent "https://github.com/qainsights/jmeter-ai/blob/main/src/main/java/org/qainsights/jmeter/ai/agent/JMeterAgent.java"
click node_loop "https://github.com/qainsights/jmeter-ai/blob/main/src/main/java/org/qainsights/jmeter/ai/agent/loop/AgentLoop.java"
click node_registry "https://github.com/qainsights/jmeter-ai/blob/main/src/main/java/org/qainsights/jmeter/ai/agent/tool/AgentToolRegistry.java"
click node_handlers "https://github.com/qainsights/jmeter-ai/blob/main/src/main/java/org/qainsights/jmeter/ai/agent/tool/handlers/ReadToolHandlers.java"
click node_testcontrol "https://github.com/qainsights/jmeter-ai/blob/main/src/main/java/org/qainsights/jmeter/ai/agent/jmeter/TestRunController.java"
click node_recordui "https://github.com/qainsights/jmeter-ai/blob/main/src/main/java/org/qainsights/jmeter/ai/record/RecordingControlPanel.java"
click node_recordflow "https://github.com/qainsights/jmeter-ai/blob/main/src/main/java/org/qainsights/jmeter/ai/record/RecordingWorkflowService.java"
click node_browser "https://github.com/qainsights/jmeter-ai/blob/main/src/main/java/org/qainsights/jmeter/ai/record/BrowserSession.java"
click node_proxy "https://github.com/qainsights/jmeter-ai/blob/main/src/main/java/org/qainsights/jmeter/ai/record/JMeterProxyRecorder.java"
click node_correlation "https://github.com/qainsights/jmeter-ai/blob/main/src/main/java/org/qainsights/jmeter/ai/correlation/CorrelationEngine.java"
click node_correlationui "https://github.com/qainsights/jmeter-ai/blob/main/src/main/java/org/qainsights/jmeter/ai/correlation/CorrelationReviewDialog.java"
click node_injector "https://github.com/qainsights/jmeter-ai/blob/main/src/main/java/org/qainsights/jmeter/ai/correlation/CorrelationInjector.java"
click node_commands "https://github.com/qainsights/jmeter-ai/blob/main/src/main/java/org/qainsights/jmeter/ai/optimizer/OptimizeRequestHandler.java"
click node_refactor "https://github.com/qainsights/jmeter-ai/blob/main/src/main/java/org/qainsights/jmeter/ai/service/CodeRefactorer.java"
click node_pet "https://github.com/qainsights/jmeter-ai/blob/main/src/main/java/org/qainsights/jmeter/ai/pet/PetBootstrap.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_chatui,node_attachments,node_sessions,node_services,node_terminal,node_user toneBlue
class node_agentui,node_agent,node_loop,node_registry,node_handlers toneAmber
class node_recordui,node_recordflow,node_browser,node_proxy toneMint
class node_correlation,node_correlationui,node_injector,node_commands,node_refactor toneRose
class node_jmeter,node_testcontrol,node_pet,node_llms toneIndigo
```

## Components

### Chat and providers

- [Chat panel](https://github.com/qainsights/jmeter-ai/blob/main/src/main/java/org/qainsights/jmeter/ai/gui/AiChatPanel.java): `src/main/java/org/qainsights/jmeter/ai/gui/AiChatPanel.java`
- [Attachments](https://github.com/qainsights/jmeter-ai/blob/main/src/main/java/org/qainsights/jmeter/ai/service/attach/AttachmentRegistry.java): `src/main/java/org/qainsights/jmeter/ai/service/attach/AttachmentRegistry.java`
- [Chat sessions](https://github.com/qainsights/jmeter-ai/blob/main/src/main/java/org/qainsights/jmeter/ai/service/session/ConversationStore.java): `src/main/java/org/qainsights/jmeter/ai/service/session/ConversationStore.java`
- [AI services](https://github.com/qainsights/jmeter-ai/blob/main/src/main/java/org/qainsights/jmeter/ai/service/AiService.java): `src/main/java/org/qainsights/jmeter/ai/service/AiService.java`
- [AI CLI terminal](https://github.com/qainsights/jmeter-ai/blob/main/src/main/java/org/qainsights/jmeter/ai/claudecode/ClaudeCodePanel.java): `src/main/java/org/qainsights/jmeter/ai/claudecode/ClaudeCodePanel.java`

### Agent and plans

- [Agent chat](https://github.com/qainsights/jmeter-ai/blob/main/src/main/java/org/qainsights/jmeter/ai/gui/AiChatPanel.java): `src/main/java/org/qainsights/jmeter/ai/gui/AiChatPanel.java`
- [JMeter agent](https://github.com/qainsights/jmeter-ai/blob/main/src/main/java/org/qainsights/jmeter/ai/agent/JMeterAgent.java): `src/main/java/org/qainsights/jmeter/ai/agent/JMeterAgent.java`
- [Agent loop](https://github.com/qainsights/jmeter-ai/blob/main/src/main/java/org/qainsights/jmeter/ai/agent/loop/AgentLoop.java): `src/main/java/org/qainsights/jmeter/ai/agent/loop/AgentLoop.java`
- [Tool registry](https://github.com/qainsights/jmeter-ai/blob/main/src/main/java/org/qainsights/jmeter/ai/agent/tool/AgentToolRegistry.java): `src/main/java/org/qainsights/jmeter/ai/agent/tool/AgentToolRegistry.java`
- [Plan tool handlers](https://github.com/qainsights/jmeter-ai/blob/main/src/main/java/org/qainsights/jmeter/ai/agent/tool/handlers/ReadToolHandlers.java): `src/main/java/org/qainsights/jmeter/ai/agent/tool/handlers/ReadToolHandlers.java`

### Browser recording

- [Recording controls](https://github.com/qainsights/jmeter-ai/blob/main/src/main/java/org/qainsights/jmeter/ai/record/RecordingControlPanel.java): `src/main/java/org/qainsights/jmeter/ai/record/RecordingControlPanel.java`
- [Recording workflow](https://github.com/qainsights/jmeter-ai/blob/main/src/main/java/org/qainsights/jmeter/ai/record/RecordingWorkflowService.java): `src/main/java/org/qainsights/jmeter/ai/record/RecordingWorkflowService.java`
- [Browser session](https://github.com/qainsights/jmeter-ai/blob/main/src/main/java/org/qainsights/jmeter/ai/record/BrowserSession.java): `src/main/java/org/qainsights/jmeter/ai/record/BrowserSession.java`
- [JMeter proxy](https://github.com/qainsights/jmeter-ai/blob/main/src/main/java/org/qainsights/jmeter/ai/record/JMeterProxyRecorder.java): `src/main/java/org/qainsights/jmeter/ai/record/JMeterProxyRecorder.java`

### Commands and correlation

- [Correlation engine](https://github.com/qainsights/jmeter-ai/blob/main/src/main/java/org/qainsights/jmeter/ai/correlation/CorrelationEngine.java): `src/main/java/org/qainsights/jmeter/ai/correlation/CorrelationEngine.java`
- [Correlation review](https://github.com/qainsights/jmeter-ai/blob/main/src/main/java/org/qainsights/jmeter/ai/correlation/CorrelationReviewDialog.java): `src/main/java/org/qainsights/jmeter/ai/correlation/CorrelationReviewDialog.java`
- [Correlation injector](https://github.com/qainsights/jmeter-ai/blob/main/src/main/java/org/qainsights/jmeter/ai/correlation/CorrelationInjector.java): `src/main/java/org/qainsights/jmeter/ai/correlation/CorrelationInjector.java`
- [Plan commands](https://github.com/qainsights/jmeter-ai/blob/main/src/main/java/org/qainsights/jmeter/ai/optimizer/OptimizeRequestHandler.java): `src/main/java/org/qainsights/jmeter/ai/optimizer/OptimizeRequestHandler.java`
- [Code refactoring](https://github.com/qainsights/jmeter-ai/blob/main/src/main/java/org/qainsights/jmeter/ai/service/CodeRefactorer.java): `src/main/java/org/qainsights/jmeter/ai/service/CodeRefactorer.java`

### JMeter integrations

- **JMeter plan**
- [Test execution](https://github.com/qainsights/jmeter-ai/blob/main/src/main/java/org/qainsights/jmeter/ai/agent/jmeter/TestRunController.java): `src/main/java/org/qainsights/jmeter/ai/agent/jmeter/TestRunController.java`
- [Companion pet](https://github.com/qainsights/jmeter-ai/blob/main/src/main/java/org/qainsights/jmeter/ai/pet/PetBootstrap.java): `src/main/java/org/qainsights/jmeter/ai/pet/PetBootstrap.java`

### Other components

- **JMeter user**
- **LLM providers**

## Connections

- JMeter user → Chat panel: sends prompts
- Chat panel → Attachments: prepares files
- Chat panel → AI services: requests responses
- AI services → LLM providers: calls model APIs
- AI services → Chat panel: streams answers
- Chat panel → Chat sessions: saves conversations
- JMeter user → AI CLI terminal: opens terminal
- JMeter user → Agent chat: requests plan edits
- Agent chat → JMeter agent: starts agent
- JMeter agent → Agent loop: runs turns
- Agent loop → Tool registry: dispatches tools
- Tool registry → Plan tool handlers: executes tools
- Plan tool handlers → JMeter plan: reads and edits
- Plan tool handlers → Test execution: runs or stops
- JMeter user → Recording controls: starts recording
- Recording controls → Recording workflow: configures session
- Recording workflow → Browser session: drives browser
- Browser session → LLM providers: requests planning
- Recording workflow → JMeter proxy: starts capture
- JMeter proxy → JMeter plan: records samplers
- JMeter user → Correlation engine: requests analysis
- Correlation engine → Correlation review: presents candidates
- Correlation review → Correlation injector: applies selections
- Correlation injector → JMeter plan: updates plan
- JMeter user → Plan commands: invokes commands
- Plan commands → AI services: requests optimization
- JMeter user → Code refactoring: requests refactoring
- Code refactoring → AI services: requests code changes
- Test execution → Companion pet: reports run status