Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
xbq
✓ npm install -g xcode-build-queue
xbq --version
✗ import { xbq } from 'xcode-build-queue'
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.
xbq init
✓ xbq init ~/path/to/your/project
Initializes the xbq system for a specified Xcode project, configuring the main repository for build queuing.
xbq config
✓ xbq config set backend xcodebuild
✗ edit ~/.bq/config.json
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.
xbq fleet
✓ xbq fleet launch my-experiment -p "refactor auth module"
Manages parallel Claude Code sessions across worktrees, using templates for consistent session setup and tracking.
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.
const { execSync } = require('child_process');
const path = require('path');
const os = require('os');
// Ensure xbq is installed globally. For a real scenario, handle installation checks robustly.
try {
execSync('npm list -g xcode-build-queue', { stdio: 'ignore' });
console.log('xcode-build-queue is already installed globally.');
} catch (error) {
console.log('Installing xcode-build-queue globally...');
execSync('npm install -g xcode-build-queue', { stdio: 'inherit' });
console.log('xcode-build-queue installed.');
}
// Define a dummy Xcode project path for demonstration purposes.
const xcodeProjectPath = path.join(os.tmpdir(), 'MyDummyXcodeProject');
console.log(`\nSetting up dummy Xcode project directory at: ${xcodeProjectPath}`);
execSync(`mkdir -p ${xcodeProjectPath}/.git`, { stdio: 'inherit' }); // Simulate a git repo for xbq init
try {
// 1. Initialize xbq for the dummy Xcode project
console.log('\n--- Initializing xbq ---');
execSync(`xbq init ${xcodeProjectPath}`, { stdio: 'inherit' });
// 2. Start the xbq daemon. In a real setup, this would run as a background service.
console.log('\n--- Starting xbq daemon (in background) ---');
execSync('xbq daemon start', { stdio: 'inherit' });
// 3. Configure a separate test scheme (feature introduced in v0.6.0)
console.log('\n--- Configuring default test scheme ---');
execSync('xbq config set default_test_scheme MyUnitTestsScheme', { stdio: 'inherit' });
// 4. Simulate a build request from a worktree.
// This command will queue a build. It will likely fail without a real Xcode project.
console.log('\n--- Simulating a build request (expected to fail for dummy project) ---');
try {
execSync(`xbq build --project-path ${xcodeProjectPath}`, { stdio: 'inherit' });
} catch (buildError) {
console.warn(`xbq build command failed as expected for dummy project: ${buildError.message.split('\n')[0]}`);
}
// 5. Check fleet status to see managed sessions
console.log('\n--- Checking xbq fleet status ---');
execSync('xbq fleet status', { stdio: 'inherit' });
} catch (error) {
console.error('\nAn unhandled error occurred during xbq quickstart:', error.message);
} finally {
// Attempt to stop the daemon and clean up the temporary directory
console.log('\n--- Attempting cleanup ---');
try {
execSync('xbq daemon stop', { stdio: 'inherit' });
} catch (cleanupError) {
console.warn('Failed to stop xbq daemon:', cleanupError.message.split('\n')[0]);
}
console.log(`Cleaning up dummy Xcode project directory: ${xcodeProjectPath}`);
execSync(`rm -rf ${xcodeProjectPath}`, { stdio: 'inherit' });
console.log('Cleanup complete.');
}
xbq --version
Errors
Common errors & fixes
command not found: xbq
The `xcode-build-queue` package is not installed globally or is not in your system's PATH.
fixInstall the package globally: `npm install -g xcode-build-queue`.
Error: The provided path is not a git repository.
`xbq init` requires the target project directory to be a valid Git repository.
fixNavigate 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`.
Validation Error: Invalid value for backend. Must be 'mcp' or 'xcodebuild'.
An attempt was made to set an unsupported value for the `backend` configuration key.
fixUse a valid backend value: `xbq config set backend mcp` or `xbq config set backend xcodebuild`.
Audit
Dependencies
git-restore-mtimeoptionalOptional dependency installed via pip3 for optimal incremental build performance after branch switches.