dotfiles

A lightweight, recoverable, terminal-first IDE workspace built for remote development

English | 中文

Build, navigate, manage Git, run tasks, and work with AI entirely in the
terminal, without depending on a desktop IDE.

AI completion follows its tmux window and pane, then clears on focus

Neovim setup and plugin showcase: Chinese guide →

Zsh provides the shell, tmux preserves sessions, and Neovim handles code, Git,
notes, and AI-assisted work. Shared shortcuts connect terminal panes and editor
splits into one workspace

• dotfiles
  • Guides and documentation
  • Start here: setup
  • Why a terminal-first workflow
    • Development runtimes
  • AI workflow
    • AI completion notifications
  • Terminal workflow
    • Why tmux instead of a newer multiplexer?
  • 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:

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

This is not a loose collection of terminal tools. It connects the terminal, multiplexer, editor, file manager, Git, LSP, scripts, and AI into one recoverable IDE workspace. The default workflow does not depend on a full desktop environment; Neovide is an optional GUI entry point when graphical rendering is useful.

• 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
• 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

AI completion notifications

Codex and Claude Code Stop hooks report completion to tmux. An unread task
highlights its background window. Inside that window, a compact message marks
the source pane until it receives focus.

The same hook can send a desktop notification that returns to the source pane.
Terminal BEL and desktop notifications are configured independently:

NOTIFY_SOUND=0       # Terminal BEL
NOTIFY_DESKTOP=1     # Desktop notification
NOTIFY_WHEN_REMOTE=0 # Suppress local desktop alerts for SSH-driven work

The UI is event-driven. Stop hooks set tmux options; focus hooks clear them.
No process or terminal-output polling is used.

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

Why tmux instead of a newer multiplexer?

Newer multiplexers can provide richer built-in layouts, session browsers, or Agent-oriented interfaces. This setup keeps tmux because the multiplexer is infrastructure rather than the main UI:

• Low overhead: the long-lived server and panes remain lightweight, including on remote machines and small development hosts
• Stable behavior: tmux has a mature command model, predictable session semantics, and a large body of operational knowledge
• Available everywhere: it is easy to install on macOS and mainstream Linux distributions and is commonly present on remote servers
• Compact UI: one status line is enough; completion tracks appear only while unread and return their pane row after focus
• Composable automation: hooks, formats, user options, and scripts provide the required Agent state UI without replacing the shell, terminal, or editor
• Terminal independence: the same sessions work through Kitty, Ghostty, WezTerm, a plain SSH client, or multiple attached clients

Stack

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

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

Modules

See AGENTS.md for the full architecture map