build-swiftui-app

Build SwiftUI App With SwiftASB

SwiftData And SwiftUI Rule

When a task combines SwiftData with SwiftUI, keep SwiftData directly coupled to SwiftUI through Apple's data-driven path: modelContainer, environment modelContext, @Query, SwiftData model objects, and bindings. Do not add repositories, stores, service layers, DTO mirrors, view-model caches, wrapper objects, or other abstraction layers between SwiftData and SwiftUI. If this skill is not the right owner for SwiftData-backed SwiftUI work, hand off to apple-dev-skills:swiftui-app-architecture-workflow instead of inventing an intermediate data layer.

Purpose

Help a SwiftUI app use SwiftASB to start Codex work, show live progress, expose plan and goal state, handle approvals or user input, list stored threads, archive or unarchive stored threads, inspect app-server-owned worktree, selected Git status, project identity, thread source, filesystem/config/extension/MCP/workspace facts, observe SwiftASB-owned feature operations, expose app-wide inventory, and expose recent thread history without replaying raw app-server protocol payloads into app state.

The real job is to connect SwiftUI views to SwiftASB's Swift-native handles and observable companions. SwiftUI owns view lifetime and rendering. SwiftASB owns the local Codex app-server process, app-wide library and inventory companions, thread agenda companions, stable worktree groups, repository/worktree filters, selected-worktree Git status, project identity and thread-source facts, app-server-owned worktree snapshots, app-server-routed filesystem/config/extension/MCP reads, workspace permission facts, feature policy, feature-operation events, plan-mode turn starts, goal helpers, review and shell-command entry points, thread, agenda, and turn handles, typed events, request responses, diagnostics, and recent-history companions.

Keep the shown workspace model at the app or scene ownership boundary; it is not a reusable-view dependency. Reusable SwiftUI panels receive the specific values, bindings, and action closures they need. Prefer existing or deliberately custom environment values/actions for genuine hierarchy-wide capabilities, and do not reintroduce a ViewModel, store, coordinator, or service injection layer below that boundary.

Required Documentation Gate

Before implementing or proposing SwiftUI structure, read the relevant Apple documentation through Apple Dev Skills or official Apple docs.

Minimum rules to rely on:

• SwiftUI @State is view-managed storage, and SwiftUI updates dependent views when the value changes.
• SwiftUI can store @Observable objects in @State; subviews update when they read changed observable properties.
• SwiftUI app structure is built from an App whose body provides one or more Scene values.
• Observation support should come from the @Observable macro rather than bare Observable protocol conformance.

Authoritative docs:

• SwiftUI State
• SwiftUI App
• SwiftUI Scene
• Observation Observable macro

When To Use

• Use this skill when a SwiftUI app needs a SwiftASB-backed feature.
• Use this skill after swiftasb:choose-integration-shape selects a SwiftUI app shape.
• Use this skill when a SwiftUI app needs live Codex progress, approvals, diagnostics, recent turns, recent files, or recent commands.
• Use this skill for refactors that move a SwiftUI app away from raw JSON-RPC or ad hoc event replay and toward SwiftASB companions.

Source Check

Verify current SwiftASB docs and public API before editing:

