Core Data Models

Relevant source files

The following files were used as context for generating this wiki page:

• buddi/Buddi/Models/ChatMessage.swift
• buddi/Buddi/Models/ToolResultData.swift
• buddi/Buddi/Services/Session/ConversationParser.swift
• buddi/Buddi/Services/State/SessionStore.swift
• [buddi/MediaControllers/YouTube Music Controller/YouTubeMusicModels.swift](https://github.com/talkvalue/Buddi/blob/HEAD/buddi/MediaControllers/YouTube Music Controller/YouTubeMusicModels.swift)
• buddi/Buddi/Buddy/BuddyDetector.swift
• buddi/Buddi/Services/Shared/UsageService.swift

Core Data Models in the Buddi project provide the structural foundation for monitoring and interacting with Claude Code sessions. These models facilitate the parsing of complex JSONL event streams into actionable UI states, representing conversation history, tool executions, and system-level metadata.

The system relies on a central state management architecture where tool results, chat messages, and session lifecycle events are strictly typed to ensure predictable behavior across the macOS notch interface and the detailed chat view.

Conversation and Messaging Models

Buddi represents conversations as a series of strictly typed messages and blocks. Instead of simple strings, messages are composed of multiple block types to handle text, tool usage, and the model's "thinking" process.

Chat Architecture

The ChatMessage model serves as the primary unit of the conversation history. It aggregates MessageBlock types that represent different phases of the LLM's output or user input.

Model Field Definitions

Model	Field	Type	Description
ChatMessage	role	ChatRole	Identifies message as user, assistant, or system.
ToolUseBlock	name	String	The identifier of the Claude tool (e.g., "Read", "Bash").
ToolUseBlock	input	[String: String]	Key-value pairs of parameters passed to the tool.

Sources: buddi/Buddi/Models/ChatMessage.swift:29-66

Tool Execution and Results

The project utilizes an extensive set of structured data models to capture the output of various developer tools executed by Claude Code. These range from filesystem operations to web searches and subagent tasks.

Structured Tool Results

The ToolResultData enum wraps specific structs for each tool type, allowing the ConversationParser to map raw JSON results into type-safe objects.

Key Result Structures

• ReadResult: Captures file content, path, and line range information.
• EditResult: Handles file modifications, including optional PatchHunk data for diff rendering.
• BashResult: Captures standard output (stdout), error output (stderr), and background task identifiers.
• TaskResult: Represents subagent (agentic) operations, including token usage and total tool call counts.

Sources: buddi/Buddi/Models/ToolResultData.swift:35-120

Session and State Management

Sessions are managed centrally in the SessionStore, which acts as the single source of truth for the application state. It processes events like permission requests, hook receptions, and file updates.

Session Lifecycle and State

The SessionStore maintains an internal dictionary of SessionState objects. It is responsible for reconciling incremental updates from the ConversationParser with the live UI state.

System Metadata and External Integrations

Beyond conversation data, the project models system-level information such as API usage, user identity for "Buddy" generation, and media playback state.

Usage and Quota Models

The UsageService tracks Claude Code utilization across different time intervals.

Structure	Field	Type	Description
UsageData	fiveHour	QuotaPeriod?	Quota status for the 5-hour window.
UsageData	sevenDay	QuotaPeriod?	Quota status for the 7-day window.
QuotaPeriod	utilization	Double	Percentage (0-100) of quota consumed.

Sources: buddi/Buddi/Services/Shared/UsageService.swift:9-20

Identity and Appearance

The BuddyDetector uses a deterministic hashing algorithm (Wyhash) to generate a BuddyIdentity based on the user's system ID.

Summary

The Core Data Models of Buddi create a robust bridge between the asynchronous, text-heavy world of terminal-based AI tools and a reactive macOS GUI. By categorizing events into ChatMessage, ToolResultData, and SessionState, the project ensures that even complex developer workflows—such as multi-file edits or nested subagent tasks—can be monitored and controlled with high technical accuracy.