Skip to content

Setup

Complete configuration guide for the Sao development environment.

System: Ubuntu 24.04.3 LTS (Noble) | User: sao

Table of Contents

  1. System Packages
  2. Programming Languages and Tools
  3. Neovim Configuration
  4. tmux Configuration
  5. Git Configuration
  6. Shell Configuration
  7. Custom Keybindings
  8. File Locations
  9. Quick Start

System Packages

Core Development Tools

  • build-essential (12.10ubuntu1): C/C++ compiler and build tools
  • git (2.43.0-1ubuntu7.3): Version control
  • curl (8.5.0-2ubuntu10.6): Data transfer tool (HTTP/HTTPS)
  • wget (1.21.4): Data transfer tool (HTTP/HTTPS/FTP)
  • tree (2.1.1): Directory lister
  • tmux (3.4): Terminal multiplexer for session management
  • ripgrep (14.1.0): Fast recursive search tool (required for Telescope live_grep)
  • fzf: Command-line fuzzy finder

Programming Languages and Tools

Go

  • Version: go1.25.3 linux/amd64
  • Installation Path: /usr/local/go/bin/go
  • Added to PATH: /usr/local/go/bin

NVM

  • Installation: wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash

Node.js (via NVM)

  • Version: v18.20.8
  • Installation: nvm install 18 && nvm use 18
  • NVM Directory: ~/.nvm
  • Node Path: ~/.nvm/versions/node/v18.20.8/bin/node

Claude CLI

  • Path: ~/.nvm/versions/node/v18.20.8/bin/claude
  • Installation: npm install -g @anthropic-ai/claude-code

Node.js Requirement

Claude CLI requires Node.js v18 or higher. Install via NVM before installing Claude CLI.

Docker

  • Docker Engine: 28.5.1
  • Docker Compose: v2.40.0 (integrated plugin)
  • User permissions: sao is in the docker group (can run without sudo)

Docker Compose Syntax

Use docker compose (with space) instead of the legacy docker-compose (with hyphen). The compose plugin is integrated into Docker Engine.

Neovim

  • Version: NVIM v0.11.4 (Release)
  • Installation Path: /opt/nvim-linux-x86_64/bin
  • Config Location: ~/.config/nvim/
  • Based on: kickstart.nvim (forked to github.com/Mike-Bros/kickstart.nvim)
  • Added to PATH: /opt/nvim-linux-x86_64/bin

Neovim Configuration

Plugin Manager

  • lazy.nvim: Modern plugin manager with lazy loading

Installed Plugins

Core Capabilities (from kickstart.nvim)

The kickstart.nvim base provides:

  • LSP & Language Support: Auto-configured language servers with Mason installer
  • Code Completion: Smart completions with snippets and documentation
  • Fuzzy Finding: Telescope for files, buffers, grep, and LSP symbols
  • Syntax Highlighting: Treesitter for accurate code parsing
  • Git Integration: Inline blame, diff views, and hunk operations
  • UI Enhancements: Keybinding hints (which-key), progress notifications, Catppuccin colorscheme
  • Editor Features: Auto-indent detection, surround operations, statusline, relative line numbers

Telescope Dependencies

Telescope's live_grep feature requires ripgrep to be installed on the system. It's included in the base tools installation above.

Custom Plugins (in ~/.config/nvim/lua/custom/plugins/)

  • catppuccin.nvim: Modern colorscheme with soothing pastel theme (replaces tokyonight)
  • claudecode.nvim: AI coding assistant
  • conform.nvim: Auto-format on save (goimports→gofumpt for Go, biome for TS/React, stylua for Lua)
  • vim-be-good: Vim motion practice game

Claude Code Quick Reference

  • <space>ac - Toggle Claude Code terminal
  • Ctrl+w - Exit terminal mode and start window command
  • See Keybindings for complete reference

Language Servers & Tools (via Mason)

Installed in ~/.local/share/nvim/mason/bin/:

Go

  • gopls: Go language server
  • gofumpt: Go formatter
  • goimports: Go import manager

TypeScript/JavaScript

  • typescript-language-server (ts_ls)
  • biome: Fast JS/TS/React formatter and linter

Lua

  • lua-language-server (lua_ls)
  • stylua: Lua formatter

LSP Configuration

gopls (Go Language Server)

settings = {
  gopls = {
    gofumpt = true,           -- Enable gofumpt formatting
    staticcheck = true,       -- Enable static analysis
    completeUnimported = true, -- Suggest unimported packages
    usePlaceholders = true,   -- Function parameter placeholders
    analyses = {
      unusedparams = true,
      shadow = true,
    },
  },
}

Formatting Configuration

Document formatting is disabled in gopls to avoid conflicts with conform.nvim

Formatter Configuration (conform.nvim)

Auto-Format on Save

All configured file types auto-format on save with a 5-second timeout.

Formatter chains (tries first formatter, falls back to second):

  • Go: goimports → gofumpt (import management + strict formatting)
  • JavaScript/TypeScript/React: biome → prettier
  • JSON: biome → prettier
  • Lua: stylua

