Explain swiftasb

Explain 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 user understand whether SwiftASB is the right foundation for their Swift app, tool, or package before implementation starts.

Start with the real job: SwiftASB lets Swift code drive the local Codex app-server through a Swift-native API. It owns the local Codex subprocess, typed request and response conversion, app-wide stored-thread library and inventory state, thread agenda state, 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, SwiftASB feature policy, feature-operation events, plan-mode turn starts, thread goals, code-review and gated shell-command actions, thread, agenda, and turn handles, interactive request handling, diagnostics, local history reads, and SwiftUI-friendly observable companions.

When To Use

• Use this skill when a user asks what SwiftASB is or whether they should build on it.
• Use this skill before planning a SwiftASB integration when the app shape or adoption tradeoffs are unclear.
• Use this skill when an agent needs to explain SwiftASB to a non-maintainer user in plain language.
• Use this skill when licensing, runtime dependency, or API-boundary concerns affect adoption.

Source Check

Before giving exact API claims, inspect the current SwiftASB source of truth:

• SwiftASB GitHub repository
• README.md
• Sources/SwiftASB/SwiftASB.docc/
• Sources/SwiftASB/SwiftASB.docc/SwiftUIObservableCompanions.md
• Sources/SwiftASB/SwiftASB.docc/FeaturePermissionPolicy.md
• Sources/SwiftASB/SwiftASB.docc/CodexInventory.md
• Sources/SwiftASB/SwiftASB.docc/CodexMCP.md
• the public files under Sources/SwiftASB/Public/
• the latest release notes or tags

As of SwiftASB v1.8.0, the supported public surface centers on:

• CodexAppServer, the owner of the local Codex subprocess, one-call startup, stored-thread operations, app-wide library and inventory creation, diagnostics, feature-operation-event streams, and capability reads
• CodexAppServer.start(_:), CodexAppServer.StartupRequest, CodexAppServer.StartupSession, CodexAppServer.StartupCompatibilityPolicy, and CodexAppServerStartupError for normal startup, reviewed support-window validation, initialization, selected-CLI diagnostics, and typed startup failure handling
• CodexAppServer.Library, the app-wide observable companion for stored-thread lists, cwd or repository grouping, stable worktree groups, repository/worktree filters, selected worktree or repository context, selected-worktree Git status, CodexWorkspace.ProjectInfo project identity, CodexAppServer.ThreadSource source badges, and model/MCP/hook snapshots
• CodexAppServer.Inventory from 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 filesystem reads, effective config reads, advanced extension pagination, plugin detail reads, and already-configured marketplace upgrades
• CodexAppServer.mcp and CodexMCP for MCP server installs, full status snapshots, and app-wide or thread-scoped MCP resource contents advertised by configured servers
• SwiftASBFeaturePolicy, SwiftASBFeatureCategory, SwiftASBHostAccess, and SwiftASBFeatureOperationEvent for app-wide feature-category defaults, host-access declarations, mutation visibility, and quiet read-only observability
• CodexWorkspace for app-server-owned cwd, worktree snapshots, project identity, Git repository facts, selected Git status snapshots, filesystem, network, and permission-profile facts on thread sessions and requests
• CodexThread, the handle for one Codex conversation thread, including text turns, plan-mode turns, thread goal reads and mutations, and stored-thread actions
• CodexThread.makeAgenda() and CodexThread.Agenda for current thread goal state, accepted plan snapshots, proposed plan deltas, and summary titles
• CodexThread.startPlanningTurn(...) and CodexAppServer.TurnCollaborationMode.plan(...) for explicit plan-mode UI controls without sending slash-command text through the prompt
• CodexThread.startReview(against:placement:) and CodexReviewHandle for app-server code reviews from a thread, with inline or detached placement
• CodexThread.sendShellCommand(_:) for explicit user-level shell access, gated by the disabled-by-default shellCommandExecution feature category
• CodexTurnHandle, the handle for one active turn
• CodexTurnItem.Kind.sleep for preserved upstream sleep turn item classification when clients switch over public turn item kinds
• query descriptors such as CodexAppServer.ThreadListQD, CodexFS.FileDiscoveryQD, CodexThread.HistoryWindowQD, CodexThread.RecentFilesQD, and CodexThread.RecentCommandsQD
• thread source filtering and labels through CodexAppServer.ThreadListSourceKind and CodexAppServer.ThreadSource
• observable companions such as CodexThread.Dashboard, CodexThread.Agenda, CodexTurnHandle.Minimap, RecentTurns, RecentFiles, and RecentCommands
• diagnostics such as config warnings, deprecation notices, MCP server status changes, and remote-control status changes
• thread management actions such as archive, unarchive, rename, metadata updates, compaction, and rollback

