Imported from ainame/swift-codex (AGENTS.md). Install upstream with npx skills add ainame/swift-codex. Copyright stays with the author.

AGENTS.md

Scope

These instructions apply to the entire repository.

Project Goals

• Port the TypeScript Codex SDK from https://github.com/openai/codex/tree/main/sdk/typescript to Swift.
• Preserve TypeScript SDK behavior where practical while keeping the Swift API usable and idiomatic.
• Keep the Swift package focused on wrapping the codex CLI rather than reimplementing agent behavior.

License and Attribution

• This repository is Apache License 2.0 licensed.
• Treat the project as a derivative port of openai/codex where applicable.
• Preserve upstream attribution in NOTICE and keep LICENSE consistent with Apache License 2.0.
• Preserve upstream reference tracking in UPSTREAM.md.
• When importing or closely porting upstream material, do not remove applicable attribution or notice requirements.
• If new third-party derived material is added, update NOTICE when needed.

Dependencies

• Use swift-subprocess for subprocess execution.
• Use swift-log for SDK logging and logger injection.
• Use swift-testing by default for tests in this repository.
• Avoid adding new dependencies unless they provide clear value beyond small in-repo helpers.

Implementation Rules

• Keep CLI discovery Node-independent.
  • Prefer explicit binary override when provided.
  • Otherwise resolve codex from PATH.
• Keep SDK logging on swift-log.
  • Accept Logger at client construction boundaries rather than storing it in CodexConfig.
  • Do not call LoggingSystem.bootstrap(...) from the library; that is application-owned setup.
• Model MCP payloads generically unless stronger typing is required by a concrete use case.
• Keep config override serialization compatible with Codex CLI --config key=value behavior.
• Preserve important CLI argument ordering when behavior depends on it.

Upstream Sync

• Use the vendored openai/codex checkout at vendor/openai-codex as the default upstream source in this repository.
• If vendor/openai-codex is empty, uninitialized, or otherwise invalid in the current worktree, do not use it to decide whether a new upstream release exists.
• Record the exact openai/codex commit SHA used for any sync or parity work in UPSTREAM.md.
• Treat sdk/typescript as the primary upstream source unless the change clearly depends on another upstream path.
• Keep the vendor/openai-codex submodule updated intentionally. When changing its pinned commit, update UPSTREAM.md, CHANGELOG.md, and any related documentation in the same change.
• When the task depends on the latest upstream release, resolve that release from a current upstream source first, then use local checkouts for file comparison and syncing.
• When syncing with upstream, update UPSTREAM.md with the commit SHA, commit URL, review date, reviewed files or features, and intentional Swift-specific deviations.
• Update README.md when the recorded upstream basis changes the documented status, supported features, or scope.
• Do not claim a new upstream basis unless you verified the referenced commit against the implemented Swift behavior.

Verification

• Run swift build or swift test when changes are in a verifiable state.
• Prefer swift test for behavior changes.
• Keep the Examples package buildable independently.

Git Workflow

• Make git commits for each meaningful change.
• Do not squash unrelated work into one commit.
• If tags are created for versions, use tags without a v prefix.

GitHub Actions

• Never use swift-actions/setup-swift@v2.