Editor Appearance & Behavior

Color Scheme

  • Catppuccin: Modern, soothing pastel theme
  • Yellow line numbers: Custom highlight for improved visibility
  • Location: ~/.config/nvim/lua/custom/plugins/catppuccin.lua

Custom Vim Options (in init.lua)

Line Numbers & Navigation
  • Relative line numbers (relativenumber): Shows relative distances from cursor for efficient vim motions (e.g., 5j to jump down 5 lines)
  • Custom line number color: Yellow highlighting for better visibility with Catppuccin theme
Indentation & Formatting
  • 4-space indentation: shiftwidth, tabstop, and softtabstop all set to 4
  • Spaces over tabs (expandtab): Insert spaces when pressing Tab
  • Smart indenting (smartindent): Automatically indent new lines based on syntax
Display & Scrolling
  • No line wrapping (wrap = false): Long lines scroll horizontally
  • Horizontal scroll offset (sidescrolloff = 10): Keep 10 columns visible left/right of cursor when scrolling

Auto-Installation Note

Mason Auto-Installation

All language tooling (LSP servers, formatters, linters) listed above are automatically installed by Mason when you first open Neovim with this config. The host machine only needs:

  • Go: Base language runtime
  • Node.js: Base JavaScript runtime

Mason handles installing and managing:

  • Language servers (gopls, ts_ls, lua_ls)
  • Formatters (gofumpt, goimports, biome, stylua)
  • All other development tools

No manual installation of language tooling required!

tmux Configuration

  • Version: tmux 3.4
  • Config Location: ~/.tmux.conf
  • Prefix Key: Ctrl+a (instead of default Ctrl+b)
  • Theme: Catppuccin Mocha
  • Plugin Manager: TPM (Tmux Plugin Manager)

Core Features

Terminal & Display:

  • True color support: RGB color enabled for Neovim and terminal applications
  • Zero escape time: Eliminates delay when switching Neovim modes
  • Mouse support: Click to select panes, windows, and scroll
  • Large scrollback: 10,000 line history buffer

Session Management:

  • Persistent sessions: Auto-saves every 1 minute, survives system reboots
  • Auto-restore: Sessions automatically restored on tmux start
  • Auto-renumber windows: Windows renumber when closed

Installed Plugins

TPM is installed at ~/.tmux/plugins/tpm and manages the following plugins:

  • tmux-sensible: Sensible default settings
  • tmux-yank: System clipboard integration
  • vim-tmux-navigator: Seamless Vim/tmux pane navigation (works with Neovim)
  • catppuccin/tmux: Catppuccin Mocha theme with custom status bar
  • tmux-resurrect: Save and restore sessions manually
  • tmux-continuum: Auto-save sessions every 1 minute

Plugin keybindings:

  • Ctrl+a I (capital I) - Install new plugins
  • Ctrl+a U (capital U) - Update plugins
  • Ctrl+a Alt+u - Uninstall plugins not in config

Git Status Integration

gitmux displays Git repository information in the tmux status bar:

  • Location: ~/go/bin/gitmux (development version)
  • Config: ~/.gitmux.conf (Catppuccin color scheme)
  • Shows: Branch name, commits ahead/behind, staged/modified/untracked files

Status bar layout:

  • Left: Session name
  • Right: Current directory + Git status (when in git repo)
  • Window indicator: Shows (+) when window is zoomed/maximized

Windows Terminal Compatibility

The default tmux prefix (Ctrl+b) conflicts with Windows Terminal's tab switching when connecting via SSH. Using Ctrl+a avoids this conflict and provides a more ergonomic prefix key.

Configuration: See ~/.tmux.conf for full configuration details. For keybindings, see tmux Keybindings.

Git Configuration

Global Settings

user.name=Mike Bros
user.email=9326825+Mike-Bros@users.noreply.github.com

Authentication: SSH Keys

This system uses SSH key authentication for all Git operations with GitHub. SSH provides secure, password-free authentication without requiring credential storage.

Current Configuration:

  • Private key: ~/.ssh/id_ed25519
  • Public key: ~/.ssh/id_ed25519.pub (added to GitHub account)
  • Known hosts: GitHub added to ~/.ssh/known_hosts
  • Repository URLs: Use SSH format (git@github.com:user/repo.git)

Setup Steps (for fresh installations):

  1. Generate ED25519 SSH key pair: 

    ssh-keygen -t ed25519 -C "9326825+Mike-Bros@users.noreply.github.com" -f ~/.ssh/id_ed25519 -N ""

  2. Copy public key to clipboard: 

    cat ~/.ssh/id_ed25519.pub
    Copy the entire output.

  3. Add public key to GitHub:

  4. Visit GitHub Settings > SSH and GPG keys
  5. Click "New SSH key"

  6. Paste the public key and save

  7. Add GitHub to known hosts (prevents SSH fingerprint prompt): 

    ssh-keyscan github.com >> ~/.ssh/known_hosts

  8. Verify authentication: 

    ssh -T git@github.com
    Expected output: Hi Mike-Bros! You've successfully authenticated, but GitHub does not provide shell access.

