A calm, native macOS client for the Mihomo proxy core, KumoApp simplifies everyday proxy management. It targets macOS users seeking an efficient interface, offering a SwiftUI-based GUI and an agent-friendly command-line interface (CLI). The primary benefit is streamlined daily proxy operations, keeping advanced network management tools discoverable but secondary to core connection status.

How It Works

The project centers around KumoCoreKit, a shared library managing Mihomo's lifecycle, profile generation, controller interactions, state, and system proxy logic. This core is leveraged by both the SwiftUI macOS application and the kumo CLI executable. This architectural choice ensures code reuse and a consistent control plane. The approach is novel in its focus on an "agent-friendly CLI" with stable commands, --json output, and predictable exit codes, alongside a user-centric SwiftUI GUI that prioritizes daily actions.

Quick Start & Requirements

• Requirements: macOS 15 Sequoia+, Xcode 16+ with Swift 6.0 toolchain, and a Mihomo binary (managed install or manual).
• Build: Clone the repository, cd KumoApp, then make swift-build.
• Run: make run-app for the GUI, make run-cli ARGS="..." for the CLI.
• Docs: UI structure details are in docs/interfaces/macos-swiftui-interface.md.

Highlighted Details

• Native macOS app built with SwiftUI, featuring a NavigationSplitView, AppKit menu bar status item, and standard macOS controls.
• Agent-friendly CLI (kumo) supports stable commands, --json output, dry-run system changes, and predictable exit codes.
• Safe defaults include generating direct configs for empty profiles and dry-running system proxy changes.
• Focused UI design prioritizes daily actions (Overview, Profiles, Proxies) while keeping inspection and configuration tools accessible.

Maintenance & Community

• The project roadmap is detailed in docs/roadmap/service-mode-roadmap.md.
• Contributions are welcome, with guidelines provided in AGENTS.md. Documentation updates are required for meaningful changes.

Licensing & Compatibility

• License: GNU Affero General Public License v3.0 only (AGPL-3.0-only).
• Compatibility: AGPL-3.0-only is a strong copyleft license. Derivative works must also be AGPL-3.0-only, potentially restricting integration into closed-source or proprietary applications without compliance.

Limitations & Caveats

The v1 SwiftUI layout is still being finalized. Version 1 intentionally omits privileged helpers; advanced features like service mode are planned for future iterations. Requires macOS 15 Sequoia and Xcode 16+.