agentbridge-cli 0.1.11__tar.gz → 0.1.12__tar.gz

{agentbridge_cli-0.1.11 → agentbridge_cli-0.1.12}/.codex/skills/build-release/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: build-release
-description: Build, publish, and verify AgentBridge releases. Use when the user invokes /build-release or asks to cut, launch, tag, publish, monitor, or verify an agentbridge-cli PyPI or GitHub release.
+description: Build, publish, and verify AgentBridge releases. Use when the user invokes /build-release or asks to cut, launch, tag, publish, monitor, or verify the agentbridge-cli PyPI package or macOS app.
 ---
 
 # Build Release
@@ -9,7 +9,8 @@ Use the repository-owned GitHub Actions workflow and PyPI Trusted Publishing.
 Do not create a local tag or upload with local credentials: pushing a new
 `pyproject.toml` version to `main` triggers `.github/workflows/release.yml`,
 which tests, scans, builds, creates `v<version>`, creates the GitHub Release,
-and publishes `agentbridge-cli`.
+publishes `agentbridge-cli`, and, when macOS publishing is enabled, attaches
+signed and notarized arm64 and x86_64 DMGs.
 
 Use the next unused patch version unless the user requests another valid,
 unused semantic version. Treat an untagged version absent from PyPI as pending.
@@ -28,6 +29,13 @@ git log --oneline HEAD..origin/main
 Stop on unrelated changes, unpublished commits, divergence, or another branch.
 Do not clean, pull, commit unrelated files, or switch branches.
 
+Require the repository variable `MACOS_RELEASE_ENABLED` to be `true` and verify
+that these Actions secrets are configured before a release expected to contain
+the macOS app: `APPLE_CERTIFICATE_BASE64`, `APPLE_CERTIFICATE_PASSWORD`,
+`APPLE_KEYCHAIN_PASSWORD`, `APPLE_NOTARY_APPLE_ID`, `APPLE_NOTARY_PASSWORD`, and
+`APPLE_TEAM_ID`. Secret names may be inspected with `gh secret list`; never read
+or print secret values.
+
 2. Select the release version from the repository root:
 
 ```bash
@@ -47,10 +55,12 @@ uv lock
 python3 .codex/skills/build-release/scripts/release_build.py preflight --version <version>
 ```
 
-The preflight requires consistent project and lock metadata, an unused PyPI
-version and tag, clean patch formatting, a frozen lock, passing tests on Python
-3.12 and 3.13, Ruff, a successful wheel and sdist build, artifact audits, and a
-wheel installation smoke test. Stop at the exact failed gate.
+The preflight requires macOS. It checks consistent project and lock metadata, an
+unused PyPI version and tag, clean patch formatting, a frozen lock, Python 3.12
+and 3.13 tests, Ruff, Swift tests, a self-contained app/DMG build for the current
+Mac architecture, app signature and embedded-runtime smoke tests, wheel and
+sdist audits, and a wheel installation smoke test. CI builds and notarizes both
+macOS architectures. Stop at the exact failed gate.
 
 4. Review and publish the release commit:
 
