Building a macOS Agent Workbench with SwiftUI

#swift #swiftui #ai #macos

Across the previous seven articles plus a bonus chapter, we thoroughly explored the inner workings of Open Agent SDK — Agent Loop, the tool system, MCP integration, multi-Agent collaboration, conversation persistence, and multi-LLM support. The bonus chapter even embedded the SDK into a macOS native app, Motive, and ran it live.

But Motive was just a backend-swap experiment. The real question is: once you have the SDK, how do you build a complete Agent application from scratch? The SDK gives you the Agent's "brain" — but users don't see the Agent Loop; they see an interface. When the Agent is calling tools, reading files, and executing commands, users need to know what it's doing, how things are progressing, and what the results are.

That's the problem SwiftWork set out to solve — a macOS-native Agent visual workbench.

What is SwiftWork

SwiftWork is a macOS-native AI Agent desktop application. Its purpose in one sentence: let users see what the Agent is doing.

Specifically:

Users type a prompt in the input box
The Agent runs the Agent Loop in the background (calling tools, reading files, executing commands)
Every step is displayed in real time on a timeline — text output, tool calls, execution results, error messages, all visualized

This is not a CLI tool in a terminal, nor a web application. It's a native macOS app written in SwiftUI, using @observable for state management, SwiftData for data persistence, and Apple's native rendering pipeline for Markdown and code highlighting.

Why Build SwiftWork

There are two motivations behind SwiftWork.

First, the SDK needs a "showcase app." The SDK's 31 sample projects cover a wide range of use cases — streaming output, custom tools, MCP integration — but they are all command-line tools. The SDK's capabilities need a GUI to be fully demonstrated, especially things that CLI tools do poorly: tool call visualization, real-time event stream rendering, and so on.

Second, Agent application visualization is an underrated problem. Current Agent applications (including Claude Code itself) run in a terminal, where users see a scrolling stream of text. But when an Agent executes a complex task, it might call dozens of tools, read and write multiple files, and execute multiple commands. Linear terminal output makes it hard for users to understand the overall progress. SwiftWork attempts to address this with an event timeline and tool cards.

Architecture Overview

SwiftWork adopts an event-driven architecture. The entire data flow is a one-way pipeline:

SDK Agent Loop
  │
  │  AsyncStream<SDKMessage>
  ▼
AgentBridge (@Observable)
  │
  │  EventMapper.map() → AgentEvent
  ▼
AgentBridge.events: [AgentEvent]
  │
  │  SwiftUI auto-responds to @Observable changes
  ▼
TimelineView → EventViews

Four roles:

Component	Responsibility
Agent Loop	SDK provides, runs Agent inference loop, produces SDKMessage stream
AgentBridge	Consumes AsyncStream, maps to AgentEvent, manages lifecycle
EventMapper	Pure function, SDKMessage → AgentEvent type mapping
TimelineView	SwiftUI view, consumes AgentEvent array, renders timeline

Core design decision: views never directly touch SDK types. AgentEvent is SwiftWork's own UI model, completely decoupled from the SDK's SDKMessage. Views only know about AgentEvent — they neither know nor care which SDK version the events come from.

Core Data Flow

Here's what happens across the entire pipeline when a user sends a message:

1. User Input → Agent Starts

// AgentBridge.swift
func sendMessage(_ text: String) {
    // User message appended directly to event list
    let userEvent = AgentEvent(type: .userMessage, content: text, timestamp: .now)
    appendAndPersist(userEvent)

    isRunning = true

    // Consume stream in background Task
    currentTask = Task { [weak self] in
        let stream = agent.stream(text)
        for await message in stream {
            let event = EventMapper.map(message)
            self.appendAndPersist(event)
        }
        self.isRunning = false
    }
}

The user message is appended to the event list first (displayed immediately), then a Task is launched to consume the SDK's AsyncStream.

2. SDKMessage → AgentEvent

EventMapper is a pure function that maps the SDK's 18 SDKMessage types into SwiftWork's AgentEventType:

// EventMapper.swift
static func map(_ message: SDKMessage) -> AgentEvent {
    switch message {
    case .assistant(let data):
        return AgentEvent(type: .assistant, content: data.text,
            metadata: ["model": data.model, "stopReason": data.stopReason], timestamp: .now)
    case .toolUse(let data):
        return AgentEvent(type: .toolUse, content: data.toolName,
            metadata: ["toolName": data.toolName, "toolUseId": data.toolUseId, "input": data.input],
            timestamp: .now)
    case .toolResult(let data):
        return AgentEvent(type: .toolResult, content: data.content,
            metadata: ["toolUseId": data.toolUseId, "isError": data.isError], timestamp: .now)
    // ... 18 message types
    }
}

Why have this mapping layer? Because the SDK's types are designed for the Agent runtime and contain many details the UI doesn't need. AgentEvent retains only the fields needed for UI rendering: type, content, metadata, and timestamp. Views don't need to know the enum definition of SDKMessage — they only need to handle AgentEventType.

3. Event Append + Persistence

