How long does the integration take?

Change one base URL in an OpenAI-compatible client, or install the Python or TypeScript SDK; the quickstart routes a first request in a few minutes.

Will this lock us into another vendor?

No. The router is Apache-2.0 open source, your provider keys stay yours, and the API is OpenAI-compatible, so leaving is a change of base URL.

What happens when a provider fails?

The router falls back to the next model your policy allows and records the fallback in the trace, so an outage costs a retry, not an incident.

setup - Prompt - OpenSmartRoute

Name: setup
Author: xmtplabs

Prompt file imported from xmtplabs/convos-ios (.claude/commands/setup.md). Copyright stays with the author.

Setup

Initialize the Claude Code session for any branch or worktree — creates a dedicated simulator and configures build defaults.

Purpose

This command sets up an iOS simulator and XcodeBuildMCP session defaults so /build and /build --run work correctly. It works in any context:

convos-task worktrees: Uses the task config from .convos-task
Regular branches: Derives the simulator name from the current git branch
Main repo: Works on any branch, no special setup required

When to Run

At the start of any new session when working on a feature branch
Automatically suggested at session start when .convos-task file exists
Can be run manually anytime to reset or verify the setup

Instructions

Step 1: Determine Simulator Name

Check for configuration in this order:

.convos-task file exists: Read TASK_NAME and SIMULATOR_NAME from it
No .convos-task file: Derive from the current git branch:
- Run git branch --show-current to get the branch name
- Sanitize the branch name: replace / and special characters with -, lowercase it
- Simulator name: convos-<sanitized-branch-name>
- Example: branch jarod/push-notifications → simulator convos-jarod-push-notifications
- Special case: if on main or master, use convos-main

Step 2: Run Project Setup

Run Scripts/setup.sh with CI=true CLAUDE_SETUP=1 — CI skips one-time machine setup (git hooks, Xcode defaults, brew installs of the GitHub CLI) and CLAUDE_SETUP=1 re-enables the .env / Firebase debug token check so missing .env symlinks in worktrees surface as warnings:

CI=true CLAUDE_SETUP=1 Scripts/setup.sh

This ensures SwiftLint, SwiftFormat, and other dependencies are installed, and surfaces any .env gap that would otherwise cause Firebase App Check failures at runtime.

Step 3: Create Simulator if Needed

Use mcp__XcodeBuildMCP__list_sims to check if the simulator already exists
If the simulator doesn't exist:
- Find a base iPhone simulator to clone from (prefer iPhone 17 Pro, iPhone 17 Pro Max, or latest available)
- Use bash to clone it: xcrun simctl clone "BASE_SIM_NAME" "SIMULATOR_NAME"
Get the simulator's UUID from the list

Step 4: Set XcodeBuildMCP Session Defaults

Call mcp__XcodeBuildMCP__session-set-defaults with:

simulatorName: The simulator name (e.g., "convos-push-notifications")
projectPath: Path to Convos.xcodeproj
scheme: "Convos (Dev)" (default scheme)
useLatestOS: true

Step 5: Save Simulator ID for Session

Write the simulator UUID to .claude/.simulator_id for use by /build command.

Step 6: Report Setup Complete

Inform the user:

✅ Session setup complete

📱 Simulator: SIMULATOR_NAME (UUID)
🔧 XcodeBuildMCP defaults configured
📁 Project: Convos.xcodeproj
🎯 Scheme: Convos (Dev)

Ready to build! Use /build or /build --run

Teardown (when the task is done)

The simulator created here is task-scoped. Delete it from disk once the task is done - PR merged or work abandoned, not merely session end:

xcrun simctl shutdown "$(cat .claude/.simulator_id)" 2>/dev/null
xcrun simctl delete "$(cat .claude/.simulator_id)"
rm -f .claude/.simulator_id

Each clone holds 1-6 GB of app data and the shared disk runs chronically near-full. convos-task cleanup already deletes its task's sim; every other creation path (worktree /setup, branch /setup, ad-hoc QA clones) must clean up after itself. To sweep accumulated orphans, run .claude/scripts/cleanup-orphaned-sims (dry run by default; add --delete).

Example Flows

In a convos-task worktree:

User: /setup
Claude: Found .convos-task: TASK_NAME=push-notifications, SIMULATOR_NAME=convos-push-notifications
        Running Scripts/setup.sh...
        ✅ All dependencies installed
        Simulator convos-push-notifications exists (A1B2C3D4-...)
        Setting XcodeBuildMCP defaults...

        ✅ Session setup complete

        📱 Simulator: convos-push-notifications (A1B2C3D4-...)
        🔧 XcodeBuildMCP defaults configured
        📁 Project: Convos.xcodeproj
        🎯 Scheme: Convos (Dev)