@@ -87,12 +97,17 @@ python3 .codex/skills/build-release/scripts/release_build.py wait-pypi --version
 gh release view v<version> --json url,tagName,assets
 ```
 
-Do not report success until PyPI returns files for the exact version. If the
-workflow fails, inspect `gh run view <run-id> --log-failed` and report the
-failed gate before considering recovery.
+When macOS publishing is enabled, require both
+`AgentBridge-<version>-macos-arm64.dmg` and
+`AgentBridge-<version>-macos-x86_64.dmg` plus their `.sha256` files in the
+release assets. Do not report success until PyPI returns exact-version files and
+all required GitHub assets exist. If the workflow fails, inspect
+`gh run view <run-id> --log-failed` and report the failed gate before considering
+recovery.
 
 ## Final Response
 
 Lead with the exact PyPI version URL. Report the tag, release workflow URL and
-conclusion, GitHub Release URL, pushed commit, and every distribution filename.
-On failure, report the exact command or job and the next safe recovery action.
+conclusion, GitHub Release URL, pushed commit, every Python distribution, and
+every macOS DMG/checksum filename. On failure, report the exact command or job
+and the next safe recovery action.

{agentbridge_cli-0.1.11 → agentbridge_cli-0.1.12}/.codex/skills/build-release/scripts/release_build.py

@@ -7,6 +7,7 @@ import argparse
 import email.parser
 import hashlib
 import json
+import platform
 import re
 import subprocess
 import sys
@@ -307,6 +308,40 @@ def smoke_wheel(wheel: Path, version: str) -> None:
         run([str(installed_python), "-c", code])
 
 
+def preflight_macos_app(version: str) -> dict[str, object]:
+    if sys.platform != "darwin":
+        raise SystemExit("the AgentBridge release preflight requires macOS for app validation")
+
+    architecture = platform.machine()
+    if architecture not in {"arm64", "x86_64"}:
+        raise SystemExit(f"unsupported macOS release architecture: {architecture}")
+
+    run(["swift", "test", "--package-path", "macos"])
+    run(["scripts/build_macos_app.sh"])
+
+    output = REPO_ROOT / "build" / "macos" / architecture
+    app = output / "AgentBridge.app"
+    dmg = output / f"AgentBridge-{version}-macos-{architecture}.dmg"
+    checksum = Path(f"{dmg}.sha256")
+    run(["scripts/verify_macos_app.sh", str(app)])
+
+    if not dmg.is_file() or not checksum.is_file():
+        raise SystemExit(f"macOS release artifacts are missing under {output}")
+    recorded_hash = checksum.read_text(encoding="utf-8").split(maxsplit=1)[0]
+    actual_hash = sha256(dmg)
+    if recorded_hash != actual_hash:
+        raise SystemExit(f"macOS DMG checksum mismatch: {dmg.name}")
+
+    result = {
+        "file": dmg.name,
+        "sha256": actual_hash,
+        "architecture": architecture,
+        "signing": "local preflight signature",
+    }
+    print(json.dumps({"macos_app": result}, indent=2))
+    return result
+
+
 def preflight(args: argparse.Namespace) -> None:
     version = args.version
     check_version(version)
@@ -342,6 +377,7 @@ def preflight(args: argparse.Namespace) -> None:
             ".codex/skills/build-release/scripts/release_build.py",
         ]
     )
+    macos_result = preflight_macos_app(version)
     with tempfile.TemporaryDirectory(prefix="agentbridge-release-") as directory:
         output = Path(directory) / "dist"
         run(["uv", "build", "--out-dir", str(output)])
@@ -356,7 +392,11 @@ def preflight(args: argparse.Namespace) -> None:
         smoke_wheel(wheels[0], version)
         print(
             json.dumps(
-                {"package": PACKAGE_NAME, "version": version, "artifacts": results},
+                {
+                    "package": PACKAGE_NAME,
+                    "version": version,
+                    "artifacts": results + [macos_result],
+                },
                 indent=2,
             )
         )

{agentbridge_cli-0.1.11 → agentbridge_cli-0.1.12}/.github/dependabot.yml

@@ -10,6 +10,18 @@ updates:
     cooldown:
       default-days: 7
     open-pull-requests-limit: 5
+    groups:
+      security-updates:
+        applies-to: security-updates
+        patterns:
+          - "*"
+      minor-and-patch:
+        applies-to: version-updates
+        update-types:
+          - minor
+          - patch
+        patterns:
+          - "*"
 
   - package-ecosystem: github-actions
     directory: /
@@ -21,3 +33,10 @@ updates:
     cooldown:
       default-days: 7
     open-pull-requests-limit: 5
+    groups:
+      minor-and-patch:
+        update-types:
+          - minor
+          - patch
+        patterns:
+          - "*"

agentbridge_cli-0.1.12/.github/workflows/ci.yml

@@ -0,0 +1,52 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  merge_group:
+    types:
+      - checks_requested
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --frozen --extra test --python ${{ matrix.python-version }}
+
+      - name: Audit dependencies
+        run: uv run --frozen --extra test --python ${{ matrix.python-version }} pip-audit
+
+      - name: Lint
+        run: uv run --frozen --extra test --python ${{ matrix.python-version }} ruff check agentbridge tests
+
+      - name: Run tests
+        run: uv run --frozen --extra test --python ${{ matrix.python-version }} pytest -q
+
+      - name: Smoke test CLI
+        run: uv run --frozen --python ${{ matrix.python-version }} agentbridge --help
+
+      - name: Build package
+        if: matrix.python-version == '3.12'
+        run: uv build

{agentbridge_cli-0.1.11 → agentbridge_cli-0.1.12}/.github/workflows/release.yml

@@ -28,7 +28,7 @@ jobs:
     outputs:
       should-publish: ${{ steps.publish.outputs.should-publish }}
     steps:
-      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
           persist-credentials: false
@@ -52,36 +52,51 @@ jobs:
       matrix:
         python-version: ["3.12", "3.13"]
     steps:
-      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
       - name: Install uv
-        uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
         with:
           enable-cache: true
           cache-dependency-glob: "uv.lock"
       - name: Set up Python ${{ matrix.python-version }}
         run: uv python install ${{ matrix.python-version }}
       - name: Install dependencies
-        run: uv sync --all-extras --python ${{ matrix.python-version }}
+        run: uv sync --frozen --extra test --python ${{ matrix.python-version }}
+      - name: Audit dependencies
+        run: uv run --frozen --extra test --python ${{ matrix.python-version }} pip-audit
+      - name: Lint
+        run: uv run --frozen --extra test --python ${{ matrix.python-version }} ruff check agentbridge tests
       - name: Run tests
-        run: uv run --python ${{ matrix.python-version }} pytest tests/ -v --tb=short
+        run: uv run --frozen --extra test --python ${{ matrix.python-version }} pytest -q
 
   pii-scan:
     runs-on: ubuntu-latest
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
       - name: Run gitleaks
-        uses: gitleaks/gitleaks-action@ff98106e4c7b2bc287b24eaf42907196329070c7 # v2
+        uses: gitleaks/gitleaks-action@e0c47f4f8be36e29cdc102c57e68cb5cbf0e8d1e # v3.0.0
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
+  macos-test:
+    runs-on: macos-15
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Test menu-bar app
+        run: swift test --package-path macos
+
   build:
-    needs: [changes, test, pii-scan]
+    needs: [changes, test, pii-scan, macos-test]
     if: needs.changes.outputs.should-publish == 'true'
     runs-on: ubuntu-latest
     timeout-minutes: 15
@@ -91,7 +106,7 @@ jobs:
       publish: ${{ steps.check-version.outputs.tag_exists == 'false' }}
       tag: ${{ steps.check-version.outputs.tag }}
     steps:
-      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
           persist-credentials: false
@@ -122,7 +137,7 @@ jobs:
           echo "Version ${version} maps to ${tag}; tag_exists=${tag_exists}"
       - name: Setup uv
         if: steps.check-version.outputs.tag_exists == 'false'
-        uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
         with:
           enable-cache: true
           cache-dependency-glob: "uv.lock"
@@ -175,26 +190,126 @@ jobs:
           PY
       - name: Store package artifacts
         if: steps.check-version.outputs.tag_exists == 'false'
-        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: python-package-${{ github.sha }}
           path: dist/
           if-no-files-found: error
           retention-days: 1
 
+  macos-app:
+    needs: [build]
+    if: >-
+      needs.build.outputs.publish == 'true' &&
+      vars.MACOS_RELEASE_ENABLED == 'true'
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - runner: macos-15
+            architecture: arm64
+          - runner: macos-15-intel
+            architecture: x86_64
+    runs-on: ${{ matrix.runner }}
+    timeout-minutes: 30
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Install uv
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+      - name: Install Python 3.12
+        run: uv python install 3.12
+      - name: Import Developer ID certificate
+        env:
+          APPLE_CERTIFICATE_BASE64: ${{ secrets.APPLE_CERTIFICATE_BASE64 }}
+          APPLE_CERTIFICATE_PASSWORD: ${{ secrets.APPLE_CERTIFICATE_PASSWORD }}
+          KEYCHAIN_PASSWORD: ${{ secrets.APPLE_KEYCHAIN_PASSWORD }}
+        shell: bash
+        run: |
+          certificate_path="$RUNNER_TEMP/developer-id.p12"
+          keychain_path="$RUNNER_TEMP/agentbridge-signing.keychain-db"
+          echo "$APPLE_CERTIFICATE_BASE64" | base64 -D > "$certificate_path"
+          security create-keychain -p "$KEYCHAIN_PASSWORD" "$keychain_path"
+          security set-keychain-settings -lut 21600 "$keychain_path"
+          security unlock-keychain -p "$KEYCHAIN_PASSWORD" "$keychain_path"
+          security import "$certificate_path" \
+            -P "$APPLE_CERTIFICATE_PASSWORD" \
+            -A \
+            -t cert \
+            -f pkcs12 \
+            -k "$keychain_path"
+          security list-keychain -d user -s "$keychain_path"
+          security set-key-partition-list \
+            -S apple-tool:,apple: \
+            -s \
+            -k "$KEYCHAIN_PASSWORD" \
+            "$keychain_path"
+          identity="$(security find-identity -v -p codesigning "$keychain_path" \
+            | sed -n 's/.*"\(Developer ID Application:.*\)"/\1/p' \
+            | head -1)"
+          test -n "$identity"
+          echo "CODE_SIGN_IDENTITY=$identity" >> "$GITHUB_ENV"
+      - name: Build signed application
+        run: scripts/build_macos_app.sh
+      - name: Verify embedded application
+        run: scripts/verify_macos_app.sh "build/macos/${{ matrix.architecture }}/AgentBridge.app"
+      - name: Notarize and staple disk image
+        env:
+          APPLE_ID: ${{ secrets.APPLE_NOTARY_APPLE_ID }}
+          APPLE_APP_PASSWORD: ${{ secrets.APPLE_NOTARY_PASSWORD }}
+          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+        shell: bash
+        run: |
+          dmg="$(find "build/macos/${{ matrix.architecture }}" -maxdepth 1 -name '*.dmg' -print -quit)"
+          test -n "$dmg"
+          xcrun notarytool submit "$dmg" \
+            --apple-id "$APPLE_ID" \
+            --password "$APPLE_APP_PASSWORD" \
+            --team-id "$APPLE_TEAM_ID" \
+            --wait
+          xcrun stapler staple "$dmg"
+          xcrun stapler validate "$dmg"
+          shasum -a 256 "$dmg" > "$dmg.sha256"
+      - name: Store macOS artifacts
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: macos-app-${{ matrix.architecture }}-${{ github.sha }}
+          path: |
+            build/macos/${{ matrix.architecture }}/*.dmg
+            build/macos/${{ matrix.architecture }}/*.dmg.sha256
+          if-no-files-found: error
+          retention-days: 1
+
   release:
-    needs: [build, publish]
-    if: needs.build.outputs.publish == 'true'
+    needs: [build, publish, macos-app]
+    if: >-
+      always() &&
+      needs.build.outputs.publish == 'true' &&
+      needs.publish.result == 'success' &&
+      (needs.macos-app.result == 'success' || needs.macos-app.result == 'skipped')
     runs-on: ubuntu-latest
     timeout-minutes: 10
     permissions:
       contents: write
     steps:
       - name: Download package artifacts
-        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
           name: python-package-${{ github.sha }}
           path: dist/
+      - name: Download macOS artifacts
+        if: needs.macos-app.result == 'success'
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          pattern: macos-app-*-${{ github.sha }}
+          path: dist/
+          merge-multiple: true
       - name: Create GitHub release
         run: gh release create "$TAG" --title "$TAG" --generate-notes dist/*
         env:
@@ -215,9 +330,9 @@ jobs:
       id-token: write
     steps:
       - name: Setup uv
-        uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
       - name: Download package artifacts
-        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
           name: python-package-${{ github.sha }}
           path: dist/

{agentbridge_cli-0.1.11 → agentbridge_cli-0.1.12}/.gitignore

@@ -54,4 +54,6 @@ logs/
 *$py.class
 .claude/settings.local.json
 .eggs/
+.build/
+.swiftpm/
 _build_info.py

agentbridge_cli-0.1.11/README.md → agentbridge_cli-0.1.12/PKG-INFO

@@ -1,10 +1,42 @@
+Metadata-Version: 2.5
+Name: agentbridge-cli
+Version: 0.1.12
+Summary: Bridge OpenAI tools to Claude Code SDK, Codex CLI, and OpenRouter
+Project-URL: Homepage, https://github.com/tsilva/agentbridge
+Project-URL: Repository, https://github.com/tsilva/agentbridge
+Project-URL: Issues, https://github.com/tsilva/agentbridge/issues
+Author: tsilva
+License: MIT
+License-File: LICENSE
+Keywords: anthropic,api,bridge,claude,claude-code,codex,fastapi,llm,openai,streaming
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.12
+Requires-Dist: claude-agent-sdk>=0.2.132
+Requires-Dist: fastapi>=0.141.1
+Requires-Dist: jinja2>=3.1.0
+Requires-Dist: openrouter==1.1.31
+Requires-Dist: pillow>=12.3.0
+Requires-Dist: uvicorn[standard]>=0.32.0
+Provides-Extra: test
+Requires-Dist: pip-audit>=2.9.0; extra == 'test'
+Requires-Dist: pytest-asyncio>=1.4.0; extra == 'test'
+Requires-Dist: pytest>=9.1.1; extra == 'test'
+Requires-Dist: ruff>=0.15.0; extra == 'test'
+Description-Content-Type: text/markdown
+
 <div align="center">
-  <img src="./logo.png" alt="agentbridge" width="512" />
+  <img src="./logo.png" alt="AgentBridge" width="512" />
 
-  **🌉 Bridge OpenAI tools to Claude Code SDK, Codex CLI, or OpenRouter — use your subscriptions anywhere 🔌**
+  **OpenAI-compatible routing for Claude Code, Codex, and OpenRouter — use your subscriptions anywhere.**
 </div>
 
-agentbridge is a local API bridge for developers who want to connect OpenAI-compatible apps to Claude Code, Codex, or OpenRouter. Run one server, choose a backend with a namespaced model ID, and point existing Chat Completions clients at `http://localhost:8082/api/v1`.
+AgentBridge is a local API bridge for developers who want to connect OpenAI-compatible apps to Claude Code, Codex, or OpenRouter. Run one server, choose a backend with a namespaced model ID, and point existing Chat Completions clients at `http://localhost:8082/api/v1`.
 
 It supports streaming and non-streaming responses, image and PDF inputs where the backend accepts them, native Codex image editing, strict JSON Schema output, OpenAI-style tool calls, a live dashboard, and local JSON session logs.
 
