dotfiles

A lightweight, recoverable terminal workspace built for remote development

English | 中文

demo-github-complete.mp4

Neovim setup and plugin showcase: Chinese guide →

This repository turns a fresh terminal into a complete development workspace: Zsh provides the shell, tmux keeps sessions alive, Kitty / Ghostty / WezTerm render the terminal, and Neovim handles code, Git, notes, and AI-assisted workflows. The same shortcuts move between terminal panes and editor splits, so the tools feel like one environment instead of several unrelated apps

• dotfiles
  • Guides and documentation
  • Start here: setup
  • Why a terminal-first workflow
    • Development runtimes
  • AI workflow
  • Terminal workflow
  • Stack
  • Neovim
    • Neovide and nvd
    • Plugins
  • Modules

Guides and documentation

The GitHub Wiki contains the detailed Chinese usage guides. Start with the workflow you need instead of reading the repository from top to bottom:

Topic	Guides
Neovim basics	Modes and Movement · Editing and Text Objects · Advanced Commands
Neovim workflow	Shortcut Tips · DAP Debugging · Lua Configuration
Shell and terminal	Zsh · Tmux · Terminal Keymaps · Yazi
Arch Linux	Installation · Windows Dual Boot · Troubleshooting
Desktop environment	Niri · Karabiner Windows Keymap · Linux Clipboard History
Neovim development	Lua for TypeScript Developers · Neovim API · Plugin Paths

Start here: setup

No terminal experience is required. Complete these steps in order and move on only when the current step works

1. Choose a modern terminal

Choose one of the following terminals. They all support this configuration, and only one is required:

• Kitty — the most extensible and recommended choice. Of the three terminals, only Kitty's native mode reproduces the full tmux-like window, pane, and layout handoff workflow, and it supports a smooth cursor
• Ghostty — supports custom shaders for terminal visual effects; its feature set is more direct and its memory usage is slightly higher
• WezTerm — a balanced cross-platform choice for macOS, Linux, and Windows, configured through Lua scripts

The setup scripts support macOS and mainstream Linux distributions. Windows users can install WezTerm, but should deploy the shell configuration inside WSL

2. Check for a Nerd Font

A Nerd Font provides the folder, Git, diagnostic, and interface icons used by the terminal, Neovim, and prompt. Skip this step if a Nerd Font is already installed and selected in the terminal

Maple Mono NF is recommended, or choose another font from Nerd Fonts. After installing it, select that Nerd Font in the terminal settings

On Linux, the upstream Maple Mono NF package avoids downloading the much larger AUR split-package source:

The command below requires curl and unzip. If they are not installed yet, use the browser to install the font or return here after step 4

mkdir -p ~/Downloads/maplemono && \
cd ~/Downloads/maplemono && \
curl -fL --retry 3 \
  -o MapleMono-NF.zip \
  https://github.com/subframe7536/maple-font/releases/latest/download/MapleMono-NF.zip && \
