{"id":14371,"library":"xcode-build-queue","title":"xbq - Xcode Build Queue","description":"xbq is a command-line interface (CLI) tool designed to manage serial Xcode builds for projects utilizing Git worktrees. It aims to solve the problem of duplicating large `DerivedData` and Swift Package Manager (SPM) resolution caches when running multiple concurrent AI coding sessions (e.g., Claude Code) on the same Xcode project. By routing all build and test requests through a single 'main' repository, it significantly reduces disk space usage and prevents `DerivedData` corruption. The current stable version is `0.6.0`, with a consistent, albeit irregular, release cadence that introduces new features and fixes. Key differentiators include its snapshot-based build process (no commit required), strict serial queue enforcement, and robust worktree management, making it an essential tool for environments leveraging AI-driven development with Xcode.","status":"active","version":"0.6.0","language":"javascript","source_language":"en","source_url":"https://github.com/a-ulkhan/xbq","tags":["javascript","xcode","build","queue","worktree","swift","ios"],"install":[{"cmd":"npm install xcode-build-queue","lang":"bash","label":"npm"},{"cmd":"yarn add xcode-build-queue","lang":"bash","label":"yarn"},{"cmd":"pnpm add xcode-build-queue","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Optional dependency installed via pip3 for optimal incremental build performance after branch switches.","package":"git-restore-mtime","optional":true}],"imports":[{"note":"This package is a global CLI tool, not a library for programmatic import within JavaScript/TypeScript. Its functionality is accessed via the `xbq` command in the terminal after global npm installation.","wrong":"import { xbq } from 'xcode-build-queue'","symbol":"xbq","correct":"npm install -g xcode-build-queue\nxbq --version"},{"note":"Initializes the xbq system for a specified Xcode project, configuring the main repository for build queuing.","symbol":"xbq init","correct":"xbq init ~/path/to/your/project"},{"note":"Since v0.2.0, all configuration should be managed via the `xbq config` CLI commands. Direct manual editing of `~/.bq/config.json` is discouraged and can lead to validation issues.","wrong":"edit ~/.bq/config.json","symbol":"xbq config","correct":"xbq config set backend xcodebuild"},{"note":"Manages parallel Claude Code sessions across worktrees, using templates for consistent session setup and tracking.","symbol":"xbq fleet","correct":"xbq fleet launch my-experiment -p \"refactor auth module\""}],"quickstart":{"code":"const { execSync } = require('child_process');\nconst path = require('path');\nconst os = require('os');\n\n// Ensure xbq is installed globally. For a real scenario, handle installation checks robustly.\ntry {\n  execSync('npm list -g xcode-build-queue', { stdio: 'ignore' });\n  console.log('xcode-build-queue is already installed globally.');\n} catch (error) {\n  console.log('Installing xcode-build-queue globally...');\n  execSync('npm install -g xcode-build-queue', { stdio: 'inherit' });\n  console.log('xcode-build-queue installed.');\n}\n\n// Define a dummy Xcode project path for demonstration purposes.\nconst xcodeProjectPath = path.join(os.tmpdir(), 'MyDummyXcodeProject');\nconsole.log(`\\nSetting up dummy Xcode project directory at: ${xcodeProjectPath}`);\nexecSync(`mkdir -p ${xcodeProjectPath}/.git`, { stdio: 'inherit' }); // Simulate a git repo for xbq init\n\ntry {\n  // 1. Initialize xbq for the dummy Xcode project\n  console.log('\\n--- Initializing xbq ---');\n  execSync(`xbq init ${xcodeProjectPath}`, { stdio: 'inherit' });\n\n  // 2. Start the xbq daemon. In a real setup, this would run as a background service.\n  console.log('\\n--- Starting xbq daemon (in background) ---');\n  execSync('xbq daemon start', { stdio: 'inherit' });\n\n  // 3. Configure a separate test scheme (feature introduced in v0.6.0)\n  console.log('\\n--- Configuring default test scheme ---');\n  execSync('xbq config set default_test_scheme MyUnitTestsScheme', { stdio: 'inherit' });\n\n  // 4. Simulate a build request from a worktree.\n  // This command will queue a build. It will likely fail without a real Xcode project.\n  console.log('\\n--- Simulating a build request (expected to fail for dummy project) ---');\n  try {\n    execSync(`xbq build --project-path ${xcodeProjectPath}`, { stdio: 'inherit' });\n  } catch (buildError) {\n    console.warn(`xbq build command failed as expected for dummy project: ${buildError.message.split('\\n')[0]}`);\n  }\n\n  // 5. Check fleet status to see managed sessions\n  console.log('\\n--- Checking xbq fleet status ---');\n  execSync('xbq fleet status', { stdio: 'inherit' });\n\n} catch (error) {\n  console.error('\\nAn unhandled error occurred during xbq quickstart:', error.message);\n} finally {\n  // Attempt to stop the daemon and clean up the temporary directory\n  console.log('\\n--- Attempting cleanup ---');\n  try {\n    execSync('xbq daemon stop', { stdio: 'inherit' });\n  } catch (cleanupError) {\n    console.warn('Failed to stop xbq daemon:', cleanupError.message.split('\\n')[0]);\n  }\n  console.log(`Cleaning up dummy Xcode project directory: ${xcodeProjectPath}`);\n  execSync(`rm -rf ${xcodeProjectPath}`, { stdio: 'inherit' });\n  console.log('Cleanup complete.');\n}","lang":"javascript","description":"This script demonstrates the installation, initialization, daemon startup, configuration, and a simulated build request using the `xbq` command-line interface via Node.js `child_process`. It illustrates typical setup and interaction patterns."},"warnings":[{"fix":"Always use the `xbq config` CLI commands (e.g., `xbq config set backend xcodebuild`) to manage xbq settings.","message":"Direct manual editing of the configuration file (`~/.bq/config.json`) is no longer supported and can lead to validation errors or unexpected behavior.","severity":"gotcha","affected_versions":">=0.2.0"},{"fix":"Install `git-restore-mtime` via `pip3 install git-restore-mtime` for improved build performance.","message":"Suboptimal incremental build performance might be observed after Git branch switches without `git-restore-mtime` installed.","severity":"gotcha","affected_versions":"all"},{"fix":"Set `default_test_scheme` and `default_test_plan` (if applicable) using `xbq config set default_test_scheme MyUnitTests`.","message":"If `xbq test` is used and a separate test scheme is intended, configuring it explicitly is required. The `default_scheme` setting now only applies to `xbq build`.","severity":"gotcha","affected_versions":">=0.6.0"}],"env_vars":null,"search_vec":"'0.6.0':84 'ai':46,127 'ai-driven':126 'aim':26 'albeit':88 'base':104 'build':3,19,60,105,134 'cach':41 'cadenc':91 'claud':50 'cli':12 'code':47,51 'command':9 'command-lin':8 'commit':108 'concurr':45 'consist':87 'corrupt':78 'current':80 'deriveddata':34,77 'design':14 'develop':129 'differenti':99 'disk':72 'driven':128 'duplic':32 'e.g':49 'enforc':113 'environ':124 'essenti':121 'featur':95 'fix':97 'git':23 'includ':100 'interfac':11 'introduc':93 'io':138 'irregular':89 'javascript':132 'key':98 'larg':33 'leverag':125 'line':10 'main':67 'make':118 'manag':16,38,117 'multipl':44 'new':94 'packag':37 'prevent':76 'problem':30 'process':106 'project':21,56 'queue':4,112,135 'reduc':71 'releas':90 'repositori':68 'request':63 'requir':109 'resolut':40 'robust':115 'rout':58 'run':43 'serial':17,111 'session':48 'signific':70 'singl':66 'snapshot':103 'snapshot-bas':102 'solv':28 'space':73 'spm':39 'stabl':81 'strict':110 'swift':36,137 'test':62 'tool':13,122 'usag':74 'util':22 'version':82 'worktre':24,116,136 'xbq':1,5 'xcode':2,18,55,131,133","created_at":"2026-04-20T01:59:21.758129+00:00","updated_at":"2026-04-20T01:59:21.758129+00:00","problems":[{"fix":"Install the package globally: `npm install -g xcode-build-queue`.","cause":"The `xcode-build-queue` package is not installed globally or is not in your system's PATH.","error":"command not found: xbq"},{"fix":"Navigate to your Xcode project directory and ensure it is initialized as a Git repository (e.g., `git init`). Then run `xbq init ~/path/to/your/project`.","cause":"`xbq init` requires the target project directory to be a valid Git repository.","error":"Error: The provided path is not a git repository."},{"fix":"Use a valid backend value: `xbq config set backend mcp` or `xbq config set backend xcodebuild`.","cause":"An attempt was made to set an unsupported value for the `backend` configuration key.","error":"Validation Error: Invalid value for backend. Must be 'mcp' or 'xcodebuild'."}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"xbq","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/a-ulkhan/xbq","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/xcode-build-queue","openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops","workflow"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}