Quickstart

Welcome to Your New Environment

You’ve successfully installed Gentleman.Dots! This guide will help you start using your new development setup effectively. We’ll cover the essential workflows and shortcuts to make you productive immediately.

This guide assumes you’ve completed the installation. If not, go back and set up your environment first.

Launch Your Setup

Open your terminal emulator

Launch the terminal you installed (Alacritty, WezTerm, Kitty, or Ghostty).You should see:

Starship prompt with the Gentleman theme
Your current directory path
Git branch info (if in a repo)

The prompt shows language versions (Node.js, Rust, Go, etc.) when you’re in a project directory.

Your shell starts automatically

The shell you chose during installation (Fish, Zsh, or Nushell) should be your default.Verify:

echo $SHELL
# Should show: /usr/local/bin/fish, /bin/zsh, or /usr/local/bin/nu

Window manager may auto-start

If you didn’t choose “none” for window manager, Tmux or Zellij may start automatically.

Tmux started automatically?

You’ll see a status bar at the bottom with:

Session name
Window list
System info (CPU, memory, date/time)

The prefix key is Ctrl+a (not the default Ctrl+b).

Zellij started automatically?

You’ll see a UI with tabs at the top and a status bar showing:

Tab names
Mode indicator
Keybinding hints

Don't want auto-start?

To disable auto-start:

# Edit ~/.config/fish/config.fish
# Comment out or remove the tmux/zellij launch line

Essential Keybindings

Window Manager Shortcuts

Tmux
Zellij

The prefix key is Ctrl+a (customized from the default Ctrl+b).

Action	Keybinding
Prefix	`Ctrl+a`
New window	`Prefix + c`
Next window	`Prefix + n`
Previous window	`Prefix + p`
Split horizontal	`Prefix + \|`
Split vertical	`Prefix + -`
Navigate panes	`Prefix + arrow keys`
Resize pane	`Prefix + Ctrl+arrow`
Detach session	`Prefix + d`
List sessions	`Prefix + s`
Install plugins	`Prefix + I` (capital i)
Reload config	`Prefix + r`

Seamless Vim/Neovim navigation: Use Ctrl+h/j/k/l to move between tmux panes and Neovim splits without thinking about boundaries!

Common workflows:

# Create a new session
tmux new -s myproject

# Attach to existing session
tmux attach -t myproject

# List all sessions
tmux ls

# Kill a session
tmux kill-session -t myproject

Zellij uses modes similar to Vim:

Mode	Enter	Exit
Normal	`Esc` or `Ctrl+g`	-
Pane	`Ctrl+p`	`Esc`
Tab	`Ctrl+t`	`Esc`
Resize	`Ctrl+n`	`Esc`
Move	`Ctrl+h`	`Esc`
Scroll	`Ctrl+s`	`Esc`
Session	`Ctrl+o`	`Esc`

Common actions:

Action	Keybinding
New pane (right)	`Ctrl+p` then `n`
New pane (down)	`Ctrl+p` then `d`
New tab	`Ctrl+t` then `n`
Navigate panes	`Alt+arrow keys`
Rename tab	`Ctrl+t` then `r`
Close pane	`Ctrl+p` then `x`
Detach	`Ctrl+o` then `d`

Zellij shows available keybindings at the bottom of the screen based on your current mode!

Shell Shortcuts

These work in all shells (Fish, Zsh, Nushell):

Tool	Keybinding	Description
fzf	`Ctrl+r`	Search command history
fzf	`Ctrl+t`	Find files in current directory
fzf	`Alt+c`	Change directory interactively
Atuin	`Ctrl+r`	Enhanced history search (if configured)

Modern CLI tools (already installed):

# bat - better cat with syntax highlighting
bat file.js
bat -l python script.py  # force language

# eza - better ls with icons and colors  
eza
eza -l        # long format
eza -la       # include hidden
eza -T        # tree view
eza -l --git  # show git status

