ClashTui

Language: English | 中文

ClashTui is a terminal user interface (TUI) proxy management tool supporting both Mihomo (Clash.Meta) and sing-box proxy cores. Switch nodes, update subscriptions, manage connections, and control services — all from the terminal.

Features

• Dual Core Support — Compatible with both Mihomo and sing-box; switch anytime in the UI
• Subscription Management — Supports File, URL, and Template (ClashTui template) profile types
• Proxy Switching — Switch by group or by node, with latency testing
• Connection Monitoring — View all active connections in real time; close individual or all connections
• Service Control — Manage core start, stop, and restart via systemd
• Log Viewing — View core logs in real time within the interface
• CLI Mode — Supports profile, mode, service, update subcommands for scripting and automation
• Config Override — Override final config via core_override_config without modifying original subscription files
• Template System — Auto-generate config files using templates + proxy node groups, with variable expansion (recommended for sing-box to avoid configuration version issues)
• Custom Key Bindings — Customize shortcuts for each tab via keymap.yaml
• Custom themes - user-definable via theme.yaml
• which panel - convenient for user operations
• Supports fzf - users can use fzf for selection

Supported Platforms

• [x] Linux
• [x] macOs
• [x] Windows

Installation

Requirements

Linux and macOS: - sudo - fzf

Windows: - nssm

With root access (for TUN mode)

Linux

1. [Optional] Install mihomo and clashtui from your package repository:

sudo pacman -S mihomo sing-box clashtui  # ArchLinux. (Note: the latest clashtui may not be uploaded yet — please build and install it manually)

This step ensures mihomo, sing-box, and clashtui are available in your environment so the install script will skip downloading them. You can also download them manually and run which mihomo sing-box clashtui to verify they are correctly configured.

1. Run the install script:

bash <(curl -fsSL https://raw.githubusercontent.com/JohanChane/clashtui/refs/heads/main/installs/install) --core all

Tip: The install script downloads resources from GitHub. If downloads keep failing, try enabling a proxy before running the script.

1. [Optional] Enable clashtui_mihomo.service / clashtui_singbox.service on boot:

sudo systemctl enable clashtui_mihomo.service
# OR
sudo systemctl enable clashtui_singbox.service

macOS

1. [Optional] Install mihomo and clashtui from Homebrew:

brew install mihomo sing-box clashtui  # Note: the latest clashtui may not be uploaded yet — please build and install it manually

1. Run the install script (same as Linux):

bash <(curl -fsSL https://raw.githubusercontent.com/JohanChane/clashtui/refs/heads/main/installs/install) --core all

1. [Optional] Enable clashtui_mihomo / clashtui_singbox launchd plists on boot:

sudo launchctl load -w /Library/LaunchDaemons/clashtui_mihomo.plist
# OR
sudo launchctl load -w /Library/LaunchDaemons/clashtui_singbox.plist

Windows

1. [Optional] Install mihomo and clashtui from Scoop:

scoop install mihomo sing-box clashtui  # Note: the latest clashtui may not be uploaded yet — please build and install it manually
# Verify
Get-Command mihomo sing-box clashtui

This step ensures mihomo, sing-box, and clashtui are in PATH so the install script will skip downloading them.

1. Run the install script (as Administrator):

# Default install to D:\ClashTui
.\installs\install.ps1 --core all

# Custom directory (no spaces allowed)
.\installs\install.ps1 --core all -InstallDir "D:\MyTools\ClashTui"

# Only install mihomo core
.\installs\install.ps1 --core mihomo

1. Start clashtui, then use CoreSrvCtl to install and start core services:

The install script does NOT register Windows Services. Launch clashtui and use the built-in CoreSrvCtl to manage services. Enable only one core service at boot (do not enable both simultaneously).

Without root access (no TUN)

Linux

bash <(curl -fsSL https://raw.githubusercontent.com/JohanChane/clashtui/refs/heads/main/installs/install) --core all --is-user

Enable on boot:

systemctl --user enable clashtui_mihomo.service
# OR
systemctl --user enable clashtui_singbox.service

macOS

bash <(curl -fsSL https://raw.githubusercontent.com/JohanChane/clashtui/refs/heads/main/installs/install) --core all --is-user

Enable on boot:

launchctl load -w ~/Library/LaunchAgents/clashtui_mihomo.plist
# OR
launchctl load -w ~/Library/LaunchAgents/clashtui_singbox.plist

Documentation

Document	Description
Getting Started	Detailed usage guide: UI operations, CLI, subscription management, config reference, FAQ
Feature Design	Feature design: config structure, subscription management, Template expansion, sing-box merge algorithm
Architecture	Code architecture: module structure, startup flow, TUI event loop, Tab system
Development Conventions	Branch naming, commit format, CHANGELOG conventions

Contributing

Issues and pull requests are welcome. Please read the Development Conventions before contributing.

To get up to speed quickly: 1. Feature Design — understand the feature design 2. Architecture — understand the code structure