unzip -o MapleMono-NF.zip && \
sudo install -d /usr/local/share/fonts/MapleMono-NF && \
sudo install -m 644 ./*.ttf /usr/local/share/fonts/MapleMono-NF/ && \
sudo fc-cache -f

fc-list | grep 'MapleMono'

3. Clone the repository

Make sure Git is installed. On a fresh system, run the command for the current platform:

# macOS
xcode-select --install

# Arch Linux
sudo pacman -S git

# Debian / Ubuntu
sudo apt install git

# Fedora
sudo dnf install git

Then clone the repository and enter it:

git clone https://github.com/beixiyo/dotfiles.git ~/dotfiles
cd ~/dotfiles

Run all following ./one-click-config/... commands from ~/dotfiles

4. Install command-line dependencies

./one-click-config/setup-deps.sh

The script detects pacman, apt, dnf, zypper, or Homebrew and installs Zsh, Neovim, tmux, mise, Git, ripgrep, fd, and related tools. Administrator access is requested only when system packages actually need to be installed

5. Deploy the configuration

Most users only need the first command:

# Deploy to the current user
./one-click-config/setup-user.sh

# Optional: deploy to specific users
./one-click-config/setup-user.sh alice bob

With no arguments, the script deploys to the current user and asks whether to configure anyone else. Passing alice bob deploys to those users. Linux can create missing users automatically; on macOS, create them in System Settings first

Before replacing existing files, the script asks for confirmation and can back them up under ~/.dotfiles-backup-<timestamp>/. Administrator access is limited to required operations such as creating users, changing login shells, and configuring sudo

6. Install Bun

# This repository only requires Bun
mise use -g bun

Bun runs the Zsh helpers and parts of the Neovim tooling. Run mise install only when the complete toolchain in .config/mise/config.toml is wanted

7. Install tmux plugins

./one-click-config/setup-tmux.sh

Run this as the normal user. It installs TPM, session recovery, status-line, and related tmux plugins

8. Start the workspace

exec zsh
tmux new-session -A

Run nvim to open the editor. Neovim downloads its plugins automatically on the first launch

New to tmux? Read the Tmux keymap guide for windows, panes, copy mode, and workspace recovery

New to Neovim? Follow the Wiki in order: Modes and Movement, Editing and Text Objects, then Advanced Commands

Want configuration files only, without installing dependencies or changing the system? See the manual deployment option in the one-click-config guide

Why a terminal-first workflow

• Lightweight and remote-friendly: SSH is all you need. There is no full desktop stream and no dependency on RDP, Sunshine, or NoMachine; a terminal also remains more usable when the network becomes unstable
• Recoverable workspace: tmux keeps windows, panes, and CLIs alive across SSH disconnects. tmux-resurrect and tmux-continuum periodically save layouts, directories, pane contents, and selected commands so the workspace can be reconstructed after a reboot
• Quick collaboration: multiple SSH clients using the same Unix account can attach to one tmux session and share its input and output. Because focus and input state are shared too, this works best for short, coordinated sessions
• A fully programmable editor: Neovim is one of the freest and most active editors available. Its configuration is a Lua program, and plugins can live locally or be published directly on GitHub without a marketplace; the main trade-off is Lua's less pleasant syntax and developer experience
• A smooth GUI when wanted: Neovide adds fluid animation, scrolling, and a graphical frontend without giving up the Neovim workflow

Development runtimes

mise manages development languages and runtimes in one place. A single configuration can declare Bun, Node.js, Python, Go, Rust, and most other common runtimes; mise install installs the complete configured toolchain. This repository itself only requires Bun:

# This repository only requires Bun
mise use -g bun

Run mise install only when the complete development toolchain is wanted. mise automatically selects configured versions when entering a project, without manual PATH changes. This repository's mise configuration selects Node.js 22, the latest Bun / Go / Python, and stable Rust. System-level tools such as Git, tmux, and compilers still come from Homebrew, pacman, apt, or another system package manager

AI workflow

• tmux keeps long-running AI CLIs alive across SSH disconnects; after a reboot, resurrect / continuum can rebuild the saved layout and restart configured AI CLIs
• <leader>ts sends the current code selection or line, plus diagnostics, to the AI pane next door
• nvd hands the current directory and split layout to Neovide, then restores the original tmux pane on exit
• vv-mcp works with LSP and tmux so code context can move between the editor, the shell, and AI tools

Terminal workflow

The terminal configs support two interchangeable layouts

A pane is one split area. A tab/window groups one or more panes. These shortcuts stay consistent across Neovim, tmux, and the terminal's native mode, so you do not need to learn a separate navigation scheme for each tool

Panes

• Ctrl + Alt + h/j/k/l — move focus left / down / up / right
• Ctrl + Alt + Left/Right/Up/Down — resize the current pane or editor split
• Ctrl + Alt + - / Ctrl + Alt + \ — create a vertical / horizontal split
• Ctrl + Alt + w — close the current pane
• Ctrl + Alt + b — zoom or restore the current pane

Tabs and windows

• Ctrl + Shift + t / Ctrl + Shift + w — create / close a window
• Ctrl + 1 … Ctrl + 8 — switch to window 1 … 8

Kitty, Ghostty, and WezTerm all have tmux and standalone/native keymap files. The shortcuts stay the same; only the backend changes. Enable exactly one mode in the relevant terminal config by keeping its include / config-file line active and commenting out the other. The default Kitty setup is tmux-first; in tmux mode, start or attach with tmux new-session -A

Stack

Layer	Choice	Notes
System	Arch Linux + Niri	My base desktop stack
Shell	Zsh	Close enough to Bash that AI-written shell snippets are less likely to drift
Multiplexer	tmux	Default session layer, lightweight and stable
Terminal	Kitty	Primary terminal; the most extensible, with a complete tmux-like native workflow and smooth cursor support
Terminal	Ghostty	Custom shader support with slightly higher memory usage
Terminal	WezTerm	A balanced cross-platform option configured in Lua, especially useful on Windows
File manager	Yazi	Fast file and directory browsing inside the terminal
Editor	Neovim	Main editor for code, Git work, notes, and workflow

Neovim

Neovim is my main editor for code, Git work, notes, and in-editor automation The vv-* plugins cover navigation, Git, search, refactors, Markdown, and workflow panels

Neovide and nvd

Neovide is Neovim's GPU-accelerated GUI frontend with smooth scrolling, and the smoothest editor in the world

nvd launches Neovide in the current or specified project directory. Inside tmux, it preserves and restores the original window or pane layout; in Kitty native mode, it hands off through Kitty remote control and restores the source window as closely as possible; otherwise, it launches Neovide directly

Plugins

Group	Plugins
Foundation	vv-utils · vv-icons · vv-dashboard · vv-statuscol · vv-indent
Git and files	vv-git · vv-explorer · vv-bufferline · vv-scrollbar · vv-hover
Editing	vv-expand · vv-markdown · vv-replace
Workflow	vv-flow · vv-task-panel · vv-i18n · vv-log-hl · vv-mcp

Each plugin repository has its own bilingual README. The Neovim guide (Chinese) includes a clickable plugin demo gallery

Modules

Module	Path	Docs
Zsh	~/.zsh/	Wiki · README · Dev guide
Neovim	~/.config/nvim/	Wiki · README (Chinese) · Dev guide
Tmux	~/.config/tmux/	Wiki · README
Terminals	~/.config/{kitty,ghostty,wezterm}/	Wiki
Yazi	~/.config/yazi/	Wiki
Niri	~/.config/niri/	Wiki
Karabiner	~/.config/karabiner/	Wiki
Clipboard	~/.config/quickshell/clipboard/	Wiki
Setup scripts	one-click-config/	README

See AGENTS.md for the full architecture map