A calm desktop client for the Mihomo proxy core.
Go + MyGo app · React UI · Agent-friendly CLI
Features · Quick Start · Usage · Architecture · Docs · Roadmap
Kumo connects you through Mihomo without turning proxy management into a network operations dashboard. The first screen answers four questions: is Kumo connected, which mode is active, is the system proxy on, and which profile and nodes are in use. DNS, TUN, rules, logs, overrides and the routing topology stay one click away.
| Area | What Kumo provides |
|---|---|
| Desktop app | One Go binary built with MyGo: a native window with a React + coss ui frontend, a menu bar item and notifications. |
| Topology | A React Flow canvas of entry → rules → groups → nodes, with selected paths, dynamic members, broken references and a text inspector. |
| Leaves no trace | Quitting, or a crash caught by the guardian process, stops the core and clears the system proxy — only if Kumo still owns it. |
| Plays well with others | Another app taking over the system proxy is shown, not fought; a port held by another program is named, with a free port offered. |
| CLI for humans and agents | The same executable as kumo: stable commands, --json, dry-run, predictable exit codes. |
| Agent guidance | Each page copies a ready prompt for a coding agent; the Kumo skill installs for Claude Code, Codex, Cursor, Gemini CLI and .agents. |
| First run | A guided setup with an animated preview of each step. |
Download the disk image from Releases, open Kumo and follow Setup. It finds a Mihomo you have, or downloads one.
Requires Go 1.27+, Bun and, on Linux, WebKitGTK.
bun install
make dev # live reload
make build # package into build/
make check # generate, go vet/test, typecheck, FSD and message checks| Group | Pages |
|---|---|
| Daily | Overview, Profiles, Proxies, Topology |
| Inspect | Connections, Logs, Rules |
| Configure | Core, System Proxy, DNS, TUN, Sniffer, Resources, Overrides |
| Kumo | Agents, Settings, About |
kumo status --json
kumo start
kumo proxies --json
kumo select Proxy "Tokyo 01"
kumo sysproxy on
kumo topology --issues
kumo prompt proxies # a ready-made prompt for a coding agent
kumo -l # every commandinternal/domain rules: runtime, system proxy ownership, profiles, overrides, config, topology
internal/application use cases shared by the app, the CLI and the guardian
internal/infrastructure storage, Mihomo client/launcher, system proxy, ports, processes
internal/interfaces cli (kumo) and desktop (MyGo bindings, window, tray, quit path)
src/ React frontend in Feature-Sliced Design: app, pages, widgets, features, entities, shared
The backend follows Domain-Driven Design; the frontend follows Feature-Sliced Design. See docs/README.md.
- Product · Interfaces · Core · Operations · Quality · Roadmap
- Agent index for coding agents working on Kumo.
- Read AGENTS.md and the document under docs/ for your change.
- Keep business rules in
internal/domainandinternal/application; surfaces only call services. - Run
make check; for lifecycle changes alsomake e2e MIHOMO=<path>. - Update
docs/in the same change when behavior, architecture, persistence, permissions or tests change.
Kumo is licensed under the GNU Affero General Public License v3.0 only (AGPL-3.0-only). See LICENSE for the full text.
Third-party components bundled or used by Kumo may be licensed under different terms. See THIRD_PARTY_NOTICES.md.
- Mihomo, the proxy core Kumo drives.
- The Clash and Mihomo ecosystem, for the controller API conventions Kumo speaks.
- MyGo, Base UI, coss ui and React Flow.