• SwiftASB GitHub repository
• Sources/SwiftASB/SwiftASB.docc/GettingStartedWithSwiftASB.md
• Sources/SwiftASB/SwiftASB.docc/SwiftUIObservableCompanions.md
• Sources/SwiftASB/SwiftASB.docc/ThreadHistoryAndObservables.md
• Sources/SwiftASB/SwiftASB.docc/HandlingTurnProgressAndApprovals.md
• Sources/SwiftASB/SwiftASB.docc/AppWideCapabilities.md
• Sources/SwiftASB/SwiftASB.docc/CodexInventory.md
• Sources/SwiftASB/SwiftASB.docc/CodexMCP.md
• Sources/SwiftASB/SwiftASB.docc/CodexFS.md
• Sources/SwiftASB/SwiftASB.docc/CodexConfig.md
• Sources/SwiftASB/SwiftASB.docc/CodexExtensions.md
• Sources/SwiftASB/SwiftASB.docc/CodexWorkspace.md
• Sources/SwiftASB/SwiftASB.docc/FeaturePermissionPolicy.md
• Sources/SwiftASB/SwiftASB.docc/ThreadManagement.md
• Sources/SwiftASB/Public/CodexAppServer+Library.swift
• Sources/SwiftASB/Public/CodexAppServer+Inventory.swift
• Sources/SwiftASB/Public/CodexAppServer+LoadedThreads.swift
• Sources/SwiftASB/Public/CodexAppServer+CodexExtensions.swift
• Sources/SwiftASB/Public/CodexAppServer+MCP.swift
• Sources/SwiftASB/Public/CodexMCP.swift
• Sources/SwiftASB/Public/CodexFS.swift
• Sources/SwiftASB/Public/CodexConfig.swift
• Sources/SwiftASB/Public/CodexWorkspace.swift
• Sources/SwiftASB/Public/CodexAppServer+Bootstrap.swift
• Sources/SwiftASB/Public/CodexAppServer.swift
• Sources/SwiftASB/Public/CodexDiagnostics.swift
• Sources/SwiftASB/Public/CodexErrors.swift
• Sources/SwiftASB/Public/CodexReviewHandle.swift
• Sources/SwiftASB/Public/CodexThread.swift
• Sources/SwiftASB/Public/CodexThread+Dashboard.swift
• Sources/SwiftASB/Public/CodexThread+Agenda.swift
• Sources/SwiftASB/Public/CodexTurnHandle.swift

As of SwiftASB v1.8.0, SwiftUI-facing integrations should prefer:

• CodexAppServer.start(_:) with CodexAppServer.StartupRequest for normal one-call startup, compatibility validation, initialization, and typed CodexAppServerStartupError failures
• lower-level CodexAppServer.start(), cliExecutableDiagnostics(), and initialize(_:) only when the app intentionally owns custom diagnostics, compatibility policy, or test setup before initialization
• CodexAppServer for process ownership, diagnostics, thread creation, stored-thread operations, feature-operation-event streams, and app-wide capability reads
• CodexAppServer.makeLibrary(configuration:) for app-wide stored-thread lists, cwd or repository grouping, stable worktree groups, repository/worktree filters, selected worktree or repository context, selected-worktree Git status, library-local selection, CodexWorkspace.ProjectInfo project identity, CodexAppServer.ThreadSource source badges, and model/MCP/hook snapshots that refresh when app-server app/skill/MCP state changes
• CodexAppServer.makeInventory(configuration:) for routine app-wide model capabilities, global MCP summaries, hook diagnostics, apps, skills, plugins, and collaboration modes
• CodexAppServer.fs, CodexAppServer.config, and CodexAppServer.extensions for app-server-owned file metadata, directory/file reads, file discovery with match metadata, effective config, advanced extension pagination, plugin detail reads, and already-configured marketplace upgrades
• CodexAppServer.mcp for MCP server installs, full status snapshots, and app-wide or thread-scoped MCP resource contents
• SwiftASBFeaturePolicy for feature-category defaults and host app authority, with gitObservability, extensionInventory, and extensionMaintenance enabled by default and mutation-oriented categories disabled until the app opts in
• CodexAppServer.featureOperationEvents() for human-readable SwiftASB-owned mutation records, such as marketplace maintenance attempts
• CodexWorkspace for session cwd, app-server-owned worktree snapshots, project identity, Git repository facts, selected Git status snapshots, active permission profile, and runtime filesystem/network permission facts
• CodexThread for conversation-scoped text turns, plan-mode turns, request routing, archive/unarchive, thread actions, thread goals, and local history
• CodexThread.startReview(against:placement:) for code-review UI, and CodexThread.sendShellCommand(_:) only for explicit user-level shell actions when shellCommandExecution is enabled
• CodexTurnHandle for one active turn, including events, steering, interruption, request responses, and completion handoff
• CodexThread.makeDashboard() for thread-level current state
• CodexThread.makeAgenda() for current goal state, accepted plan snapshots, proposed plan text, and summary titles
• CodexThread.startPlanningTurn(...) and CodexAppServer.TurnCollaborationMode.plan(...) for explicit plan-mode UI controls
• CodexTurnHandle.minimap for active-turn current state
• CodexTurnItem.Kind.sleep when custom turn-history or minimap-adjacent UI switches over public turn item kinds
• CodexThread.makeRecentTurns(...), makeRecentFiles(...), and makeRecentCommands(...) for local history views
• CodexAppServer.ThreadListQD, CodexFS.FileDiscoveryQD, CodexThread.HistoryWindowQD, CodexThread.RecentFilesQD, and CodexThread.RecentCommandsQD when SwiftUI state needs repeatable query intent
• optional ASBPresentation, ASBAppKit, and ASBSwiftUI products when the app wants ready-made sidebar, agenda, or dashboard panels over SwiftASB presentation snapshots