Generated CodexWire... models are internal scaffolding, not the recommended app-facing API.

Explanation Workflow

1. Identify what the user wants to build.
2. State SwiftASB's job in one plain paragraph.
3. Name the runtime dependency: a local Codex CLI/app-server must be available.
4. Explain the main public owners only after the practical job is clear.
5. Describe the adoption benefits:
   • Swift-native values instead of raw JSON-RPC payloads
   • async streams for live thread and turn events
   • typed approval and elicitation responses
   • observable companions for app-wide libraries, app-wide inventories, SwiftUI inspectors, agenda panels, rails, and progress views
   • app-server-routed filesystem, config, extension, MCP, workspace, worktree, project identity, thread source, and permission facts for sandboxed clients
   • UI-ready fuzzy file-discovery match metadata, highlight ranges, and ranking reasons
   • repeatable query descriptors for thread lists, file discovery, history windows, recent files, and recent commands
   • local history helpers for recent turns, files, and commands
   • explicit plan and goal surfaces for planning controls, goal editors, accepted plan display, and proposed plan previews
   • explicit code-review and shell-command surfaces when the host app chooses to expose those actions
6. Describe the adoption costs:
   • the app depends on a local Codex runtime
   • compatibility follows SwiftASB's reviewed Codex CLI support window; for SwiftASB v1.8.0, prefer Codex CLI 0.142.x and treat compatible 0.141.x installs as the reviewed prior-minor window
   • SwiftASB-owned mutation helpers are feature-policy gated and should produce operation events instead of surprising silent writes
   • sendShellCommand(_:) is high-impact user-level shell execution and must stay an explicit opt-in app feature
   • same-thread overlapping turns are rejected client-side
   • generated wire features are not all public API
   • users must understand SwiftASB's package license before adoption
7. Give a clear fit recommendation.

Fit Guidance

SwiftASB is a good fit when the user needs a Swift app or package to:

• start or control local Codex work
• show live command, file-edit, MCP, hook, approval, diagnostic, library, agenda, or history state
• show workspace, worktree, selected Git status, project identity, thread source, filesystem, config, inventory, extension, model, MCP, hook, diagnostic, feature-operation, or permission facts from the app-server instead of reading local machine state directly
• upgrade already-configured plugin marketplaces through a typed extension-maintenance intent while surfacing the command result and operation event
• install MCP servers through SwiftASB-owned config writes, or inspect MCP status and resources from app UI
• show plan and goal state, start plan-mode turns, start app-server code reviews, or expose shell commands as deliberate user actions
• build SwiftUI or AppKit surfaces around Codex conversations
• keep raw app-server protocol models out of their own public API
• use typed Swift handles for threads, turns, approvals, elicitation, diagnostics, and recent history

SwiftASB is probably not the right first choice when the user needs:

• a hosted AI SDK unrelated to the local Codex app-server
• a server-side multi-user agent platform
• a cross-platform non-Apple UI toolkit as the primary target
• a stable public wrapper for every experimental Codex app-server feature
• an integration that cannot depend on a local Codex CLI runtime

Output Shape

Answer in this order:

1. Recommendation: one direct fit call.
2. What SwiftASB would do here: plain-language role.
3. What the app would own: UI, product behavior, persistence choices, and user policy.
4. What SwiftASB would own: app-server process, app-wide library and inventory state, agenda state, worktree groups and filters, selected Git status, project identity, thread source, filesystem/config/extension/MCP/workspace reads, feature policy, feature-operation events, typed review and shell-command entry points, typed thread and turn API, events, requests, diagnostics, query descriptors, and companions.
5. Tradeoffs: runtime, compatibility, same-thread turn policy, and licensing.
6. Next integration step: the next skill or repo action.

Handoffs

• Use swiftasb:choose-integration-shape when the user wants to proceed but the app shape is not settled.
• Use swiftasb:build-swiftui-app when the chosen target is a SwiftUI app.
• Use swiftasb:build-appkit-app when the chosen target is an AppKit app.
• Use swiftasb:build-swift-package when the chosen target is a package library, command-line package, helper package, or test harness.
• Use apple-dev-skills:explore-apple-swift-docs before making Apple framework claims.
• Use Apple build or Xcode workflow skills when the task shifts from explanation to project execution.

Guardrails

• Do not call SwiftASB a general AI SDK.
• Do not present generated wire models as the public consumer API.
• Do not promise support for app-server families that SwiftASB has not promoted into public API.
• Do not hide the local Codex runtime dependency.
• Do not flatten licensing into "open source" without explaining that SwiftASB's package license is documented in its own repository.