Contributing

Kumo is an open project under AGPL-3.0-only.

This track assumes familiarity with the terminal and Swift. No macOS systems engineering background is required — typo fixes, error-message improvements, and UI clarifications are all valid contributions.

Where to start

Set up your machine

Clone the repo, install Xcode 16, and run Kumo from source.

Tour the repository

What lives where — modules, scripts, tests, docs.

Understand the architecture

The four-module split and why the GUI doesn't drive Mihomo directly.

File a great issue

What we need to reproduce a bug, and what makes a feature request actionable.

Open a pull request

Branching, commit style, tests, and the review loop.

Write or fix docs

These docs are MDX. You can change them with a PR like any other code.

Ground rules

Be kind. Reviewers, reporters, and other contributors are real people.
One change per PR. Small, focused diffs land faster.
Tests are part of the change. If you fix a bug, add a test that would have caught it.
Docs are part of the change. If your patch alters product behaviour, permissions, runtime configuration, or persistence, update the relevant document in the same PR.
English in user-visible copy unless the change is specifically about localization.

If you're not sure whether a change is welcome, open a discussion or a draft PR first. Early feedback prevents wasted effort.

Good first changes

Fix a typo or broken link in these docs (Kumo-docs).
Improve an error message in KumoCoreKit so the cause is obvious from the CLI output.
Tighten or clarify a UI string in KumoApp (read AGENTS.md first — copy conventions matter here).
Add a missing test for a KumoCoreKit model or helper.

If something looks easy on the surface but turns out to be structural, ask in the issue or PR. Someone will help find a safe scope.