Implementation Workflow

1. Confirm the app's existing SwiftUI state pattern.
2. Read Apple docs for the framework behavior the change relies on.
3. Add SwiftASB as a package dependency only if it is not already present:
   • package URL: https://github.com/gaelic-ghost/SwiftASB
   • minimum version: 1.8.0 when using current one-call startup, Codex CLI 0.142.x compatibility, app-wide library or inventory, stable worktree groups, repository/worktree filters, selected-worktree Git status, feature policy, feature-operation events, extension marketplace maintenance, project identity, thread source, filesystem match metadata, MCP installs/status/resource reads, config warnings, extension inventory, workspace, query-descriptor, thread archive/unarchive, code-review starts, shell-command execution, plan/goal UI, sleep turn-item classification, presentation products, or recent-activity guidance; otherwise verify the support window in SwiftASB's README
   • product: SwiftASB
   • optional products: ASBPresentation, ASBAppKit, and ASBSwiftUI when the app uses SwiftASB's reusable presentation snapshots or native UI panels
4. Choose the owner object:
   • app-wide model owns CodexAppServer
   • app-wide, scene, or workspace model owns CodexAppServer.Library when the UI needs stored-thread lists before a thread is selected
   • workspace, document, or conversation model owns CodexThread
   • active-turn method or model owns CodexTurnHandle
5. Start the app-server from an explicit async entrypoint, using appServer.start(_:) for normal clients and the lower-level start() plus initialize(_:) sequence only for custom diagnostics or tests.
6. Create or resume a thread through CodexAppServer.
7. Create CodexAppServer.Library from the app server when the UI has a launcher, sidebar, project browser, or app-wide diagnostics surface.
8. Use appServer.fs, appServer.config, appServer.makeInventory(configuration:), appServer.extensions, appServer.mcp, CodexWorkspace, and SwiftASBFeaturePolicy when SwiftUI needs filesystem, config, plugin/skill/app, collaboration-mode, marketplace-maintenance, MCP resource or install state, worktree, selected Git status, project identity, thread source, permission facts, or feature-category choices from Codex.
9. Create observable companions from the thread and current turn, including makeAgenda() when the UI shows goals or plans.
10. Render state from companions directly where possible.
11. Route approval and elicitation responses through the owning CodexTurnHandle or CodexThread.
12. Make startup, compatibility, turn, approval, cancellation, and shutdown errors human-readable.
13. Validate with the repository's documented SwiftPM or Xcode path.

State Ownership Pattern

Prefer one app-facing model that makes ownership visible:

import Observation
import SwiftASB

