Build from source

Kumo can be built from source in about fifteen minutes.

Requirements

macOS 15 Sequoia or later on Apple Silicon. The app uses APIs that are not available on macOS 14 or x86_64.
Xcode 16 or later with the Swift 6.0 toolchain. Install from the App Store, then open it once so the Command Line Tools settle.
Git (ships with Xcode's Command Line Tools).
Optional but recommended: XcodeGen for regenerating the Xcode project from project.yml (brew install xcodegen).

Mihomo does not need to be installed manually. Kumo can download a managed copy on first launch.

Clone and build

Clone the repository

git clone https://github.com/ProjectKumo/KumoApp.git
cd KumoApp

Build the Swift package

make swift-build

This compiles every product — the app, the CLI, the shared library, and the service binary — in debug mode. The first build takes a few minutes while SwiftPM resolves dependencies.

Run the app

make dev

make dev quits any running Kumo, rebuilds the .app bundle, and opens the debug build. The window appears with Overview selected.

Try the CLI

make run-cli ARGS="status --json"

The output should be a JSON envelope like:

{
  "ok": true,
  "data": { "running": false, "mode": "rule", "...": "..." },
  "error": null
}

make run-cli ARGS="..." is equivalent to running the kumo executable with those arguments, but it always uses the current debug build.

Useful make targets

The Makefile is the source of truth for build and test workflows. Read it whenever something behaves unexpectedly — it's short.

Target	What it does
`make help`	Print every target with a one-line description.
`make swift-build`	`swift build` for every product.
`make build-release`	`swift build -c release`.
`make app`	Build the `.app` bundle into `build/Build/Products/Debug/`.
`make app-release`	Build a Release-configuration `.app`.
`make dev`	Quit, rebuild, and re-open the debug app. The fastest inner loop.
`make run-app`	Launch the SwiftUI app via `swift run` (no `.app` bundle).
`make run-cli ARGS="..."`	Invoke the CLI with arbitrary arguments.
`make swift-test`	Run unit tests with SwiftPM.
`make xcode-test`	Run unit tests via `xcodebuild`.
`make check`	Build + test + smoke-check `kumo status --json`.
`make release-dmg VERSION=0.0.1`	Build the Release app and a notarizable DMG.
`make reset-local-state`	Wipe `~/Library/Application Support/Kumo/`.
`make clean`	Remove SwiftPM build artefacts.

make reset-local-state deletes profiles, overrides, and Sub-Store data from the local Kumo install. Use it when a true first-launch state is needed — not when data is important.

Running from Xcode

If Xcode is preferred over the command line:

make generate          # regenerate Kumo.xcodeproj from project.yml
open Kumo.xcodeproj

Pick the KumoApp scheme and hit ⌘R. The shared library, the CLI, and the service are all part of the same workspace.

To run package tests in Xcode, switch to the Kumo-Package scheme.

Common build failures

xcodegen: command not found — install with brew install xcodegen, or skip make generate and use SwiftPM (make swift-build, make run-app).
Sub-Store preparation step fails — make prepare-substore-runtime is invoked by make swift-build. It downloads a Node runtime into Sources/KumoCoreKit/Resources/SubStore/. If the network is blocking that, set KUMO_SKIP_SUBSTORE=1 for a quick rebuild while working on something unrelated.
Old derived data — Xcode caches can survive a Swift toolchain upgrade. make clean && make swift-build clears them.
Intel Mac — Kumo v1 is Apple Silicon only. The build will succeed, but several runtime features are gated on arm64.

Inner loop tips

For UI changes, use make dev. It is the fastest way to see an edit in the actual .app.
For CLI changes, make run-cli ARGS="..." is faster than rebuilding the app.
For KumoCoreKit changes, write a unit test in Tests/KumoCoreTests and run swift test. The test target is intentionally lightweight and starts quickly.
Keep tail -F ~/Library/Application Support/Kumo/logs/core.log open in a side terminal — it is the best view into what Mihomo is doing.

On this page