CCDB

Warning

CCDB HAS POOR CHINESE LANGUAGE SUPPORT

The translation is incomplete and existing translations are a mess. Texts lacking Chinese corresponding translations are shown in English. Missing texts will be shown in ~/.cache/ccdb/MISSING-TRANSLATIONS.json for Release Candidates.

A lightweight terminal dashboard for Clash/Mihomo, written in C++.

• Overview
• Usage
• Quick Start Examples:
  • Example 1: Switch Proxy in a Proxy Group
  • Example 2: Map the Entire Proxy Chain
  • Example 3: Shell Parsing of get config
  • Example 4: Dump backend debug info
• How to Build

Overview

CCDB targets low-resource environments (for example, embedded devices) and users who want a low-overhead dashboard.

CCDB depends on the following open-source libraries:

• CPP-HTTPLIB v0.54.1 (Embedded)
• GNU Readline 8.3 (Embedded)
• GNU Ncurses 6.6 (Embedded)
• TSL Hopscotch-Hashing Map v2.4.0 (Embedded)
• UTF8-CPP 4.2.0 (Embedded)
• JSON for Modern C++ 3.12.0 <commit/35705d79d878db5ca1a282ec0f8243a80010d24e> (Embedded)
• Perl 5.42.0 (Not embedded, required by OpenSSL)
• OpenSSL 4.0.2 (Embedded)
• GNU Tar 1.35 (Embedded)
• XXD, from VIM <commit/24bf0b60e901b11a37d877cd5947849c18e1a602> (Not embedded, required by the build system)
• libpsl, 0.23.3 (Embedded)
• zlib 1.3.2 (Embedded)
• libpng 1.6.58 (Embedded)
• stb_image - v2.30 - public domain image loader
• CImg 4.0.3 (Embedded)
• libtiv - Original Copyright © 2017-2023, Stefan Haustein, Aaron Liu. Heavily Modified by Anivice (Embedded)
• Abseil - C++ Common Libraries 20260526.0 (Embedded, required by RE2)
• RE2, a regular expression library 2025-11-05 (Embedded)
• C library for the MaxMind DB file format Releases 1.13.3 (Embedded)
• C++ Cache implementation v0.1.1 (Embedded)

Usage

Use help command to see usage details.

Press Tab twice to list candidates in a command, this will list all the available candidates like proxy endpoints or groups, with additional information like latency (if tested) and vector index.

To run a shell command, prefix it with "$ " (dollar sign + space/$[WITH A SPACE]).

NOTE 1:

Double tab will show the helper details of each and every candidate:

NOTE 2:

ccdb/ccdbrc.example

Lines 56 to 57 in c5b70b0

	dashboard = get connections # clash dashboard
	logs = get log # show logs

Comments for the aliases will be noted and printed in the double tab helper as well:

e.g.:

~/.ccdbrc definition:

Helper output:

Example 1: Switch Proxy in a Proxy Group

Step 1

Select the group you want to switch by the following command:

set vgroup [DOUBLE TAB TO LIST GROUPS YOU WANT TO SWITCH]

You should see the vector results similar to this image (groups and endpoints are redacted):

Step 2

Say, I want to change group 44. Use the following command to list the proxy I can set for this group:

set vgroup 44 [DOUBLE TAB TO LIST WHICH PROXY ENDPOINT YOU WANT TO SWITCH TO]

As is shown in the above image, currently selected proxy is marked with a prefix " * " and is highlighted in the candidate selection prompt. The selected endpoint for the above proxy group 44 is 3.

Additional Note

If you tested latency before using get latency, the latency results will be shown in the parentheses, i.e., ([\d]+), as is shown in the following image.

Example 2: Map the Entire Proxy Chain

Example 3: Shell Parsing of get config

CCDB supports shell parsing of its own command outputs. This can be useful for commands like get config to parse JSON on external utilities like jq. For example, you can select dns-hijack from the JSON reply from backend using get config | jq -r '.tun["dns-hijack"]':

Or, you can even pipe a POSIX script into the pipeline:

As you can see, when executing a piped script, you can invoke ccdb with environment variable $CCDB, which is a duplicate of the parent ccdb arguments.

Example 4: Dump backend debug info

   ccdb> get memory pprof heap > /tmp/heap

Here we dumped backend heap file to /tmp/heap.

How to Build

Linux

Requirements

You need

• a complete C++ toolchain of either GCC or Clang that can process at least C++ 17 (GCC >= 13 would be fine)
• cmake and your build system of choice (either Unix Makefile [make] or Ninja [ninja]).
• tar, sed, and grep, the standard POSIX tools that should exist on all Linux systems by default.
• GNU's automake, required by tar package for ccdb

to build CCDB.

All dependencies are embedded inside the source code. No additional installation required.

CMake Settings

• OPENSSL_TARGET: Supported openssl target, if you are cross-compiling you need to specify a platform.
• OPENSSL_LIBP: Depending on the target, openssl can have its lib in .../lib or .../lib64, you can tell CMake this info by setting it to lib or lib64.

Build

On x86_64, you can use the command

  git clone https://github.com/Anivice/ccdb --depth=1 && \
  cd ccdb && mkdir build && cd build && \
  cmake ../src/ -DPERL_MAKE_ADDITIONAL_FLAGS=-j$(nproc) -DOPENSSL_MAKE_ADDITIONAL_FLAGS=-j$(nproc) -DREADLINE_MAKE_ADDITIONAL_FLAGS=-j$(nproc) -DNCURSES_MAKE_ADDITIONAL_FLAGS=-j$(nproc) \
      -DCC_ADDITIONAL_OPTIONS="-O3 -fomit-frame-pointer -ffast-math -fstrict-aliasing -fdata-sections -ffunction-sections -D_FORTIFY_SOURCE=2 -fno-stack-protector -s" \
      -DLD_ADDITIONAL_OPTIONS="-O3 -fomit-frame-pointer -ffast-math -fstrict-aliasing -fdata-sections -ffunction-sections -D_FORTIFY_SOURCE=2 -fno-stack-protector -s" \
      -DOPENSSL_TARGET=linux-x86_64 -DOPENSSL_LIBP=lib64 && \
  make -j$(nproc)

to build locally.

Disclaimer

This is free software; There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. This project is provided "as is." DO NOT use it in production.

YOU HAVE BEEN WARNED

CCDB is GPLv3-licensed to comply with its statically linked GPL dependencies.

See LICENSE for details.