@MainActor
@Observable
final class CodexWorkspaceModel {
    private let appServer = CodexAppServer()

    var inventory: CodexAppServer.Inventory?
    var library: CodexAppServer.Library?
    var thread: CodexThread?
    var dashboard: CodexThread.Dashboard?
    var agenda: CodexThread.Agenda?
    var currentMinimap: CodexTurnHandle.Minimap?
    var errorMessage: String?

    func start(workspacePath: String) async {
        do {
            let session = try await appServer.start(
                .init(
                    clientInfo: .init(
                        name: "ExampleApp",
                        title: "Example App",
                        version: "1.0.0"
                    )
                )
            )
            _ = session.cliExecutableDiagnostics

            inventory = try await appServer.makeInventory(
                configuration: .init(
                    hookListCurrentDirectoryPaths: [workspacePath],
                    extensionCurrentDirectoryPaths: [workspacePath]
                )
            )
            let thread = try await appServer.startThread(
                .init(currentDirectoryPath: workspacePath)
            )
            self.thread = thread
            library = try await appServer.makeLibrary(
                configuration: .init(
                    sortedBy: .turnFinishedNewestFirst,
                    groupedBy: .repository,
                    query: .unarchived(limit: 30),
                    mcpServerStatusRequest: .init(detail: .toolsAndAuthOnly)
                )
            )
            dashboard = await thread.makeDashboard()
            agenda = try await thread.makeAgenda()
        } catch {
            errorMessage = "SwiftASB could not start the local Codex runtime: \(error)"
        }
    }

    func refreshAppSnapshots() async {
        await inventory?.refresh()
        await library?.refreshAppSnapshots()
    }

    func selectThread(_ threadID: String?) {
        library?.selectThread(threadID)
    }

    func plan(_ prompt: String) async {
        guard let thread else {
            errorMessage = "SwiftASB cannot start a planning turn before a thread exists."
            return
        }

        do {
            let turn = try await thread.startPlanningTurn(prompt)
            currentMinimap = turn.minimap

            for try await event in turn.events {
                if case .completed = event {
                    _ = try await turn.complete()
                    currentMinimap = nil
                    return
                }
            }
        } catch {
            errorMessage = "SwiftASB planning turn failed before completion: \(error)"
        }
    }

    func run(_ prompt: String) async {
        guard let thread else {
            errorMessage = "SwiftASB cannot start a turn before a thread exists."
            return
        }

        do {
            let turn = try await thread.startTextTurn(prompt)
            currentMinimap = turn.minimap

            for try await event in turn.events {
                if case .completed = event {
                    _ = try await turn.complete()
                    currentMinimap = nil
                    return
                }
            }
        } catch {
            errorMessage = "SwiftASB turn failed before completion: \(error)"
        }
    }

    func stop() async {
        await appServer.stop()
    }
}

Use this as a shape, not as a file to paste blindly. Match the app's real lifetime, error model, and UI needs.

UI Guidance