@@ -12,6 +44,31 @@ It supports streaming and non-streaming responses, image and PDF inputs where th
 
 ## Install
 
+### macOS menu-bar app
+
+Build the app locally on macOS 13 or later. This requires
+[uv](https://docs.astral.sh/uv/) and the Xcode Command Line Tools, but it does
+not require an Apple Developer account:
+
+```bash
+git clone https://github.com/tsilva/agentbridge.git
+cd agentbridge
+scripts/build_macos_app.sh
+open "build/macos/$(uname -m)/AgentBridge-"*.dmg
+```
+
+Drag `AgentBridge.app` to Applications and open it. The menu-bar window shows
+live server health and activity, starts and stops the local server, opens the
+dashboard, and provides settings for the port, worker count, and launch at
+login. See [`macos/README.md`](macos/README.md) for development instructions.
+
+The app contains its own Python 3.12 runtime and AgentBridge dependencies. It
+does not bundle the Claude Code or Codex executables: installed provider tools
+and their existing authentication state remain in the user account. Mutable
+configuration and logs continue to live under `~/.config/agentbridge/`.
+
+### Command line
+
 ```bash
 uv tool install agentbridge-cli
 agentbridge
@@ -97,14 +154,17 @@ agentbridge --workers 3                               # set Claude pool and Code
 agentbridge --version                                 # print package and git version
 uv run --frozen --extra test pytest -q                # run tests
 uv run --frozen --extra test ruff check agentbridge tests  # lint Python
+swift test --package-path macos                    # test the macOS app
+scripts/build_macos_app.sh                         # build a local signed app and DMG
 uv lock --check                                       # verify the lockfile
 uv build                                              # build wheel and source distribution
 ```
 
 ## Notes
 
-- Python 3.12+ and at least one authenticated backend are required.
+- The CLI requires Python 3.12+; the macOS app bundles Python. At least one authenticated backend is required for provider requests.
 - Public routes include `POST /api/v1/chat/completions`, `POST /api/v1/images`, `GET /api/v1/models`, `GET /api/v1/capabilities`, `GET /health`, `/dashboard`, and `/dashboard/chat`.
+- `GET /health` includes safe operator status used by the menu-bar app: version, start time, uptime, configured workers, active requests, and pool state when initialized.
 - `PORT`, `POOL_SIZE`, `CLAUDE_TIMEOUT`, `CODEX_TIMEOUT`, `CODEX_IMAGE_TIMEOUT`, and `OPENROUTER_TIMEOUT` control the server port, pool size, and provider timeouts. `--workers` overrides `POOL_SIZE`; Codex chat and native image generation default to 600-second timeouts, while Claude and OpenRouter default to 120 seconds.
 - `MAX_IMAGE_INPUT_BYTES`, `MAX_IMAGE_OUTPUT_BYTES`, and `MAX_IMAGE_PIXELS` bound native image requests. Defaults are 64 MiB input, 32 MiB output, and 40 million pixels.
 - `AGENTBRIDGE_CONFIG_DIR` moves the user configuration directory. `LOG_DIR` moves session logs, and `MAX_LOG_FILES` limits retained JSON logs.
@@ -116,7 +176,12 @@ uv build                                              # build wheel and source d
 
 ## Publishing
 
-Releases use the `Release` GitHub Actions workflow and PyPI Trusted Publishing for the `agentbridge-cli` project. The publisher is scoped to owner `tsilva`, repository `agentbridge`, workflow `release.yml`, and environment `pypi`; no PyPI API token is required. Releases through `0.1.10` remain available under the previous `agentbridge-py` distribution name.
+Releases use the `Release` GitHub Actions workflow and PyPI Trusted Publishing
+for the `agentbridge-cli` project. The publisher is scoped to owner `tsilva`,
+repository `agentbridge`, workflow `release.yml`, and environment `pypi`; no
+PyPI API token is required. GitHub Releases contain the Python distributions;
+the macOS app is tested in CI and built locally from source. Releases through
+`0.1.10` remain available under the previous `agentbridge-py` distribution name.
 
 ## Architecture