# rg (ripgrep) - blazing fast search
rg "pattern" 
rg -i "case insensitive"
rg -t js "only in .js files"
rg -C 3 "with 3 lines context"

# fd - better find
fd pattern
fd -e js      # only .js files
fd -H         # include hidden
fd -t d       # only directories

# zoxide - smart cd
z project     # jump to directory matching "project"
z -l          # list matches

# lazygit - beautiful git TUI
lazygit

Launch Neovim

Start Neovim

nvim
# Or open a file:
nvim myfile.js

On first launch, Lazy.nvim will install all plugins automatically. This takes 1-2 minutes.

You may see some error messages on the very first launch - this is normal. Just press Enter to dismiss them, wait for plugins to finish installing, then quit (:q) and reopen Neovim.

Verify plugins loaded

Once inside Neovim:

:Lazy

This opens the Lazy.nvim plugin manager. You should see all plugins with green checkmarks.Press q to close the Lazy window.

Try basic navigation

Neovim uses Vim keybindings:

Key	Action
`h/j/k/l`	Left/Down/Up/Right
`i`	Enter insert mode
`Esc`	Return to normal mode
`:w`	Save file
`:q`	Quit
`:wq`	Save and quit

If you’re new to Vim, run :Tutor inside Neovim for an interactive tutorial, or try the vim-be-good plugin (included) to practice: :VimBeGood

Essential Neovim Shortcuts

The Gentleman.Dots Neovim config uses Space as the leader key.

File Navigation

Keybinding	Action
`Space + Space`	Find files (fzf-lua)
`Space + f`	File explorer (Oil.nvim)
`Space + /`	Search in files (grep)
`Space + b`	List buffers
`Space + r`	Recent files
`Ctrl+h/j/k/l`	Navigate between splits

Oil.nvim tips:

Edit file paths like text, then press Enter to apply changes
- to go up a directory
g? to see all keybindings

LSP & Code Intelligence

Keybinding	Action
`gd`	Go to definition
`gr`	Show references
`K`	Hover documentation
`Space + ca`	Code actions
`Space + rn`	Rename symbol
`[d` / `]d`	Previous/next diagnostic
`Space + e`	Show diagnostics

Auto-completion:

Start typing, suggestions appear automatically
Tab / Shift+Tab to navigate suggestions
Enter to accept
Powered by blink.cmp

AI Assistant (OpenCode)

The Gentleman agent is enabled by default in OpenCode.nvim.

Keybinding	Action
`Space + a`	Open AI assistant
`Space + ac`	AI chat
`Space + ae`	Explain code
`Space + ar`	Refactor selection

Or use OpenCode CLI:

# From terminal
opencode

# Select Gentleman agent
/agent
# Choose: gentleman

# Chat with the agent
> How do I implement authentication in Express?

The Gentleman agent is designed to challenge your assumptions and propose alternatives. Don’t be surprised if it asks you to verify something or suggests a different approach!

Git Integration (LazyGit)

Keybinding	Action
`Space + gg`	Open LazyGit

Inside LazyGit:

Space to stage/unstage
c to commit
P to push
p to pull
? for help
q to quit

Window & Tab Management

Keybinding	Action
`Space + w` + `v`	Split vertically
`Space + w` + `s`	Split horizontally
`Space + w` + `c`	Close window
`Space + w` + `o`	Close other windows
`Ctrl+w =`	Equal window sizes
`Space + tab + n`	New tab
`Space + tab + c`	Close tab
`gt` / `gT`	Next/previous tab

Search & Replace

Keybinding	Action
`/pattern`	Search forward
`?pattern`	Search backward
`n` / `N`	Next/previous match
`*`	Search word under cursor
`:%s/old/new/g`	Replace in file
`:%s/old/new/gc`	Replace with confirmation

Which-Key Helper

Press Space and wait 1 second - which-key will show all available keybindings!This is invaluable for discovering features. Try:

