clash-verge-auto-switch

Use when the user wants Codex to speed test Clash Verge Rev or Mihomo proxies, auto-detect currently used Clash groups from the live controller, switch a sel...

Security Scan

The skill's code and instructions are coherent with its stated purpose (discover a local Clash controller, speed-test proxies, and optionally install a macOS launchd job); it does access local Clash config and environment variables and can create a persistent user LaunchAgent, so users should review and consent before installing.

Purpose & Capability

Name/description match the implementation: the scripts discover a local Mihomo/Clash controller (via explicit args, CLASH_API_* env vars, or local config files), call the controller API, run latency tests, and switch selector groups. No unrelated cloud credentials or unrelated binaries are requested.

Instruction Scope

SKILL.md and the scripts instruct the agent to read local Clash config files (~/.config/clash/config.yaml and ~/Library/Application Support/...), consult environment variables (CLASH_API_UNIX_SOCKET, CLASH_API_URL, CLASH_API_SECRET), call the controller via curl (HTTP or unix socket), and optionally launch the Clash app. These actions are within the stated purpose but are broad (they examine local config and may modify controller state by switching selectors).

Install Mechanism

There is no external download; install is a local zsh script that writes a user LaunchAgent plist under ~/Library/LaunchAgents and uses launchctl. This is a standard macOS user-level installation method and the script does not pull code from remote URLs.

Credentials

The skill does not declare required env vars but will read CLASH_API_UNIX_SOCKET, CLASH_API_URL, and CLASH_API_SECRET if present and will use any 'secret' from local configs as an Authorization header to the controller. While these env/config accesses are necessary for discovering and authenticating to a Clash controller, users should be aware the script will read local config files and environment variables and may send the secret value to the controller API.

Persistence & Privilege

The provided installer creates a user LaunchAgent that will run the bundled Python script at the chosen interval and write logs to ~/Library/Logs. The skill does not set always:true; installation is explicit via the install script, but installing grants the script periodic execution under the user account.

Assessment

This skill appears to do what it says: discover a local Clash controller, test proxies, switch selector groups, and optionally install a macOS LaunchAgent to run periodically. Before installing, review the included scripts (switch_fastest.py and install_launch_agent.sh). Key points to consider: - The script will read local Clash config files (~/.config/clash/config.yaml and Clash Verge's config path) and will read CLASH_API_UNIX_SOCKET, CLASH_API_URL, and CLASH_API_SECRET environment variables if present. If a controller secret exists it will be used in an Authorization header to the controller API. - The script uses curl to communicate with the controller and may change selector state (it performs switches). Use --dry-run first to verify behavior. - The install script writes a LaunchAgent plist to ~/Library/LaunchAgents and runs the script at the chosen interval; inspect the generated plist and logs before enabling. Installation requires explicit user action; do not run the installer unless you trust the code and understand the schedule. - If you are unsure, run the Python script manually with --list-groups and --dry-run, and verify it only talks to your intended controller. If you rely on a secret, rotate it if you suspect exposure. If you want to be extra cautious, run the code in a controlled account or inspect it line-by-line before permitting installation.

This skill gives Codex a reliable workflow for Clash Verge Rev and Mihomo proxy switching on macOS. It is meant for users who want a concrete node selected from a selector group, not just a passive health check.

When To Use It

Use this skill when the user asks to:

• speed test Clash Verge or Mihomo nodes
• switch the currently used Clash selector groups to the fastest node
• diagnose why the Clash controller cannot be reached
• install or remove a timed automatic switch job on macOS

Quick Start

Run the main script:

/usr/bin/python3 ~/.codex/skills/clash-verge-auto-switch/scripts/switch_fastest.py

By default it auto-discovers the current active selector chain from the live Clash controller. To inspect what it found:

/usr/bin/python3 ~/.codex/skills/clash-verge-auto-switch/scripts/switch_fastest.py --list-groups

Target explicit groups:

/usr/bin/python3 ~/.codex/skills/clash-verge-auto-switch/scripts/switch_fastest.py \
  --group 'Proxy' \
  --group 'ChatGPT'

Dry-run without changing selections:

/usr/bin/python3 ~/.codex/skills/clash-verge-auto-switch/scripts/switch_fastest.py --dry-run

Workflow

1. Check whether the Mihomo controller is reachable.
2. If the user did not name target groups, inspect the live /proxies tree and auto-discover groups from the current active selection chain.
3. Expand url-test, fallback, and load-balance groups into leaf proxies, but do not rewrite nested selector groups unless the user explicitly targets them.
4. Test candidate proxies with the controller delay API and switch the selector group to the lowest-latency healthy node.
5. Report the winning node, measured latency, and whether a switch happened.

Group Discovery

• Default mode is --group-scope current, which follows the currently selected chain from the live Clash proxy tree.
• Use --group-scope top-level when you want all top-level selector groups discovered from the current controller session.
• Use --group-scope all when you want every selector group in the current Clash instance.
• Use explicit --group flags when the user wants exact control.

Scheduling

For a true custom-minute schedule on macOS, use the bundled launchd installer instead of Codex automations because Codex recurring schedules only support hourly intervals.

Install:

~/.codex/skills/clash-verge-auto-switch/scripts/install_launch_agent.sh \
  --interval-minutes 30 \
  --group-scope current

Remove:

~/.codex/skills/clash-verge-auto-switch/scripts/uninstall_launch_agent.sh

Notes

• Read runtime-notes.md when you need the generic controller discovery and group-detection rules.
• If the controller is offline, ask the user whether Clash Verge should be opened first or run the script with --launch-if-needed.