SSH Authentication Configured

This system is configured with SSH key authentication. No credential storage or personal access tokens are needed. All Git operations use the SSH key at ~/.ssh/id_ed25519.

SSH vs HTTPS URLs

Always clone repositories using SSH URLs (git@github.com:user/repo.git) instead of HTTPS URLs (https://github.com/user/repo.git). SSH authentication is more secure and doesn't require managing tokens or credential storage.

Shell Configuration

~/.bashrc Additions

# Go
export PATH=$PATH:/usr/local/go/bin

# NVM (Node Version Manager)
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

# Neovim
export PATH="$PATH:/opt/nvim-linux-x86_64/bin"
export EDITOR=nvim
export VISUAL=nvim

# Aliases
alias vim=nvim
alias vi=nvim

Custom Keybindings

For a complete reference of all custom keybindings, see Keybindings.

File Locations

Configuration Files

  • Neovim config: ~/.config/nvim/init.lua
  • Custom plugins: ~/.config/nvim/lua/custom/plugins/init.lua
  • tmux config: ~/.tmux.conf
  • gitmux config: ~/.gitmux.conf
  • Bashrc: ~/.bashrc
  • Git config: ~/.gitconfig
  • SSH keys: ~/.ssh/id_ed25519 (private) and ~/.ssh/id_ed25519.pub (public)
  • NVM: ~/.nvm/

Data Directories

  • Neovim plugins: ~/.local/share/nvim/lazy/
  • Mason tools: ~/.local/share/nvim/mason/bin/
  • tmux plugins: ~/.tmux/plugins/
  • Go binaries: ~/go/bin/ (includes gitmux)
  • Node modules: ~/.nvm/versions/node/v18.20.8/

Quick Start After Fresh Install

Prerequisites

These instructions assume a fresh Ubuntu 24.04 LTS installation. Adjust commands if using a different version or distribution.

To replicate this setup on a new Ubuntu installation:

  1. Install base tools: 

    sudo apt update
sudo apt install build-essential git curl wget tree tmux ripgrep fzf

  2. Install Go: 

    cd ~/Downloads
wget https://dl.google.com/go/go1.25.3.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.25.3.linux-amd64.tar.gz
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
source ~/.bashrc

  3. Install NVM: 

    wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
# Reload shell or run: source ~/.bashrc

  4. Install Node.js via NVM: 

    nvm install 18 && nvm use 18

  5. Install Neovim: 

    cd ~/Downloads
wget https://github.com/neovim/neovim/releases/latest/download/nvim-linux-x86_64.tar.gz
sudo tar -C /opt -xzf nvim-linux-x86_64.tar.gz
echo 'export PATH="$PATH:/opt/nvim-linux-x86_64/bin"' >> ~/.bashrc
echo 'export EDITOR=nvim' >> ~/.bashrc
echo 'export VISUAL=nvim' >> ~/.bashrc
echo 'alias vim=nvim' >> ~/.bashrc
echo 'alias vi=nvim' >> ~/.bashrc
source ~/.bashrc

  6. Install tmux and TPM: 

    sudo apt install tmux

# Download the full tmux config
curl -o ~/.tmux.conf https://raw.githubusercontent.com/Mike-Bros/kickstart.nvim/main/.tmux.conf

# Install TPM (Tmux Plugin Manager)
git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm

# Install gitmux for git status in status bar
go install github.com/arl/gitmux@latest

# Download gitmux config
curl -o ~/.gitmux.conf https://raw.githubusercontent.com/Mike-Bros/kickstart.nvim/main/.gitmux.conf

# Start tmux and install plugins
tmux
# Press Ctrl+a then Shift+I to install plugins

  7. Install Claude CLI: 

    npm install -g @anthropic-ai/claude-code

  8. Clone kickstart.nvim config: 

    git clone https://github.com/Mike-Bros/kickstart.nvim.git ~/.config/nvim

  9. Open Neovim (auto-installs plugins, LSP servers, linters, and formatters): 

    nvim

  10. Configure Git and SSH: 

    # Basic Git configuration
git config --global user.name "Mike Bros"
git config --global user.email "9326825+Mike-Bros@users.noreply.github.com"

# Generate SSH key for GitHub
ssh-keygen -t ed25519 -C "9326825+Mike-Bros@users.noreply.github.com" -f ~/.ssh/id_ed25519 -N ""

# Display public key to copy
cat ~/.ssh/id_ed25519.pub
# Copy the output and add it to GitHub Settings > SSH and GPG keys
# Visit: https://github.com/settings/keys

# Add GitHub to known hosts (prevents SSH fingerprint prompt)
ssh-keyscan github.com >> ~/.ssh/known_hosts

# Test SSH authentication
ssh -T git@github.com
# Expected: "Hi Mike-Bros! You've successfully authenticated..."