Space (wait) - see all leader key mappings
Space + g (wait) - see all git commands
Space + c (wait) - see all code commands

Switch AI Plugins

By default, OpenCode.nvim is enabled with the Gentleman agent. To switch:

Open plugin configuration

nvim ~/.config/nvim/lua/plugins/disabled.lua

Toggle plugin states

Find the plugins and change their enabled values:

-- Example: Switch from OpenCode to Claude Code
{
  "NickvanDyke/opencode.nvim",
  enabled = false,  -- Disable OpenCode
},
{
  "coder/claudecode.nvim",
  enabled = true,   -- Enable Claude Code
},

Only enable ONE AI plugin at a time to avoid keybinding conflicts!

Available AI plugins:

opencode.nvim - OpenCode with Gentleman agent (default)
avante.nvim - AI-powered coding assistant
copilot-chat.nvim - GitHub Copilot chat
codecompanion.nvim - Multi-provider AI support
claudecode.nvim - Claude AI integration
gemini.nvim - Google Gemini integration

Restart Neovim

:q

Then reopen Neovim. Lazy.nvim will install the newly enabled plugin automatically.

Configure OpenCode Model

Open OpenCode config

nvim ~/.config/opencode/opencode.json

Change the model

Edit the model field in the Gentleman agent:

{
  "agent": {
    "gentleman": {
      "model": "anthropic/claude-sonnet-4-20250514",
      ...
    }
  }
}

Popular models:

anthropic/claude-sonnet-4-20250514 (recommended)
anthropic/claude-haiku-4-20250514 (faster, cheaper)
openai/gpt-4o
openai/gpt-4o-mini
google/gemini-2.0-flash
google/gemini-2.5-pro-preview-06-05

Test the new model

opencode
/agent
# Select: gentleman

> Test message

Customize Your Theme

The Gentleman theme is applied across all tools. To customize:

Starship Prompt
Neovim Colorscheme
Terminal Emulator
OpenCode Theme

nvim ~/.config/starship.toml

The Gentleman color palette is defined:

[palettes.gentleman]
text = "#F3F6F9"
red = "#CB7C94"
green = "#B7CC85"
yellow = "#FFE066"
blue = "#7FB4CA"
# ... more colors

Change any color or module format, then restart your shell.

Edit ~/.config/nvim/lua/plugins/colorscheme.lua:

-- Current theme is Kanagawa-inspired
-- You can switch to another installed theme:
return {
  {
    "rebelot/kanagawa.nvim",
    lazy = false,
    priority = 1000,
    config = function()
      require("kanagawa").setup({
        -- customize here
      })
      vim.cmd("colorscheme kanagawa")
    end,
  },
}

# ~/.config/alacritty/alacritty.toml
# Gentleman colors are defined in [colors] section

The Gentleman OpenCode theme is at:

~/.config/opencode/themes/gentleman.json

Customize colors and apply:

{
  "colors": {
    "background": "#1a1b26",
    "foreground": "#dcd7ba",
    // ... more colors
  }
}

Common Workflows

Starting a New Project

Create project directory

mkdir my-project
cd my-project
git init

Start your window manager session

# Tmux
tmux new -s my-project

# Zellij
zellij -s my-project

Create window layout

Tmux
Zellij

# Window 1: Editor
nvim

# Prefix + c (new window)
# Window 2: Server
npm run dev

# Prefix + c (new window)
# Window 3: Git/commands
lazygit

# Tab 1: Editor
nvim

# Ctrl+t n (new tab)
# Tab 2: Server
npm run dev

# Ctrl+t n (new tab)
# Tab 3: Git
lazygit

Code with AI assistance

Inside Neovim:

" Open a file
:e src/index.js

" Ask AI for help
<Space>a
> How should I structure this Express app?

Daily Development Session

# Morning: Attach to yesterday's session
tmux attach -t my-project
# or: zellij attach my-project

