Repository layout

Top-level layout

KumoApp/
  Sources/                Swift code, one folder per module
    KumoCoreKit/          Shared domain library (no SwiftUI)
    KumoCLI/              The `kumo` executable thin shell
    KumoCLIKit/           CLI command surface (Argument Parser commands)
    KumoApp/              SwiftUI macOS app
    KumoService/          Planned privileged helper (service mode)
  Tests/
    KumoCoreTests/        Unit tests for KumoCoreKit
    KumoCLITests/         Unit tests for the CLI surface
  Resources/              Bundled assets — icons, banner art
  Assets/                 Marketing and README art
  Scripts/                Release scripting, Sub-Store runtime preparation
  docs/                   Engineering documentation (the source of truth
                          for architecture, not these user docs)
  Makefile                Source of truth for build + test workflows
  Package.swift           SwiftPM manifest
  project.yml             XcodeGen project definition
  AGENTS.md               Copy and component constraints for agents
  README.md               Project overview
  LICENSE                 AGPL-3.0-only

The four modules

Kumo deliberately splits responsibility across four libraries.

KumoCoreKit

Everything that is not UI lives here.

KumoCoreKit/
  Models/                 Plain data types (profile metadata, state, modes)
  Configuration/          Profile loading, runtime config generation
  Runtime/                Mihomo process supervision, managed core install
  Networking/             Mihomo external-controller HTTP client
  System/                 networksetup-based system proxy controller
  Service/                Sub-Store sidecar lifecycle
  AgentSkills/            Agent skill bundle installer
  Support/                Paths, state storage, shared errors
  Resources/              Bundled Sub-Store runtime, skill content

KumoCoreKit has zero SwiftUI. It is pure async Swift with Yams for YAML. That separation is what makes the CLI possible — both the app and kumo talk to the same controller.

KumoCLIKit

The command surface. Built on swift-argument-parser. Every CLI command — status, start, mode, select, profile, config, sysproxy, service, tun, substore, skills, backup, doctor, etc. — is a ParsableCommand in here.

The convention is that a command:

1. Validates inputs.
2. Calls into KumoCoreKit for the real work.
3. Renders the result as plain text or JSON.

If Foundation.URLSession or Process is needed inside KumoCLIKit, that logic almost certainly belongs in KumoCoreKit instead.

KumoCLI

A tiny wrapper: the actual executable target. It exists so the library (KumoCLIKit) can be unit-tested without spawning a process.

KumoApp

The SwiftUI macOS app. Uses NavigationSplitView, a Settings scene, an AppKit menu bar status item, and standard SwiftUI controls. Reads UI copy conventions from AGENTS.md.

KumoApp calls into KumoCoreKit directly — it does not duplicate any of the runtime logic.

KumoService

The future privileged helper. Will own TUN control, guarded system proxy changes, and signed-request transport over a Unix socket once service mode ships. Compiles today, but does not yet do useful work in v1.

Scripts

Scripts/ holds the project's release machinery.

These are usually invoked indirectly via the corresponding make targets.

Engineering docs

The docs/ folder is the source of truth for how Kumo is built:

• docs/product/ — product scope and IA.
• docs/interfaces/ — macOS SwiftUI interface, CLI surface.
• docs/core/ — control layer, Mihomo runtime, profile loading.
• docs/operations/ — permissions, persistence, releases.
• docs/roadmap/ — service mode, future work.
• docs/quality/ — testing expectations.
• docs/standards/ — implementation conventions.

These are written for people working on Kumo itself. The docs on this site (the public Kumo-docs) are written for people using Kumo. Both matter.

What's intentionally not in the repo

• No Mihomo binary. Kumo downloads it on first launch or you point at a path. Bundling a closed copy of Mihomo would make Kumo's release schedule depend on Mihomo's.
• No third-party tracking SDKs. Kumo does not phone home for analytics. The only outbound network calls from KumoCoreKit are the Mihomo controller, profile fetches you configure, and (optionally) the update manifest.
• No bundled secrets. Anything that looks like a credential is a bug — please report it.