claude-devtools:chatgroup-architecture

# ChatGroup Architecture

How conversation data flows from raw JSONL messages to rendered chat groups.

## Core Design Principle

Chat groups are **independent items in a flat chronological list**, not paired turns.
There is no UserTurn/AITurn pairing — each group stands alone.

```typescript
// src/renderer/types/groups.ts
export type ChatItem =
  | { type: 'user'; group: UserGroup }
  | { type: 'system'; group: SystemGroup }
  | { type: 'ai'; group: AIGroup }
  | { type: 'compact'; group: CompactGroup };

export interface SessionConversation {
  sessionId: string;
  items: ChatItem[];  // Flat chronological list
  totalUserGroups: number;
  totalSystemGroups: number;
  totalAIGroups: number;
  totalCompactGroups: number;
}
```

## Pipeline Overview

```
Raw JSONL messages
  → MessageClassifier (classify into user/system/ai/hardNoise)
  → ChunkBuilder (buffer AI messages, flush on user/system boundary)
  → ChunkFactory (build EnhancedAIChunk with SemanticSteps)
  → groupTransformer (chunks → flat ChatItem[] conversation)
  → aiGroupEnhancer (AIGroup → EnhancedAIGroup with displayItems, linkedTools, lastOutput)
  → React components render
```

Primary source files:

- `src/main/services/parsing/MessageClassifier.ts`
- `src/main/services/analysis/ChunkBuilder.ts`
- `src/main/services/analysis/ChunkFactory.ts`
- `src/renderer/utils/groupTransformer.ts`
- `src/renderer/utils/aiGroupEnhancer.ts`
- `src/renderer/utils/displayItemBuilder.ts`
- `src/renderer/types/groups.ts`
- `src/main/types/chunks.ts`

## Data Models

### UserGroup

```typescript
// src/renderer/types/groups.ts
interface UserGroup {
  id: string;
  message: ParsedMessage;
  timestamp: Date;
  content: UserGroupContent;
  index: number;  // Ordering index within session
}

interface UserGroupContent {
  text?: string;                 // Plain text (commands removed)
  rawText?: string;              // Original text
  commands: CommandInfo[];       // Extracted /commands
  images: ImageData[];           // Attached images
  fileReferences: FileReference[]; // @file.ts mentions
}
```

Renders right-aligned blue bubble. Contains markdown text, slash commands, images, and file references.

### AIGroup

```typescript
interface AIGroup {
  id: string;
  turnIndex: number;             // 0-based (for turn navigation)
  startTime: Date;
  endTime: Date;
  durationMs: number;
  steps: SemanticStep[];         // Core semantic steps
  tokens: AIGroupTokens;
  summary: AIGroupSummary;       // For collapsed view
  status: AIGroupStatus;         // 'complete' | 'interrupted' | 'error' | 'in_progress'
  processes: Process[];          // Subagent processes
  chunkId: string;
  metrics: SessionMetrics;
  responses: ParsedMessage[];    // All assistant + internal messages
  isOngoing?: boolean;           // True for last group in ongoing session
}
```

### EnhancedAIGroup

The renderer enhances `AIGroup` before rendering:

```typescript
interface EnhancedAIGroup extends AIGroup {
  lastOutput: AIGroupLastOutput | null;      // Always-visible output
  displayItems: AIGroupDisplayItem[];        // Flattened chronological items
  linkedTools: Map<string, LinkedToolItem>;  // Tool call/result pairs
  itemsSummary: string;                      // "2 thinking, 4 tool calls, 3 subagents"
  mainModel: ModelInfo | null;
  subagentModels: ModelInfo[];
  claudeMdStats: ClaudeMdStats | null;
}
```

Enhancement happens in `src/renderer/utils/aiGroupEnhancer.ts`:

1. `findLastOutput` — extracts the final visible output (text, tool result, interruption, plan exit, ongoing)
2. `linkToolCallsToResults` — pairs tool calls with their results into `LinkedToolItem`
3. `buildDisplayItems` — flattens steps into chronological `AIGroupDisplayItem[]`
4. `buildSummary` — generates human-readable summary string
5. `extractMainModel` / `extractSubagentModels` — extracts model info

### AIGroupDisplayItem

```typescript
type AIGroupDisplayItem =
  | { type: 'thinking'; content: string; timestamp: Date; tokenCount?: number }
  | { type: 'tool'; tool: LinkedToolItem }
  | { type: 'subagent'; subagent: Process }
  | { type: 'output'; content: string; timestamp: Date; tokenCount?: number }
  | { type: 'slash'; slash: SlashItem }
  | { type: 'teammate_message'; teammateMessage: TeammateMessage };
```

Display items are sorted chronologically in `src/renderer/utils/displayItemBuilder.ts`.

### LinkedToolItem

```typescript
interface LinkedToolItem {
  id: string;
  name: string;
  input: Record<string, unknown>;
  callTokens?: number;
  result?: {
    content: string | unknown[];
    isError: boolean;
    toolUseResult?: ToolUseResultData;
    tokenCount?: number;
  };
  inputPreview: string;          // First 100 chars
  outputPreview?: string;        // First 200 chars
  startTime: Date;
  endTime?: Date;
  durationMs?: number;
  isOrphaned: boolean;           // No result received
  sourceModel?: string;
  skillInstructions?: string;    // For Skill tool calls
  skillInstructionsTokenCount?: number;
}
```

### AIGroupLastOutput

Always-visible output below the AI group header:

```typescript
interface AIGroupLastOutput {
  type: 'text' | 'tool_result' | 'interruption' | 'ongoing' | 'plan_exit';
  text?: string;
  toolName?: string;
  toolResult?: string;
  isError?: boolean;
  interruptionMessage?: string;
  planContent?: string;
  planPreamble?: string;
  timestamp: Date;
}
```

### SystemGroup

```typescript
interface SystemGroup {
  id: string;
  message: ParsedMessage;
  timestamp: Date;
  commandOutput: string;
  commandName?: string;
}
```

Renders left-aligned with neutral gray styling. Monospace pre with ANSI escape codes cleaned.

### CompactGroup

```typescript
interface CompactGroup {
  id: string;
  timestamp: Date;
  message: ParsedMessage;
  tokenDelta?: CompactionTokenDelta;
  startingPhaseNumber?: number;
}
```

Visual boundary for context compaction events.

## Backend: Chunk Building

### Message Classification

`src/main/services/parsing/MessageClassifier.