On a regular branch (no .convos-task):

User: /setup
Claude: No .convos-task found. Deriving from branch name...
        Branch: jarod/retry-errors → Simulator: convos-jarod-retry-errors
        Running Scripts/setup.sh...
        ✅ All dependencies installed
        Cloning iPhone 17 Pro → convos-jarod-retry-errors...
        Created simulator: convos-jarod-retry-errors (E5F6G7H8-...)
        Setting XcodeBuildMCP defaults...

        ✅ Session setup complete

        📱 Simulator: convos-jarod-retry-errors (E5F6G7H8-...)
        🔧 XcodeBuildMCP defaults configured
        📁 Project: Convos.xcodeproj
        🎯 Scheme: Convos (Dev)

Error Handling

If simulator creation fails: Show the error and suggest checking available simulators with xcrun simctl list devices
If no base simulator found: "No iPhone simulator found to clone. Install iOS Simulator runtimes in Xcode."
If Scripts/setup.sh fails: Show the error output and suggest running it manually

Install setup and it becomes one more candidate the router can pick - when it fits.

A listing is a routing target with a manifest: what it does, which domains it covers, what it costs and who publishes it. Once installed it sits beside your own models and tools, is scored like any other candidate for each request, and shows up in the trace when it wins. Ratings come from workspaces that installed it, one per account.

# Setup Initialize the Claude Code session for any branch or worktree — creates a dedicated simulator and configures build defaults. ## Purpose This command sets up an iOS simulator and XcodeBuildMCP session defaults so `/build` and `/build --run` work correctly. It works in any context: - **convos-task worktrees**: Uses the task config from `.convos-task` - **Regular branches**: Derives the simulator name from the current git branch - **Main repo**: Works on any branch, no special setup required ## When to Run - At the start of any new session when working on a feature branch - Automatically suggested at session start when `.convos-task` file exists - Can be run manually anytime to reset or verify the setup ## Instructions ### Step 1: Determine Simulator Name Check for configuration in this order: 1. **`.convos-task` file exists**: Read `TASK_NAME` and `SIMULATOR_NAME` from it 2. **No `.convos-task` file**: Derive from the current git branch: - Run `git branch --show-current` to get the branch name - Sanitize the branch name: replace `/` and special characters with `-`, lowercase it - Simulator name: `convos-<sanitized-branch-name>` - Example: branch `jarod/push-notifications` → simulator `convos-jarod-push-notifications` - Special case: if on `main` or `master`, use `convos-main` ### Step 2: Run Project Setup Run `Scripts/setup.sh` with `CI=true CLAUDE_SETUP=1` — `CI` skips one-time machine setup (git hooks, Xcode defaults, brew installs of the GitHub CLI) and `CLAUDE_SETUP=1` re-enables the `.env` / Firebase debug token check so missing `.env` symlinks in worktrees surface as warnings: ```bash CI=true CLAUDE_SETUP=1 Scripts/setup.sh ``` This ensures SwiftLint, SwiftFormat, and other dependencies are installed, and surfaces any `.env` gap that would otherwise cause Firebase App Check failures at runtime. ### Step 3: Create Simulator if Needed 1. Use `mcp__XcodeBuildMCP__list_sims` to check if the simulator already exists 2. If the simulator doesn't exist: - Find a base iPhone simulator to clone from (prefer iPhone 17 Pro, iPhone 17 Pro Max, or latest available) - Use bash to clone it: `xcrun simctl clone "BASE_SIM_NAME" "SIMULATOR_NAME"` 3. Get the simulator's UUID from the list ### Step 4: Set XcodeBuildMCP Session Defaults Call `mcp__XcodeBuildMCP__session-set-defaults` with: - `simulatorName`: The simulator name (e.g., "convos-push-notifications") - `projectPath`: Path to `Convos.xcodeproj` - `scheme`: "Convos (Dev)" (default scheme) - `useLatestOS`: true ### Step 5: Save Simulator ID for Session Write the simulator UUID to `.claude/.simulator_id` for use by `/build` command. ### Step 6: Report Setup Complete Inform the user: ``` ✅ Session setup complete 📱 Simulator: SIMULATOR_NAME (UUID) 🔧 XcodeBuildMCP defaults configured 📁 Project: Convos.xcodeproj 🎯 Scheme: Convos (Dev) Ready to build! Use /build or /build --run ``` ## Teardown (when the task is done) The simulator created here is task-scoped. Delete it from disk once the task is done - PR merged or work abandoned, not merely session end: ```bash xcrun simctl shutdown "$(cat .claude/.simulator_id)" 2>/dev/null xcrun simctl delete "$(cat .claude/.simulator_id)" rm -f .claude/.simulator_id ``` Each clone holds 1-6 GB of app data and the shared disk runs chronically near-full. `convos-task cleanup` already deletes its task's sim; every other creation path (worktree /setup, branch /setup, ad-hoc QA clones) must clean up after itself. To sweep accumulated orphans, run `.claude/scripts/cleanup-orphaned-sims` (dry run by default; add `--delete`). ## Example Flows **In a convos-task worktree:** ``` User: /setup Claude: Found .convos-task: TASK_NAME=push-notifications, SIMULATOR_NAME=convos-push-notifications Running Scripts/setup.sh... ✅ All dependencies installed Simulator convos-push-notifications exists (A1B2C3D4-...) Setting XcodeBuildMCP defaults... ✅ Session setup complete 📱 Simulator: convos-push-notifications (A1B2C3D4-...) 🔧 XcodeBuildMCP defaults configured 📁 Project: Convos.xcodeproj 🎯 Scheme: Convos (Dev) ``` **On a regular branch (no .convos-task):** ``` User: /setup Claude: No .convos-task found. Deriving from branch name... Branch: jarod/retry-errors → Simulator: convos-jarod-retry-errors Running Scripts/setup.sh... ✅ All dependencies installed Cloning iPhone 17 Pro → convos-jarod-retry-errors... Created simulator: convos-jarod-retry-errors (E5F6G7H8-...) Setting XcodeBuildMCP defaults... ✅ Session setup complete 📱 Simulator: convos-jarod-retry-errors (E5F6G7H8-...) 🔧 XcodeBuildMCP defaults configured 📁 Project: Convos.xcodeproj 🎯 Scheme: Convos (Dev) ``` ## Error Handling - If simulator creation fails: Show the error and suggest checking available simulators with `xcrun simctl list devices` - If no base simulator found: "No iPhone simulator found to clone. Install iOS Simulator runtimes in Xcode." - If `Scripts/setup.sh` fails: Show the error output and suggest running it manually

