Filing issues

Issues live at github.com/ProjectKumo/KumoApp/issues. Docs issues live at github.com/ProjectKumo/Kumo-docs/issues.

A well-written issue saves time for everyone. Here's what makes one.

Before you file

A two-minute check that prevents most duplicates:

1. Search existing issues for keywords from the problem. Check both open and closed — closed issues sometimes have the answer.
2. Update to the latest stable Kumo from Releases and try again. The bug may already be fixed.
3. Re-read Troubleshooting. Most "it doesn't work" reports map to one of three known shapes.

What a bug report needs

Copy this template into the issue body:

**What happened**
A clear, one-line description.

**What I expected**
A clear, one-line description.

**Steps to reproduce**
1. Open Kumo
2. ...
3. ...

**Kumo version**
Kumo → About, e.g. 0.0.3 (build 1)

**macOS version and chip**
e.g. macOS 15.4, Apple M2

**`kumo doctor --json` output**
<paste here>

**Relevant logs**
Last 50 lines of:
  ~/Library/Application Support/Kumo/logs/core.log
  ~/Library/Application Support/Kumo/logs/cli/*.log (if CLI-related)

The kumo doctor --json snapshot is the single most useful artifact. It captures the version, the core state, the system proxy state, the controller endpoint, and recent errors in one paste.

What a feature request needs

Knowing what to build is harder than building it. A useful feature request answers:

1. What problem are you trying to solve? Describe the situation, not the proposed solution.
2. What do you do today? Workarounds tell us how urgent the gap is.
3. What would "good" look like? A rough sketch, screenshot, or a reference to how another tool handles it.
4. Who else needs this? Personal preference is fine. Team needs are stronger.

Kumo is intentionally small. Not every request will land — and that is usually a scope decision, not a comment on the request's quality.

Security issues

If you find a security issue — credential leak, privilege escalation, update-flow bypass, etc. — do not open a public issue. Email the address in SECURITY.md instead. We'll triage and credit you in the fix.

What "won't fix" means

Sometimes we close an issue without a code change. The reasons usually are:

• Out of scope. Kumo is a focused Mihomo client. We won't ship a general DNS over HTTPS service, for example.
• Upstream. The bug is in Mihomo or in the macOS system proxy. We link to the upstream tracker when we can.
• Working as intended. What looks like a bug is the documented behaviour. We'll usually take a docs PR to make that clearer.

A "won't fix" close is not a judgement of the reporter. It is a statement about the project's scope.

After you file

• We'll usually triage within a few days.
• If we ask for more information, please answer — silent issues get closed.
• If you find the fix while waiting, an issue is the perfect place to link the pull request.