tokui

KO | EN

gitlite — search

#ai-agents #typescript #ai #python #mcp #claude-code #cli #ai-agent #mcp-server #rust #model-context-protocol #openclaw

★ 49 Open GitHub ↗

An interactive TUI for visualizing code statistics from tokei.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 📊 Tokui

[![Build](https://github.com/zdyxry/tokui/actions/workflows/build.yml/badge.svg)](https://github.com/zdyxry/tokui/actions/workflows/build.yml)
[![Go Report Card](https://goreportcard.com/badge/github.com/zdyxry/tokui)](https://goreportcard.com/report/github.com/zdyxry/tokui)

**Tokui** is a high-performance, cross-platform command-line tool for visualizing and exploring code statistics. It integrates with the powerful code statistics engine [tokei](https://github.com/XAMPPRocky/tokei) by default, and also supports [scc](https://github.com/boyter/scc) as an optional backend, to present code line count and complexity metrics through a responsive, keyboard-driven Terminal User Interface (TUI), helping you quickly analyze code composition and understand project structure.

> **Project Origin**
>
> This project is a fork of the excellent disk space analyzer [noxdir](https://github.com/crumbyte/noxdir), heavily modified and refactored by a **Large Language Model (LLM)** to transform it from a disk analyzer into a code statistics visualizer.

## 📸 Previews

Screenshots below show `tokui` analyzing the [Prometheus](https://github.com/prometheus/prometheus) codebase.

| Default View | Language Distribution (`Ctrl+w`) |
|:---:|:---:|
| ![Default View](https://raw.githubusercontent.com/zdyxry/tokui/main/assets/demo1.png) | ![Language Distribution](https://raw.githubusercontent.com/zdyxry/tokui/main/assets/demo2.png) |
| **Tree Mode** | **Treemap Mode** |
| ![Tree Mode](https://raw.githubusercontent.com/zdyxry/tokui/main/assets/demo3.png) | ![Treemap Mode](https://raw.githubusercontent.com/zdyxry/tokui/main/assets/demo4.png) |

## ✨ Features

- **Interactive Terminal UI**: Navigate, filter, and explore your project with an intuitive keyboard-driven interface.
- **Multiple Stats Providers**: Use `tokei` (default) for line counts, or switch to `scc` for complexity metrics.
- **Deep Tokei Integration**: Leverages `tokei` for accurate lines of code, comments, blanks, and total lines, categorized by language.
- **Git Integration**: Analyze code churn with `tokui diff`, browse historical snapshots with `tokui ref`, or compare statistics between two refs with `tokui compare`. File previews show side-by-side diffs in git modes.
- **File Preview**: Press `Enter` on any file to instantly preview its contents in a scrollable overlay window. In git modes, previews show the file's diff with syntax-colored additions and deletions.
- **Language Filtering**: Filter by a single language (`Tab`), or select multiple languages via the multi-select overlay (`Ctrl+L`).
- **Visual Charts**: Toggle a language distribution pie chart with `Ctrl+w`.
- **Column Sorting**: Sort the directory listing by any column (`s`) and toggle ascending/descending order (`S`).
- **Tree Mode**: Toggle tree mode (`t`) to expand and collapse directories inline.
- **Treemap Mode**: Toggle treemap mode (`m`) to visualize directory composition with proportional colored blocks.
- **Mouse Support**: Scroll, click, and double-click to navigate rows and overlays.
- **Zero-Dependency Release**: Pre-built binaries bundle `tokei` internally—no separate installation required.
- **Privacy-Focused**: Runs entirely locally. No telemetry or data uploads, ever.

## ⚠️ Prerequisites

**Pre-built release binaries have `tokei` embedded**—no manual installation is needed.

If you are building from source or want to use your own `tokei` installation, ensure `tokei` is available in your `PATH`. Tokui will automatically prefer the system-installed version if present.

- **Install `tokei`** (optional): [https://github.com/XAMPPRocky/tokei#installation](https://github.com/XAMPPRocky/tokei#installation)

> **Git modes** (`diff`, `show`, `compare`, `ref`) require `git` to be installed and available in your `PATH`, and must be run inside a git repository.

## 📦 Installation

### Pre-compiled Binaries

Download the latest release from the [Releases](https://github.com/zdyxry/tokui/releases) page. Unzip and run—no extra installation required.

### Using `go install` (Go 1.25+)

```bash
go install github.com/zdyxry/tokui@latest
```

This downloads, compiles, and installs the latest `tokui` binary into your `$GOPATH/bin` (or `$GOBIN`). The `tokei` binary is embedded at compile time, so no separate `tokei` installation is required.

### Build from Source (Go 1.25+)

```bash
# Clone the repository
git clone https://github.com/zdyxry/tokui.git
cd tokui

# Download tokei binaries for embedding (optional but recommended)
make fetch-tokei-binaries

# Build
make build

# Run
./bin/tokui
```

> **Note**: `make fetch-tokei-binaries` downloads platform-specific `tokei` binaries that will be embedded into the final executable. If skipped, the build will still succeed using placeholder files; the resulting binary will fallback to a system-installed `tokei` at runtime.

## 🛠️ Usage

Tokui supports two modes of operation:

### 1. Direct Mode (Recommended)

Tokui automatically invokes the selected provider (`tokei` by default) to analyze the specified directory.

```bash
# Analyze the current directory with tokei
tokui

# Analyze with scc for complexity metrics
tokui --provider scc

# Or set the provider via environment variable
TOKUI_PROVIDER=scc tokui

# Analyze a specific directory
tokui /path/to/your/project
```

### 2. Pipe Mode

If you have `tokei` installed separately, run it manually with custom arguments and pipe its JSON output to `tokui`. This is useful for advanced filtering (e.g., `--exclude`). `tokui` also accepts `scc --by-file -f json` output and auto-detects the format.

```bash
# Analyze the current directory with tokei
tokei -o json . | tokui

# Analyze a specific directory and exclude node_modules
tokei -o json --exclude node_modules . | tokui

# Or use scc for complexity metrics
scc --by-file -f json . | tokui
```

### 3. Git Modes

Run any of the git subcommands inside a git repository to analyze changes, compare snapshots, or browse historical versions.

```bash
# Diff mode: code churn for a commit range, branch, or unstaged changes
tokui diff                    # unstaged changes (like "git diff")
tokui diff --staged           # staged changes (like "git diff --cached")
tokui diff main...HEAD        # churn of your branch vs main
tokui diff HEAD~3             # churn of the last 3 commits

# Show mode: churn of a single commit (like "git show")
tokui show HEAD               # churn of the latest commit
tokui show a1b2c3d            # churn of a specific commit

# Compare mode: net statistics change between two refs
tokui compare v1.0..v2.0      # ΔCode, ΔComplexity between two tags
tokui compare main..HEAD      # net change on your branch

# Ref mode: browse a historical snapshot (like the normal full view)
tokui ref v1.0                # full code statistics of a tag

# Scope to a subdirectory
tokui diff main...HEAD src/   # only changes under src/
```

In **Diff mode**, the table shows code churn columns (`+`/`-`/`Δ`/`%`) alongside the current (S2) code statistics. Press `a` to toggle between "changed files only" and the full snapshot (unchanged files appear dimmed). Press `Enter` on a file to see its diff with side-by-side or unified layout.

In **Compare mode**, the table shows `Code (S1 → S2)`, `ΔCode`, and `ΔCmplx` columns, giving you the net growth or shrinkage between two refs.

These modes cannot be combined with pipe mode.

### CLI Arguments

```
Usage:
  tokui [directory] [flags]
  tokui diff [range] [directory] [flags]
  tokui show [commit] [directory] [flags]
  tokui compare <a..b> [directory] [flags]
  tokui ref <ref> [directory] [flags]

Flags:
  -r, --root string    Specify the root directory to analyze. Defaults to the current directory ".".
      --provider       Stats provider: tokei|scc. Defaults to tokei; can be set via TOKUI_PROVIDER env var.
  -t, --tree           Start in tree mode. Directories are expandable inline instead of navigable.
      --treemap        Start in treemap mode. Show proportional blocks instead of a table.
  -h, --help           Show help information

Diff flags:
      --staged         Show staged changes against HEAD (like "git diff --cached").
```

## ⌨️ Keybindings

### Main View

| Key                 | Action                                                              |
| ------------------- | ------------------------------------------------------------------- |
| `↑` / `k`           | Move cursor up                                                      |
| `↓` / `j`           | Move cursor down                                                    |
| `g` / `home`        | Go to top                                                           |
| `G` / `end`         | Go to bottom                                                        |
| `Enter`             | Enter directory / Expand-Collapse directory / Preview file          |
| `e`                 | Open file in editor                                                 |
| `Backspace`         | Go back to the parent directory                                     |
| `t`                 | Toggle navigation mode / tree mode                                  |
| `m`                 | Toggle treemap mode                                                 |
| `Tab`               | Cycle through language filters                                      |
| `Ctrl`+`L`          | Open multi-language selection overlay                               |
| `/`                 | Activate file name filter (press `Esc` to exit filter mode)         |
| `Ctrl`+`P`          | Open global fuzzy search (press `Enter` to jump, `Esc` to close)    |
| `s`                 | Cycle sort column (Name → Languages → Code → Comments → Blanks → Total → % of Parent) |
| `S`                 | Toggle ascending / descending order for the current sort column     |
| `a`                 | (Diff/Compare modes) Toggle changed-only / all files                |
| `Ctrl`+`w`          | Show/hide language distribution pie chart                           |
| `?`                 | Show/hide full help                                                 |
| `q` / `Ctrl`+`c`    | Quit the application / Close file preview                           |

### File Preview Mode

| Key                 | Action                                                              |
| ------------------- | ------------------------------------------------------------------- |
| `↑` / `k`           | Scroll up                                                           |
| `↓` / `j`           | Scroll down                                                         |
| `PgUp`              | Page up                                                             |
| `PgDn`              | Page down                                                           |
| `q` / `Esc`         | Close file preview and return to directory view                     |

### Mouse Support

Tokui also supports basic mouse interaction in terminals that report mouse events:

| Action              | Effect                                                              |
| ------------------- | ------------------------------------------------------------------- |
| Scroll wheel        | Move cursor / scroll previews and language lists                    |
| Left click          | Select a row or an item in the language selection overlay           |
| Left click header   | Sort by the clicked column (click again to toggle ascending/descending) |
| Double left click   | Enter directory, expand/collapse directory, or open file preview    |
| Double left click `..` | Go back to the parent directory                                    |
| Click outside overlay | Close the file preview, language selection, or chart overlay       |

## 🤝 Contributing

Pull Requests are welcome! If you'd like to add new features or report bugs, please open an issue first to discuss your ideas.

## 📝 License

Tokui is licensed under the [MIT License](./LICENSE).

This project bundles a copy of [tokei](https://github.com/XAMPPRocky/tokei) (MIT OR Apache-2.0) for zero-dependency operation. See [THIRD-PARTY-LICENSES](./THIRD-PARTY-LICENSES) for details.

tokui

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README