• Show CodexAppServerStartupError startup and compatibility failures before offering turn controls.
• Disable same-thread turn controls while one turn is active, or create a separate thread when concurrent work is truly intended.
• Use inventory for routine app-wide model capabilities, global MCP summaries, hook diagnostics, apps, skills, plugins, and collaboration modes.
• Use library for stored-thread sidebars, cwd or repository grouping, stable worktree groups, repository/worktree filters, selected worktree or repository context, selected Git status, project identity display, thread-source badges, library-local selection, app-wide model capabilities, MCP server status, and hook diagnostics.
• Show library.selectedGitStatus, lastGitStatusReadAt, and latestGitStatusErrorDescription when a selected-worktree status panel needs branch, SHA, remotes, dirty/untracked counts, or refresh failures.
• Use CodexAppServer.ThreadListQD when the same sidebar query should drive both direct listThreads reads and library loading.
• Use CodexAppServer.fs and CodexFS.FileDiscoveryQD for sandbox-safe file pickers, metadata panes, directory browsers, file-byte previews, watches, highlighted matches, and ranking explanations.
• Use CodexAppServer.mcp when the UI needs to install MCP servers, show full MCP details, or show text/blob resource contents advertised by a configured MCP server.
• Use CodexAppServer.config, CodexAppServer.extensions, and CodexWorkspace for diagnostics views that show effective config, requirements, advanced extension detail, marketplace maintenance, worktree snapshots, selected Git status, project identity, active profile, and filesystem/network permissions.
• Use SwiftASBFeaturePolicy to present feature-category toggles only when the app actually lets users change SwiftASB-owned authority. Read-only Git observability and extension inventory are enabled by default; stronger mutation categories should stay deliberate app choices.
• Subscribe to CodexAppServer.featureOperationEvents() when SwiftUI needs to show marketplace-upgrade results or future SwiftASB-owned mutation records. Do not emit parallel UI events for routine read-only refreshes.
• Use agenda for plan and goal UI when the view needs current goal state, accepted plan steps, proposed plan text, or goal mutations. Use CodexThread.readGoal(), setGoal(_:), clearGoal(), setName(_:), archive(), unarchive(), updateMetadata(gitInfo:), compactContext(), and rollbackLastTurns(_:) from app-facing actions that already own the selected thread.
• Use CodexThread.startReview(against:placement:) only from review controls that clearly say what will be reviewed and where the result appears.
• Use CodexThread.sendShellCommand(_:) only behind explicit user opt-in for high-impact shell execution; preserve shell syntax and explain that it does not inherit the thread sandbox policy.
• Use dashboard for thread-wide current activity. Use thread.startPlanningTurn(...) for Plan buttons instead of sending slash commands through a text prompt.
• Use currentMinimap for the active turn's command, file-edit, dynamic-tool, collab-tool, MCP, and compaction activity.
• Handle CodexTurnItem.Kind.sleep explicitly in custom turn item switches so UI remains forward-safe for Codex CLI 0.142.x history and live events.
• Use ASBThreadSidebar, ASBAgendaPanel, and ASBDashboardPanel from ASBSwiftUI when the app wants SwiftASB-owned presentation snapshots rendered with packaged UI instead of custom panels.
• Use recent companions for inspector rails and completed history instead of building a second cache from raw events.
• Keep approval and elicitation prompts user-facing and concrete: tell the user what command, file change, permission, or MCP action is being requested.
• Keep cancellation visible and reversible where the app's product model allows it.

Validation

Run the repository's documented validation path.

For SwiftPM packages:

swift build
swift test

For Xcode apps, use the repository's documented xcodebuild or Xcode MCP workflow. Do not assume SwiftPM validation is enough for an app project with Xcode-owned project settings.

Live Codex integration tests should be opt-in, isolated in temporary workspaces, and bounded by hard timeouts.

Handoffs

• Use swiftasb:explain-swiftasb when the user needs adoption tradeoffs before implementation.
• Use swiftasb:choose-integration-shape when ownership or app shape is unclear.
• Use apple-dev-skills:explore-apple-swift-docs for SwiftUI, Observation, SwiftPM, or AppKit documentation.
• Use Apple build, test, or Xcode workflow skills for project execution and diagnostics.

Guardrails

• Do not put raw generated CodexWire... models into SwiftUI view state.
• Do not introduce a command bus or broad coordinator just to forward SwiftASB events; use local model methods and SwiftASB handles unless the app already has a real architecture surface for that job.
• Do not start overlapping turns on the same thread; SwiftASB rejects that because the live app-server does not expose a reliable independent lifecycle for them.
• Do not hide local Codex CLI discovery, compatibility, or startup failures behind generic "failed" messages; preserve CodexAppServerStartupError cases when mapping errors into UI text.
• Do not run multiple SwiftPM or Xcode build/test commands concurrently.