# All your windows/tabs are exactly as you left them!
# Neovim still has your buffers open
# Server might still be running
# Git status ready to view

# End of day: Just close terminal
# Session persists, ready for tomorrow

# Or explicitly detach:
# Tmux: Prefix + d
# Zellij: Ctrl+o then d

Code Review Workflow

# Open LazyGit in Neovim
# Press: Space + gg

# Or from terminal:
lazygit

# Navigate commits with j/k
# Press Enter on a commit to see changes
# Press Space to stage/unstage files
# Press c to commit
# Press P to push

Debugging with AI

Encounter an error

npm run build
# Error: Module not found: '@/components/Button'

Ask the Gentleman agent

opencode
/agent
gentleman

> I'm getting "Module not found: '@/components/Button'". 
> What's wrong?

The agent will:

Ask to see your tsconfig.json or webpack config
Verify the actual file path
Propose 2-3 solutions with tradeoffs
NOT just say “you’re right” - it’ll investigate first!

Tips & Tricks

Persisting Sessions

Tmux sessions persist even when you close your terminal:

# Create named session
tmux new -s work

# Detach (Prefix + d)
# Close terminal completely
# Open terminal later

# List sessions
tmux ls

# Reattach
tmux attach -t work
# Everything is exactly as you left it!

Zellij works similarly:

zellij -s work
# Detach: Ctrl+o then d
# Later: zellij attach work

Speed Up Your Workflow

Use zoxide for smart navigation:

# After visiting directories a few times:
z proj    # jumps to ~/projects/my-project
z doc     # jumps to ~/Documents
z conf    # jumps to ~/.config

# See matches:
z -l proj

Use fzf for history:

# Press Ctrl+r, start typing
# Fuzzy search through all past commands
# Even commands from days ago!

Use eza aliases (if configured):

ll    # alias for: eza -l
la    # alias for: eza -la
lt    # alias for: eza -T (tree view)

Learn Neovim Gradually

Don’t try to learn everything at once:Week 1: Basic editing

i to insert, Esc to normal mode
h/j/k/l for movement
:w to save, :q to quit

Week 2: Navigation

w/b to move by word
0/$ to start/end of line
gg/G to start/end of file
Space + Space to find files

Week 3: Editing power moves