Every event goes through appendAndPersist, which simultaneously updates the in-memory array and the SwiftData database:

private func appendAndPersist(_ event: AgentEvent) {
    events.append(event)
    processToolContentMap(for: event)

    guard event.type != .partialMessage,
          let eventStore, let currentSession else { return }

    try eventStore.persist(event, session: currentSession, order: eventOrder)
    eventOrder += 1

    trimOldEvents()
}

Note that partialMessage is not persisted — it's an intermediate fragment of streaming text. Once accumulated, a complete .assistant event is generated.

4. SwiftUI Auto-Rendering

AgentBridge is marked with @observable. When the events array changes, TimelineView automatically re-renders:

// TimelineView.swift
ForEach(virtualizedEvents) { event in
    eventView(for: event)
}

eventView dispatches to different view components based on event.type — UserMessageView, AssistantMessageView, ToolCardView, SystemEventView, and so on.

Project Structure

SwiftWork/
├── App/
│   ├── SwiftWorkApp.swift            # @main entry, registers SwiftData models
│   └── ContentView.swift             # NavigationSplitView root view
├── Models/
│   ├── UI/                           # UI model layer
│   │   ├── AgentEvent.swift          # Event model (SwiftUI rendering)
│   │   ├── AgentEventType.swift      # 18 event type enum
│   │   ├── ToolContent.swift         # Tool content (pairs toolUse + toolResult)
│   │   ├── PermissionDecision.swift  # Permission decision
│   │   └── AppError.swift            # Error model
│   └── SwiftData/                    # Persistence model layer
│       ├── Session.swift             # Session
│       ├── Event.swift               # Persisted event
│       ├── AppConfiguration.swift    # App configuration
│       └── PermissionRule.swift      # Permission rule
├── ViewModels/
│   ├── SessionViewModel.swift        # Session CRUD
│   └── SettingsViewModel.swift       # Settings management
├── Views/
│   ├── Sidebar/                      # Session list
│   ├── Workspace/
│   │   ├── Timeline/
│   │   │   ├── TimelineView.swift    # Timeline main view + virtualization
│   │   │   ├── EventViews/           # Per-event-type views + ToolCardView
│   │   │   │   ├── ToolRenderers/    # 5 built-in tool renderers
│   │   │   │   ├── StreamingTextView.swift
│   │   │   │   ├── MarkdownContentView.swift
│   │   │   │   └── ...
│   │   │   └── Inspector/            # Event detail panel
│   │   └── InputBar/                 # Message input bar
│   ├── Settings/                     # Settings view
│   ├── Onboarding/                   # First-launch onboarding
│   └── Permission/                   # Permission approval dialog
├── SDKIntegration/
│   ├── AgentBridge.swift             # SDK ↔ ViewModel bridge
│   ├── AgentBridge+ToolContentMap.swift  # Tool content pairing logic
│   ├── EventMapper.swift             # SDKMessage → AgentEvent
│   ├── ToolRenderable.swift          # Tool rendering protocol
│   └── ToolRendererRegistry.swift    # Tool renderer registry
├── Services/
│   ├── CodeHighlighter.swift         # Splash code highlighting
│   ├── MarkdownRenderer.swift        # swift-markdown rendering
│   ├── KeychainManager.swift         # API Key secure storage
│   ├── EventStore.swift              # Event persistence interface
│   ├── AppStateManager.swift         # App state save/restore
│   └── TitleGenerator.swift          # Auto session title generation
└── Utils/
    └── Extensions/                   # Color, date formatting utilities

Key structural layers:

Models/UI/ and Models/SwiftData/ are two independent model layers. UI models (AgentEvent) are for SwiftUI rendering, SwiftData models (Event) are for persistence. There's conversion logic between them.
SDKIntegration/ is the bridge layer between SDK and UI. Views and ViewModels don't directly import OpenAgentSDK.
Views/ is organized by feature, with one view file per event type and a dedicated subdirectory for tool renderers.

Technology Choices

Component	Choice	Reason
Language	Swift 6.1 strict concurrency	Agent SDK requires it, Sendable ensures thread safety
UI	SwiftUI + @observable	macOS 14+ support, works well with Swift concurrency
Persistence	SwiftData	Deep SwiftUI integration, simpler than Core Data
Markdown	swift-markdown (Apple)	Native Apple library, CommonMark compatible
Code Highlighting	Splash (John Sundell)	Lightweight, supports Swift/Python/JS/Bash
Auto-update	Sparkle 2.x	Standard macOS app update solution
Agent SDK	Open Agent SDK	Built it ourselves, of course we use it

Series Preview

This article gave you the big picture. The following articles will unpack each subsystem:

Part 1: SDK Integration — how AgentBridge consumes AsyncStream, maps events, and manages lifecycle
Part 2: Event Timeline — visualizing 18 event types, streaming text, virtualization
Part 3: Tool Card — ToolRenderable protocol and extensible tool renderers
Part 4: Data Layer and Services — SwiftData persistence, state restore, Markdown rendering, code highlighting

Links: