dotfiles

This repo contains my dotfile configuration

I manage the various configuration files in this repo using GNU Stow. This allows me to set up symlinks for all of my dotfiles using a single command:

stow -t ~ zsh
stow -t ~ config
stow -t ~ oh-my-zsh-custom

Optional: one-shot bootstrap (clones Oh My Zsh if missing + runs stow):

./script/bootstrap

Full install (recommended on new machines): installs packages (macOS/Homebrew or Linux/apt), installs opencode, then runs bootstrap:

./script/install

Common options:

# core CLI only
./script/install --minimal

# skip GUI apps
./script/install --no-gui

# install a specific opencode version
OPENCODE_VERSION=1.1.50 ./script/install

Features / memo

Zsh

• Custom theme lives in $ZSH_CUSTOM (default: ~/.config/oh-my-zsh), so omz update works.
• Optional extras installed by `./script/bootstrap`:
  • zsh-autosuggestions
  • fast-syntax-highlighting
  • fzf-tab
• History is shared across shells and stored under XDG state (default: ~/.local/state/zsh/history).

Quick examples:

# Update Oh My Zsh
omz update

# Run dotfiles health checks
./script/doctor

# fzf helper (defined in zsh/.zshrc)
fe

Keyboard hints:

• autosuggestions: accept suggestion with Right Arrow
• fzf-tab: use TAB completion then pick in the fzf UI

Terminal tip:

• Ctrl-S is enabled for Neovim/Kitty (XON/XOFF disabled via `stty -ixon` in `zsh/.zshrc`).

Kitty

Key cheatsheet (from `config/.config/kitty/kitty.conf`):

splits:
  Ctrl+Alt+Shift+Right   vertical split (cwd=current)
  Ctrl+Alt+Shift+Down    horizontal split (cwd=current)

focus split:
  Ctrl+Alt+Arrow keys

resize:
  Ctrl+Alt+r             resize mode

tabs:
  Ctrl+Alt+t             new tab (cwd=current)
  Ctrl+Tab               next tab
  Ctrl+Shift+Tab         previous tab
  Ctrl+Alt+w             close tab

zoom:
  Ctrl+Alt+z             toggle stack layout

selection (rectangle mode, respects pane boundaries):
  Ctrl+Alt+left drag     select text in opencode without crossing to nvim

Neovim

• This repo commits `config/.config/nvim/lazy-lock.json` so plugin versions are reproducible across machines.
• By default, `./script/bootstrap` will not overwrite an existing ~/.config/nvim/lazy-lock.json.
• Recent edits are briefly highlighted (10s) so you can spot changes from tools like opencode.

Use the repo lockfile on a machine that already has a local one:

mv ~/.config/nvim/lazy-lock.json ~/.config/nvim/lazy-lock.json.bak
./script/bootstrap

opencode

This repo ships a small, safe subset of opencode state as templates:

• UI preferences: `opencode-state/.local/state/opencode/kv.json`
• Recent models: `opencode-state/.local/state/opencode/model.json`

It intentionally does not sync:

• prompt history (`prompt-history.jsonl`)
• usage/frecency stats (`frecency.jsonl`)

If you already have local state on a machine and want to adopt the repo defaults:

mv ~/.local/state/opencode/kv.json ~/.local/state/opencode/kv.json.bak
mv ~/.local/state/opencode/model.json ~/.local/state/opencode/model.json.bak
./script/bootstrap

If you want to explicitly sync your current (safe) local state back into the repo templates:

./script/opencode-sync push

Key cheatsheet (custom additions in this repo):

save:
  à (insert)    save + exit insert
  à (normal)    save
  <C-s>         save (layout-agnostic)
  <leader>w     save (layout-agnostic)

telescope:
  <leader>«     fuzzy find in current buffer
  <leader>sb    fuzzy find in current buffer (layout-agnostic)

codeium (ghost text):
  <C-l>         accept suggestion (Codeium)
  <M-Right>     next suggestion
  <M-Left>      previous suggestion
  <M-Down>      clear suggestion

opencode.nvim (<leader>a menu):
  Session management:
    <leader>aa    Ask (@this)
    <leader>an    New session
    <leader>au    Undo last action
    <leader>ar    Redo
    <leader>ac    Compact session
    <leader>as    Select session
    <leader>aS    Share session
    <leader>at    Toggle opencode
    <leader>ax    Execute action

  Prompts (<leader>ap):
    <leader>ape   Explain @this
    <leader>apf   Fix @diagnostics
    <leader>apr   Review @this
    <leader>apd   Document @this
    <leader>apo   Optimize @this
    <leader>apt   Add tests

  Context/Buffers (<leader>ab):
    <leader>abb   Send current buffer
    <leader>aba   Send all buffers
    <leader>abv   Send visible text
    <leader>abd   Send diagnostics

  Navigation:
    <S-C-u>       Half page up
    <S-C-d>       Half page down

  Operator (go + motion):
    go<motion>    Send range (ex: goip, gow, go$)
    goo           Send current line

poetry runner (Python projects):
  <leader>pr    Run current Python file via poetry in toggleterm
  :PoetryRun    Execute current file (auto-detects project root from pyproject.toml)

ToggleTerm (terminal management):
  <C-t>         Toggle terminal (from any mode, including terminal insert)
  <leader>tt    Toggle terminal (float)
  <Esc>         Exit terminal insert mode (then use <leader>tt or <C-t>)
  <leader>tf    Floating terminal
  <leader>th    Horizontal terminal
  <leader>tv    Vertical terminal
  <leader>t1    Terminal 1
  <leader>t2    Terminal 2
  <leader>t3    Terminal 3
  <leader>ts    Select terminal
  <leader>tg    Lazygit

nvim-dap (Node.js debugging in Docker):
  Prerequisites:
    - Docker container with Node.js running in debug mode (port 567xx)
    - Auto-detection scans ports 56700-56800

  Debug controls:
    <leader>dc    Start/Continue debugging (auto-detects port or shows menu)
    <leader>db    Toggle breakpoint on current line
    <leader>ds    Step over (execute current line, move to next)
    <leader>di    Step into (enter function call)
    <leader>do    Step out (exit current function)
    <leader>dx    Stop debugging session
    <leader>dr    Open REPL console
    <leader>dl    Run last debug configuration
    <leader>dt    Toggle DAP UI (scopes, stack, watches)

  Workflow:
    1. Start Docker container with Node.js debug port exposed (e.g., 56745)
    2. In nvim, place breakpoint: <leader>db on desired line
    3. Start debugging: <leader>dc (auto-detects port or asks)
    4. Navigate: <leader>ds (step over), <leader>di (step into)
    5. Inspect: Hover variables or toggle UI with <leader>dt
    6. Stop: <leader>dx when done

  Features:
    - Virtual text: Variable values displayed inline
    - Auto-detection: Scans for Node.js debug ports automatically
    - Port selection: Menu when multiple containers detected
    - Manual input: Enter port if auto-detection fails
    - Scopes panel: View all variables in current context
    - Call stack: Navigate through function calls
    - REPL: Execute JavaScript expressions during debug

New plugins (diffview, dadbod, lazydocker, markdown-preview, undotree):

diffview (git diff viewer):
  <leader>gd    Open diff view (compare working tree)
  <leader>gh    Open file history
  <leader>gq    Close diff view
  <tab>         Select next entry
  <s-tab>       Select previous entry
  s             Stage/unstage file
  S             Stage all files
  U             Unstage all files
  X             Restore entry
  gf            Go to file

vim-dadbod (database client):
  <leader>du    Toggle DB UI (database explorer)
  <leader>df    Find DB buffer
  <leader>dr    Rename DB buffer
  <leader>dl    Show last query info
  Note: Configure connections in ~/.config/nvim/lua/plugins/dadbod.lua

lazydocker (Docker TUI in terminal):
  <leader>td    Open LazyDocker (floating terminal)
  Note: Requires lazydocker installed on system

markdown-preview (live preview in browser):
  <leader>mp    Toggle markdown preview
  Note: Opens in default browser, auto-updates on edit

undotree (visual undo history):
  <leader>tu    Toggle undotree panel
  j/k           Navigate history tree
  u             Undo to selected state
  <CR>          Revert to selected state

Search/replace tips:

in file:
  :%s/old/new/gc     replace with confirmation

fast iterative replace:
  /pattern
  cgn                change match
  n + .              next + repeat

UI replace:
  <leader>sr         opens grug-far (if installed)

IDE-like workflow tips (LazyVim):

discover keymaps:
  <leader>            shows which-key menu

common LSP:
  K                   hover docs
  gd                  go to definition
  gr                  references
  <leader>rn          rename
  <leader>ca          code action

diagnostics:
  <leader>xx          diagnostics list (Trouble)

Modern terminal tools

eza (modern ls replacement with icons):
  ls            List files with icons and colors
  ll            List files in long format with icons
  la            List all files including hidden
  lt            List files as a tree
  llt           List files in long format as a tree

zoxide (smart cd command):
  cd <dir>      Navigate to directory (with fuzzy matching)
  cdi           Interactive directory selection with fzf
  z <pattern>   Jump to directory matching pattern
  zi            Interactive directory selection

delta (syntax-highlighting pager for git):
  git diff      Shows colored side-by-side diff
  git log       Shows colored log output
  git show      Shows colored commit/diff output

bottom (modern system monitor):
  btm           Launch interactive system monitor
  top           Alias for btm
  htop          Alias for btm

Oh My Zsh

This repo does not stow into ~/.oh-my-zsh anymore.

• Keep ~/.oh-my-zsh as a clean git checkout so omz update works.
• Put custom themes/plugins under $ZSH_CUSTOM (defaults to ~/.config/oh-my-zsh in zsh/.zshrc).

Install Oh My Zsh (git clone):

git clone https://github.com/ohmyzsh/ohmyzsh.git ~/.oh-my-zsh

Custom theme is shipped by this repo here:

• `oh-my-zsh-custom/.config/oh-my-zsh/themes/adrien-agnoster.zsh-theme`

Local (per-machine) config

If you need machine-specific paths or secrets, put them in ~/.zshrc.local.

Example template:

• `zsh/.zshrc.local.example`

Migration note

If you previously overrode the theme inside ~/.oh-my-zsh, remove that symlink so OMZ can update.

Typical fix:

rm -f ~/.oh-my-zsh/themes/agnoster.zsh-theme
cd ~/.oh-my-zsh && git checkout -- themes/agnoster.zsh-theme