with one click
build-swiftui-app
// Build or refactor a SwiftUI app feature on top of SwiftASB using framework-owned SwiftUI state, SwiftASB thread and turn handles, observable companions, clear runtime diagnostics, and safe validation.
// Build or refactor a SwiftUI app feature on top of SwiftASB using framework-owned SwiftUI state, SwiftASB thread and turn handles, observable companions, clear runtime diagnostics, and safe validation.
[HINT] Download the complete skill directory including SKILL.md and all related files
| name | build-swiftui-app |
| description | Build or refactor a SwiftUI app feature on top of SwiftASB using framework-owned SwiftUI state, SwiftASB thread and turn handles, observable companions, clear runtime diagnostics, and safe validation. |
| license | Apache-2.0 |
| compatibility | Designed for Codex and compatible Agent Skills clients working with SwiftASB v1.3.1 or newer, Swift 6, SwiftPM, SwiftUI, Observation, Xcode, and local Codex app-server integrations. |
| metadata | {"owner":"gaelic-ghost","repo":"socket","package":"SwiftASB","category":"swiftasb-swiftui"} |
| allowed-tools | Read Bash(rg:*) Bash(git:*) Bash(swift:*) Bash(xcodebuild:*) |
Help a SwiftUI app use SwiftASB to start Codex work, show live progress, 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-resource/workspace facts, observe SwiftASB-owned feature operations, 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 companion, 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-resource reads, workspace permission facts, feature policy, feature-operation events, thread and turn handles, typed events, request responses, diagnostics, and recent-history companions.
Before implementing or proposing SwiftUI structure, read the relevant Apple documentation through Apple Dev Skills or official Apple docs.
Minimum rules to rely on:
@State is view-managed storage, and SwiftUI updates dependent views when the value changes.@Observable objects in @State; subviews update when they read changed observable properties.App whose body provides one or more Scene values.@Observable macro rather than bare Observable protocol conformance.Authoritative docs:
swiftasb:choose-integration-shape selects a SwiftUI app shape.Verify current SwiftASB docs and public API before editing:
Sources/SwiftASB/SwiftASB.docc/GettingStartedWithSwiftASB.mdSources/SwiftASB/SwiftASB.docc/SwiftUIObservableCompanions.mdSources/SwiftASB/SwiftASB.docc/ThreadHistoryAndObservables.mdSources/SwiftASB/SwiftASB.docc/HandlingTurnProgressAndApprovals.mdSources/SwiftASB/SwiftASB.docc/AppWideCapabilities.mdSources/SwiftASB/SwiftASB.docc/CodexFS.mdSources/SwiftASB/SwiftASB.docc/CodexConfig.mdSources/SwiftASB/SwiftASB.docc/CodexExtensions.mdSources/SwiftASB/SwiftASB.docc/CodexWorkspace.mdSources/SwiftASB/SwiftASB.docc/FeaturePermissionPolicy.mdSources/SwiftASB/SwiftASB.docc/ThreadManagement.mdSources/SwiftASB/Public/CodexAppServer+Library.swiftSources/SwiftASB/Public/CodexAppServer+LoadedThreads.swiftSources/SwiftASB/Public/CodexAppServer+CodexExtensions.swiftSources/SwiftASB/Public/CodexAppServer+MCP.swiftSources/SwiftASB/Public/CodexFS.swiftSources/SwiftASB/Public/CodexConfig.swiftSources/SwiftASB/Public/CodexWorkspace.swiftSources/SwiftASB/Public/CodexAppServer+Bootstrap.swiftSources/SwiftASB/Public/CodexAppServer.swiftSources/SwiftASB/Public/CodexDiagnostics.swiftSources/SwiftASB/Public/CodexErrors.swiftSources/SwiftASB/Public/CodexThread.swiftSources/SwiftASB/Public/CodexThread+Dashboard.swiftSources/SwiftASB/Public/CodexTurnHandle.swiftAs of SwiftASB v1.3.1, SwiftUI-facing integrations should prefer:
CodexAppServer.start(_:) with CodexAppServer.StartupRequest for normal one-call startup, compatibility validation, initialization, and typed CodexAppServerStartupError failuresCodexAppServer.start(), cliExecutableDiagnostics(), and initialize(_:) only when the app intentionally owns custom diagnostics, compatibility policy, or test setup before initializationCodexAppServer for process ownership, diagnostics, thread creation, stored-thread operations, MCP resource reads, feature-operation-event streams, and app-wide capability readsCodexAppServer.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 changesCodexAppServer.fs, CodexAppServer.config, and CodexAppServer.extensions for app-server-owned file metadata, directory/file reads, file discovery with match metadata, effective config, app, skill, plugin, collaboration-mode inventory, plugin detail reads, and already-configured marketplace upgradesCodexAppServer.readMcpResource(_:) for app-wide or thread-scoped MCP resource contentsSwiftASBFeaturePolicy 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 inCodexAppServer.featureOperationEvents() for human-readable SwiftASB-owned mutation records, such as marketplace maintenance attemptsCodexWorkspace 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 factsCodexThread for conversation-scoped turn creation, request routing, archive/unarchive, thread actions, thread goals, and local historyCodexTurnHandle for one active turn, including events, steering, interruption, request responses, and completion handoffCodexThread.makeDashboard() for thread-level current stateCodexTurnHandle.minimap for active-turn current stateCodexThread.makeRecentTurns(...), makeRecentFiles(...), and makeRecentCommands(...) for local history viewsCodexAppServer.ThreadListQD, CodexFS.FileDiscoveryQD, CodexThread.HistoryWindowQD, CodexThread.RecentFilesQD, and CodexThread.RecentCommandsQD when SwiftUI state needs repeatable query intenthttps://github.com/gaelic-ghost/SwiftASB1.3.1 when using one-call startup with typed startup errors, app-wide library, 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 resource reads, config warnings, extension inventory, workspace, query-descriptor, thread archive/unarchive, or recent-activity guidance; otherwise verify the support window in SwiftASB's READMESwiftASBCodexAppServerCodexAppServer.Library when the UI needs stored-thread lists before a thread is selectedCodexThreadCodexTurnHandleappServer.start(_:) for normal clients and the lower-level start() plus initialize(_:) sequence only for custom diagnostics or tests.CodexAppServer.CodexAppServer.Library from the app server when the UI has a launcher, sidebar, project browser, or app-wide diagnostics surface.appServer.fs, appServer.config, appServer.extensions, appServer.readMcpResource(_:), CodexWorkspace, and SwiftASBFeaturePolicy when SwiftUI needs filesystem, config, plugin/skill/app, collaboration-mode, marketplace-maintenance, MCP-resource, worktree, selected Git status, project identity, thread source, permission facts, or feature-category choices from Codex.CodexTurnHandle or CodexThread.Prefer one app-facing model that makes ownership visible:
import Observation
import SwiftASB
@MainActor
@Observable
final class CodexWorkspaceModel {
private let appServer = CodexAppServer()
var library: CodexAppServer.Library?
var thread: CodexThread?
var dashboard: CodexThread.Dashboard?
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
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()
} catch {
errorMessage = "SwiftASB could not start the local Codex runtime: \(error)"
}
}
func refreshAppSnapshots() async {
await library?.refreshAppSnapshots()
}
func selectThread(_ threadID: String?) {
library?.selectThread(threadID)
}
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.
CodexAppServerStartupError startup and compatibility failures before offering turn controls.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.library.selectedGitStatus, lastGitStatusReadAt, and latestGitStatusErrorDescription when a selected-worktree status panel needs branch, SHA, remotes, dirty/untracked counts, or refresh failures.CodexAppServer.ThreadListQD when the same sidebar query should drive both direct listThreads reads and library loading.CodexAppServer.fs and CodexFS.FileDiscoveryQD for sandbox-safe file pickers, metadata panes, directory browsers, file-byte previews, watches, highlighted matches, and ranking explanations.CodexAppServer.readMcpResource(_:) when the UI needs to show text or blob resource contents advertised by a configured MCP server.CodexAppServer.config, CodexAppServer.extensions, and CodexWorkspace for diagnostics views that show effective config, requirements, available apps/skills/plugins, collaboration modes, worktree snapshots, selected Git status, project identity, active profile, and filesystem/network permissions.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.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.CodexThread.readGoal(), setGoal(_:), clearGoal(), setName(_:), archive(), unarchive(), updateMetadata(gitInfo:), compactContext(), and rollbackLastTurns(_:) from app-facing actions that already own the selected thread.dashboard for thread-wide current activity.currentMinimap for the active turn's command, file-edit, dynamic-tool, collab-tool, MCP, and compaction activity.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.
swiftasb:explain-swiftasb when the user needs adoption tradeoffs before implementation.swiftasb:choose-integration-shape when ownership or app shape is unclear.apple-dev-skills:explore-apple-swift-docs for SwiftUI, Observation, SwiftPM, or AppKit documentation.CodexWire... models into SwiftUI view state.CodexAppServerStartupError cases when mapping errors into UI text.