Cadmus
Swift and Objective-C language intelligence, builds and debugging for VS Code and Cursor on macOS.
Cadmus connects sourcekit-lsp to Xcode's build engine through the Build Server Protocol. It provides compiler arguments and prepares dependencies for completion, navigation, references and diagnostics across Xcode projects.
Requirements
- macOS with Xcode 26 or later selected using
xcode-select.
- An Xcode workspace or project. Generate it first if the repository uses Tuist or another project generator.
- The Swift and LLDB DAP extensions, installed automatically as extension dependencies.
The helper is universal (Apple silicon and Intel); Intel execution has not been validated.
Pure Swift packages use sourcekit-lsp's native SwiftPM support.
Getting started
Open the project folder and select the .xcworkspace or .xcodeproj when prompted. Cadmus writes buildServer.json and starts preparing the semantic index. Navigation becomes available progressively; the sidebar shows preparation and build progress.
Use Cadmus: Select Build Scheme and Cadmus: Change Destination to choose the intended scheme and platform. Existing project files are read without modification.
Use Cadmus: Build, Cadmus: Run, or Cadmus: Debug (LLDB) to build and launch. macOS and iOS simulator apps support LLDB debugging; simulator runs require a booted simulator. Device provisioning and distribution signing are not covered.
An optional menu bar app shows indexing and build activity. The first installation asks for confirmation; later bundled updates install automatically when enabled in settings.
Configuration
| Setting |
Default |
Description |
cadmus.helperPath |
auto-detect |
Path to the cadmus-helper binary (bundled binary used if empty) |
cadmus.platform |
macosx |
Target platform for indexing (iphonesimulator, iphoneos, macosx, …) |
cadmus.configuration |
Debug |
Build configuration to index and serve compiler arguments for |
cadmus.derivedDataPath |
<project>/.cadmus |
Custom DerivedData path |
cadmus.prepareBatchSize |
1 |
Targets per buildTarget/prepare request during background indexing |
cadmus.indexStoreTimeout |
300 |
Per-file indexing timeout (seconds) for sourcekit-lsp background indexing |
cadmus.backgroundIndexingCores |
0.75 |
Fraction of CPU cores sourcekit-lsp may use for background indexing |
cadmus.writeSourceKitLSPConfig |
true |
Whether Cadmus writes .sourcekit-lsp/config.json (see below) |
cadmus.autoInstallMenuBarApp |
true |
Install/update the bundled menu bar app on activation (first install asks; updates are silent) |
cadmus.debugLogging |
false |
Verbose narration: per-target prepare lines in the output channel, --log-level debug in the helper's BSP log |
The three tuning settings above are delivered to sourcekit-lsp through <project>/.sourcekit-lsp/config.json, which Cadmus writes with a _managedBy: "cadmus" marker: preparationBatchingStrategy (batching is ignored harmlessly by sourcekit-lsp versions without support), index.updateIndexStoreTimeout, and index.maxCoresPercentageToUseForBackgroundIndexing. Cadmus never overwrites a config it did not create — a user-authored file always wins. Set cadmus.writeSourceKitLSPConfig: false to manage the file entirely yourself.
Commands
| Command |
Description |
| Cadmus: Select Xcode Workspace |
Choose which workspace/project to index |
| Cadmus: Restart Indexing |
Restart the build server |
| Cadmus: Select Build Scheme |
Choose the scheme that determines the bootstrap target |
| Cadmus: Change Destination |
Switch target platform (clears the args cache) |
| Cadmus: Clear Cache |
Delete the compiler-args disk cache |
| Cadmus: Retrigger Indexing |
"With Cache" (restart only) or "Clean" (delete cache + index store, then restart) |
| Cadmus: Open BSP Server Log |
Open the helper's BSP log in the editor |
| Cadmus: Open SWB Bridge Log |
Open the bridge daemon log in the editor |
| Cadmus: Open Output Channel |
Show the extension's output channel |
| Cadmus: Refresh View |
Refresh the sidebar |
| Cadmus: Build |
Real build — diagnostics land in the Problems panel |
| Cadmus: Run |
Build, then launch (macOS: opens the app; simulator: installs + launches on the booted device) |
| Cadmus: Debug (LLDB) |
Build, then launch under LLDB for breakpoint debugging (macOS and iOS simulator apps) |
| Cadmus: Select Build Target |
Pick the target builds start from (default: the application target) |
Builds are also available as tasks (Terminal → Run Task → cadmus: build/run, bindable to
⇧⌘B via tasks.json with "type": "cadmus"), with a contributed $cadmus problem matcher.
Running is also wired into the native Run and Debug view: press F5 in a Swift file (or pick
"Cadmus: Run App" from the run dropdown, no launch.json needed) — the app's output streams
into the Debug Console and the stop button terminates it. It launches without a debugger
attached; launch.json accepts target, configuration, platform, buildBeforeRun.
For breakpoint debugging, pick "Cadmus: Debug App (LLDB)" (or set "debug": true in a
cadmus launch configuration): cadmus builds the target, computes the product's executable
path (cadmus-helper product-path), and hands the launch to the
LLDB DAP
extension pointed at Xcode's toolchain lldb-dap (xcrun -f lldb-dap) — the LLDB that carries
Swift's type-system plugin, so po and frame variables work. Without it, plain LLDB reports
"TypeSystem for language swift doesn't exist". Falls back to the Swift extension's adapter, then
CodeLLDB. Simulator debugging installs the app, launches it suspended, and attaches LLDB.
Run cadmus-helper mcp to expose project discovery, setup, indexing, semantic queries and builds to an MCP client. The server uses JSON-RPC over standard input/output. The helper is bundled at bin/cadmus-helper inside the installed extension.
Start with inspect_project, follow the repository's setup instructions, and explicitly generate a Tuist workspace when needed. Use setup_project for an existing language server, or query_code when the client only supports MCP. Use start_build and poll build_status for long builds; cancel_build stops an owned build.
Compatibility
Cadmus uses Xcode's private build service protocol. Xcode updates can change that protocol; report the Xcode version and the Cadmus output log when diagnosing a failure. Native compatibility fixtures are verified against Xcode 26.2.
Acknowledgements
Cadmus uses swift-build and sourcekit-lsp.
License
GPL-3.0.
