setup_env/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Repository Overview

Personal Linux development environment setup. Clone and run one script to get a consistent shell and editor across machines.

Key Commands

Fresh machine setup

git clone git@gitea.hptrow.me:pt/setup_env.git ~/setup_env
cd ~/setup_env && ./setup_env.sh

setup_env.sh installs packages, downloads Neovim, clones plugin managers, deploys all dotfile symlinks, and sets up NvChad.

Day-to-day sync

cd ~/setup_env && ./sync.sh

Pulls setup_env and nvim config repos, redeploys symlinks. Safe to run anytime.

Optional tool installs (run manually per machine)

./install_postgres.sh      # PostgreSQL from official apt repository
./install_python3.sh       # Latest Python 3 from deadsnakes PPA (includes python3-venv)
./install_node.sh          # Node.js via nvm (needed for prettier formatter in nvim)
./install_java_dev.sh      # SDKMAN for Java development
./install_visidata.sh      # VisiData for terminal data exploration
./reinstall_nvchad.sh      # Wipe and reinstall NvChad from scratch

After plugin manager install

• Tmux: press Ctrl-b + I to install TPM plugins
• Vim: run :PluginInstall inside vim

Architecture

Scripts

• setup_env.sh — fresh machine only. Installs everything in order.
• sync.sh — day-to-day. Pulls repos and redeploys symlinks. No apt, no sudo.
• _lib.sh — shared deploy functions sourced by both scripts.
• install_neovim.sh — downloads Neovim v0.11.3 to /opt/, auto-adds to .bashrc_paths. Called by setup_env.sh.
• install_nvchad.sh — clones nvim config from gitea on fresh install, or git pulls if already present. Called by both setup_env.sh and sync.sh.
• reinstall_nvchad.sh — wipes all nvim data and re-runs install_nvchad.sh. Run manually when nvim is broken.
• install_*.sh — optional installs, run manually per machine.

Dotfile Management

Symlink-based deployment. Editing ~/.<file> directly edits the repo file. git status shows config drift.

deploy_configs, deploy_bin, and deploy_nvim (in _lib.sh) handle symlinking. create_symlink skips if already correct. migrate_and_link (used for gitignored files) migrates existing real files into the repo, or bootstraps from _example if nothing exists.

Tracked dotfiles (in git):

• dotfiles/.bashrc — main shell config
• dotfiles/.vimrc, .gitconfig, .tmux.conf, .psqlrc, .pspgconf
• dotfiles/bin/td — time-tracking CLI
• dotfiles/nvim/mappings.lua — all nvim keybindings
• dotfiles/nvim/td.lua, td_mappings.lua — nvim time-tracking integration
• dotfiles/nvim/rename_term.lua — vault-wide find-and-replace with confirmation popup (<leader>rn)
• dotfiles/nvim/telescope_tasks.lua — vault-wide task pickers (<leader>tl open tasks, <leader>tL priority tasks)

Gitignored (machine-specific, auto-bootstrapped from examples):

• dotfiles/.bashrc_local — secrets and credentials
• dotfiles/.bashrc_paths — PATH additions and tool inits

Two-repo nvim setup

The nvim config lives in a separate repo at git@gitea.hptrow.me:pt/nvchad.git (customize branch), deployed to ~/.config/nvim. install_nvchad.sh manages it.

dotfiles/nvim/td.lua and td_mappings.lua are deployed as symlinks into ~/.config/nvim/lua/ by deploy_nvim. The nvim repo's mappings.lua loads them via require "td_mappings". The nvim repo does not track these files — setup_env owns them.

Dependency: deploy_nvim must run after install_nvchad.sh has created ~/.config/nvim/lua/. On a fresh machine this is handled automatically by setup_env.sh ordering. On existing machines sync.sh handles it.

Custom Bash Workflow

Database Query Management

PostgreSQL (env var $PG defined in .bashrc_local):

• xnspa([args]) — fzf-select an open nvim swap file, run with $PG, output CSV to VisiData. Accepts extra psql args.
• xnsp — same, output to pspg
• xns — same, raw output

SQL Server (env vars $MS, $MSC, $MSW in .bashrc_local):

• xmspa() — fzf-select swap file, run with $MSC, pipe-delimited output to VisiData
• xmsp — same, output to pspg
• xms — same, raw output

General:

• ons — list open nvim swap files in current directory tree

Git Aliases

• gs — git status short
• ga — interactive git add via fzf
• gx — interactive git checkout via fzf
• vc() — git add -u, commit with timestamp, push
• gr, gc, gd, gl — reset, commit, difftool, log

Todo Grep (rg-based)

• td — find unchecked todos
• tdp / tdtp — priority todos (🔼 / ⏫)
• tdo / tdop — open todo in nvim at exact line

Time Tracking

Shell wrappers around dotfiles/bin/td (bypasses the td rg alias via command td):

• tstart / tstop / treport / tweek

Nvim keymaps (via td_mappings.lua): <leader>ts/tp/tr/tw

Other Aliases

• cj — cd to journal
• jr / hc — sync journal / hc notes

Machine-specific Configuration

.bashrc sources two gitignored files:

• .bashrc_local — secrets: DB connection strings, passwords, tokens
• .bashrc_paths — PATH additions: nvim, cargo, nvm, java, etc.

Both are auto-bootstrapped from _example files on first setup_env.sh run. When a tool appends to .bashrc, git status shows it — move those lines to .bashrc_paths.

Git Commit Style

Simple lowercase messages: "add cargo", "visidata", "fix nv alias path"