{ "prompt": "# Setup\n\nInitialize the Claude Code session for any branch or worktree — creates a dedicated simulator and configures build defaults.\n\n## Purpose\n\nThis command sets up an iOS simulator and XcodeBuildMCP session defaults so `/build` and `/build --run` work correctly. It works in any context:\n- **convos-task worktrees**: Uses the task config from `.convos-task`\n- **Regular branches**: Derives the simulator name from the current git branch\n- **Main repo**: Works on any branch, no special setup required\n\n## When to Run\n\n- At the start of any new session when working on a feature branch\n- Automatically suggested at session start when `.convos-task` file exists\n- Can be run manually anytime to reset or verify the setup\n\n## Instructions\n\n### Step 1: Determine Simulator Name\n\nCheck for configuration in this order:\n\n1. **`.convos-task` file exists**: Read `TASK_NAME` and `SIMULATOR_NAME` from it\n2. **No `.convos-task` file**: Derive from the current git branch:\n - Run `git branch --show-current` to get the branch name\n - Sanitize the branch name: replace `/` and special characters with `-`, lowercase it\n - Simulator name: `convos-<sanitized-branch-name>`\n - Example: branch `jarod/push-notifications` → simulator `convos-jarod-push-notifications`\n - Special case: if on `main` or `master`, use `convos-main`\n\n### Step 2: Run Project Setup\n\nRun `Scripts/setup.sh` with `CI=true CLAUDE_SETUP=1` — `CI` skips one-time machine setup (git hooks, Xcode defaults, brew installs of the GitHub CLI) and `CLAUDE_SETUP=1` re-enables the `.env` / Firebase debug token check so missing `.env` symlinks in worktrees surface as warnings:\n\n```bash\nCI=true CLAUDE_SETUP=1 Scripts/setup.sh\n```\n\nThis ensures SwiftLint, SwiftFormat, and other dependencies are installed, and surfaces any `.env` gap that would otherwise cause Firebase App Check failures at runtime.\n\n### Step 3: Create Simulator if Needed\n\n1. Use `mcp__XcodeBuildMCP__list_sims` to check if the simulator already exists\n2. If the simulator doesn't exist:\n - Find a base iPhone simulator to clone from (prefer iPhone 17 Pro, iPhone 17 Pro Max, or latest available)\n - Use bash to clone it: `xcrun simctl clone \"BASE_SIM_NAME\" \"SIMULATOR_NAME\"`\n3. Get the simulator's UUID from the list\n\n### Step 4: Set XcodeBuildMCP Session Defaults\n\nCall `mcp__XcodeBuildMCP__session-set-defaults` with:\n- `simulatorName`: The simulator name (e.g., \"convos-push-notifications\")\n- `projectPath`: Path to `Convos.xcodeproj`\n- `scheme`: \"Convos (Dev)\" (default scheme)\n- `useLatestOS`: true\n\n### Step 5: Save Simulator ID for Session\n\nWrite the simulator UUID to `.claude/.simulator_id` for use by `/build` command.\n\n### Step 6: Report Setup Complete\n\nInform the user:\n```\n✅ Session setup complete\n\n📱 Simulator: SIMULATOR_NAME (UUID)\n🔧 XcodeBuildMCP defaults configured\n📁 Project: Convos.xcodeproj\n🎯 Scheme: Convos (Dev)\n\nReady to build! Use /build or /build --run\n```\n\n## Teardown (when the task is done)\n\nThe simulator created here is task-scoped. Delete it from disk once the task\nis done - PR merged or work abandoned, not merely session end:\n\n```bash\nxcrun simctl shutdown \"$(cat .claude/.simulator_id)\" 2>/dev/null\nxcrun simctl delete \"$(cat .claude/.simulator_id)\"\nrm -f .claude/.simulator_id\n```\n\nEach clone holds 1-6 GB of app data and the shared disk runs chronically\nnear-full. `convos-task cleanup` already deletes its task's sim; every other\ncreation path (worktree /setup, branch /setup, ad-hoc QA clones) must clean\nup after itself. To sweep accumulated orphans, run\n`.claude/scripts/cleanup-orphaned-sims` (dry run by default; add `--delete`).\n\n## Example Flows\n\n**In a convos-task worktree:**\n```\nUser: /setup\nClaude: Found .convos-task: TASK_NAME=push-notifications, SIMULATOR_NAME=convos-push-notifications\n Running Scripts/setup.sh...\n ✅ All dependencies installed\n Simulator convos-push-notifications exists (A1B2C3D4-...)\n Setting XcodeBuildMCP defaults...\n\n ✅ Session setup complete\n\n 📱 Simulator: convos-push-notifications (A1B2C3D4-...)\n 🔧 XcodeBuildMCP defaults configured\n 📁 Project: Convos.xcodeproj\n 🎯 Scheme: Convos (Dev)\n```\n\n**On a regular branch (no .convos-task):**\n```\nUser: /setup\nClaude: No .convos-task found. Deriving from branch name...\n Branch: jarod/retry-errors → Simulator: convos-jarod-retry-errors\n Running Scripts/setup.sh...\n ✅ All dependencies installed\n Cloning iPhone 17 Pro → convos-jarod-retry-errors...\n Created simulator: convos-jarod-retry-errors (E5F6G7H8-...)\n Setting XcodeBuildMCP defaults...\n\n ✅ Session setup complete\n\n 📱 Simulator: convos-jarod-retry-errors (E5F6G7H8-...)\n 🔧 XcodeBuildMCP defaults configured\n 📁 Project: Convos.xcodeproj\n 🎯 Scheme: Convos (Dev)\n```\n\n## Error Handling\n\n- If simulator creation fails: Show the error and suggest checking available simulators with `xcrun simctl list devices`\n- If no base simulator found: \"No iPhone simulator found to clone. Install iOS Simulator runtimes in Xcode.\"\n- If `Scripts/setup.sh` fails: Show the error output and suggest running it manually", "variables": [], "notes": "Initialize the Claude Code session for any branch or worktree — creates a dedicated simulator and configures build defaults.", "metadata": { "source": { "provider": "github-claude-commands", "repository": "https://github.com/xmtplabs/convos-ios", "path": ".claude/commands/setup.md", "ref": "bfbb918f7eb5c67f1729eedd371aba9bb80c002f", "url": "https://github.com/xmtplabs/convos-ios/blob/bfbb918f7eb5c67f1729eedd371aba9bb80c002f/.claude/commands/setup.md", "key": "xmtplabs/convos-ios/.claude/commands/setup.md" } } }

setup

About

Setup

Purpose

When to Run

Instructions

Step 1: Determine Simulator Name

Step 2: Run Project Setup

Step 3: Create Simulator if Needed

Step 4: Set XcodeBuildMCP Session Defaults

Step 5: Save Simulator ID for Session

Step 6: Report Setup Complete

Teardown (when the task is done)

Example Flows

Error Handling

Install setup and it becomes one more candidate the router can pick - when it fits.

What it costs to adopt - in engineering time.

One base URL

No vendor lock-in

Failover built in

Use it

Manifest

Reviews