d to delete, y to yank (copy), p to paste
dd delete line, yy yank line
ciw change inner word
di( delete inside parentheses

Week 4: LSP & AI

gd go to definition
K hover docs
Space + ca code actions
Space + a AI assistant

Use :VimBeGood (included plugin) to practice!

Working with Multiple Projects

Create a tmux/zellij session per project:

# Project 1
tmux new -s frontend
cd ~/projects/frontend
nvim

# Detach: Prefix + d

# Project 2
tmux new -s backend
cd ~/projects/backend
nvim

# Detach: Prefix + d

# Switch between sessions:
# Prefix + s (shows list)
# Or from terminal:
tmux attach -t frontend
tmux attach -t backend

Update Your Dotfiles

To get the latest changes from Gentleman.Dots:

# Clone the repo
cd ~/tmp
git clone https://github.com/Gentleman-Programming/Gentleman.Dots.git
cd Gentleman.Dots

# Copy updated configs
cp -r GentlemanNvim/nvim/* ~/.config/nvim/
cp starship.toml ~/.config/
# etc.

# Or re-run the installer to update everything

Check the GitHub repo for changelogs and updates!

Troubleshooting

Neovim plugins not loading

" Inside Neovim:
:Lazy sync
" Wait for all plugins to install/update

" Check for errors:
:Lazy log

" Check health:
:checkhealth

LSP not working

" Check if language server is installed:
:Mason
" Install your language server (e.g., typescript-language-server)

" Check LSP status:
:LspInfo

" Restart LSP:
:LspRestart

Icons not showing (boxes or �)

The Nerd Font isn’t active in your terminal:

Verify font is installed:
```
fc-list | grep Iosevka  # Linux
```
Set font in terminal config:
- Alacritty: Edit font.normal.family in alacritty.toml
- WezTerm: Edit font = wezterm.font in .wezterm.lua
- Kitty: Edit font_family in kitty.conf
Restart terminal

AI commands not working

Check if AI CLIs are installed:

opencode --version
claude --version
gemini --version

# If missing, install:
curl -fsSL https://opencode.ai/install | bash
curl -fsSL https://claude.ai/install.sh | bash
brew install gemini-cli

Some may require API keys. Check each tool’s documentation.

Tmux prefix not working

If Ctrl+a doesn’t work as prefix:

Check config:

cat ~/.tmux.conf | grep prefix
# Should show: set -g prefix C-a

Reload config:
```
tmux source-file ~/.tmux.conf
```
If still using Ctrl+b, the config wasn’t loaded. Try:
```
# Inside tmux:
Ctrl+b :source-file ~/.tmux.conf
```

Zoxide not finding directories

Zoxide learns over time. Use directories normally with cd first:

# Visit directories a few times
cd ~/projects/my-app
cd ~/Documents
cd ~/.config

# Now zoxide knows them:
z app    # jumps to ~/projects/my-app
z doc    # jumps to ~/Documents
z conf   # jumps to ~/.config

What’s Next?

You now have a powerful development environment! Here’s what to explore:

Master Neovim

Practice with :VimBeGood
Learn one new keybinding per day
Explore plugins in ~/.config/nvim/lua/plugins/

Customize Your Setup

Tweak colors in starship.toml
Add your own Neovim plugins
Create custom shell aliases

Explore AI Features

Try different AI models in OpenCode
Test other AI plugins (Avante, CodeCompanion)
Experiment with the Gentleman agent’s prompts

Join the Community

Star the GitHub repo
Report issues or contribute
Share your customizations

Pro tip: The best way to learn is by doing. Start a real project and discover features as you need them. The which-key plugin (press Space and wait) will guide you along the way!

Remember: The Gentleman agent is there to challenge and improve your thinking, not just to agree with you. Embrace the constructive feedback!

Get Started

Terminal Emulators

Shells

Window Managers

Neovim Configuration

AI Integration

Platform-Specific Guides

Advanced

Welcome to Your New Environment

Launch Your Setup

Essential Keybindings

Window Manager Shortcuts

Shell Shortcuts

Launch Neovim

Essential Neovim Shortcuts

Switch AI Plugins

Configure OpenCode Model

Customize Your Theme

Common Workflows

Starting a New Project

Daily Development Session

Code Review Workflow

Debugging with AI

Tips & Tricks

Troubleshooting

What’s Next?

Master Neovim

Customize Your Setup

Explore AI Features

Join the Community

Build docs developers (and LLMs) love

Get Started

Terminal Emulators

Shells

Window Managers

Neovim Configuration

AI Integration

Platform-Specific Guides

Advanced

​Welcome to Your New Environment

​Launch Your Setup

​Essential Keybindings

​Window Manager Shortcuts

​Shell Shortcuts

​Launch Neovim

​Essential Neovim Shortcuts

​Switch AI Plugins

​Configure OpenCode Model

​Customize Your Theme

​Common Workflows

​Starting a New Project

​Daily Development Session

​Code Review Workflow

​Debugging with AI

​Tips & Tricks

​Troubleshooting

​What’s Next?

Master Neovim

Customize Your Setup

Explore AI Features

Join the Community

Build docs developers (and LLMs) love

Welcome to Your New Environment

Launch Your Setup

Essential Keybindings

Window Manager Shortcuts

Shell Shortcuts

Launch Neovim

Essential Neovim Shortcuts

Switch AI Plugins

Configure OpenCode Model

Customize Your Theme

Common Workflows

Starting a New Project

Daily Development Session

Code Review Workflow

Debugging with AI

Tips & Tricks

Troubleshooting

What’s Next?