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

This is a personal development environment setup repository containing:

• Shell scripts for automated installation of development tools
• Dotfiles for bash, vim, tmux, git, psql, and pspg
• The main setup_env.sh script deploys dotfiles as symlinks and installs base packages

Key Commands

Environment Setup

# Initial setup - installs packages, plugin managers, and creates symlinks
./setup_env.sh

# Individual tool installations
./install_postgres.sh      # PostgreSQL from official apt repository
./install_python3.sh       # Latest Python 3 from deadsnakes PPA
./install_java_dev.sh      # SDKMAN for Java development
./install_neovim.sh        # Latest Neovim release, extracted to /opt/
./install_nvchad.sh        # NvChad Neovim config
./install_visidata.sh      # VisiData for terminal data exploration

After running setup_env.sh, activate plugins:

• Tmux: Press prefix + I (Ctrl-b + I) to install TPM plugins
• Vim: Run :PluginInstall inside vim to install Vundle plugins

Git Operations

# Automated commit and push (defined in .bashrc)
vc                         # git add . && commit with timestamp && push

# Custom git aliases (defined in .gitconfig)
git pushall                # Push to all remotes

Architecture

Dotfile Management System

The repository uses symlink-based configuration deployment. When setup_env.sh runs:

1. deploy_configs symlinks each dotfile in dotfiles/ to ~/.<filename> (backing up any existing file)
2. deploy_bin symlinks every file in dotfiles/bin/ to ~/.local/bin/<filename>
3. This allows version control of configs and user-local scripts while keeping them in their expected locations

All dotfiles are symlinked, not copied. Editing ~/.<file> directly modifies files in the repository.

Critical Files:

• dotfiles/.bashrc - Main bash configuration with extensive aliases and functions
• dotfiles/.bashrc_local - Machine-specific secrets and credentials (PG, MS connection strings)
• dotfiles/.bashrc_local_example - Template for .bashrc_local
• dotfiles/.bashrc_paths - Machine-specific PATH additions and tool inits
• dotfiles/.bashrc_paths_example - Template for .bashrc_paths
• dotfiles/.vimrc - Vim configuration using Vundle plugin manager
• dotfiles/.tmux.conf - Tmux configuration with vim-style pane navigation
• dotfiles/.gitconfig - Git configuration with custom log format and vimdiff
• dotfiles/.psqlrc - PostgreSQL client configuration
• dotfiles/.pspgconf - pspg (PostgreSQL pager) configuration
• dotfiles/bin/td - Python CLI for time-tracking markdown todos (see Time tracking section)

Custom Bash Workflow

The .bashrc contains a sophisticated workflow for working with:

Database Query Management:

PostgreSQL workflow:

• xnspa() function - Interactive file selector for running PostgreSQL queries through nvim swap files, outputs to VisiData as CSV. Accepts extra psql args (e.g. xnspa -v var=val).
• xnsp - Select and execute SQL file through fzf with pspg output
• xns - Select and execute SQL file through fzf
• PG environment variable - psql connection string to database (defined in .bashrc_local)

SQL Server workflow:

• xmspa() function - Interactive file selector for SQL Server queries through nvim swap files, outputs to VisiData with pipe-delimited format
• xmsp - Select SQL file via fzf, execute with sqlcmd, pipe to pspg
• xms - Select SQL file via fzf, execute with sqlcmd
• MS environment variable - sqlcmd connection string to SQL Server (defined in .bashrc_local)
• MSC environment variable - sqlcmd connection string with pipe-delimited output format (defined in .bashrc_local)
• MSW environment variable - Windows sqlcmd connection (optional, defined in .bashrc_local)

General:

• ons - List open nvim files in current directory tree

Git workflow aliases:

• gs - git status short format
• ga - Interactive git add using fzf for file selection
• gx - Interactive git checkout using fzf
• gr - git reset HEAD
• gc - git commit verbose
• gd - git difftool
• gl - Pretty git log with colors

Todo grep aliases (rg-based):

• td - Find unchecked todo items using ripgrep
• tdp - Find priority todos (with 🔼 or ⏫)
• tdtp - Find top priority todos (⏫ only)
• tdo - Open todo in nvim at exact line
• tdop - Open priority todo in nvim at exact line

Time tracking (functions wrapping dotfiles/bin/td):

• tstart <tid> - Start a timer on a task identified by a ^tid-* block-ref
• tstop - Stop the running timer
• treport [filter] - Show totals per tid, filterable by tid or filename
• tweek [filter] - Show this week's time summary
• Wrappers use command td to bypass the td rg alias. The CLI writes one row per entry to $TD_LOG (default ./time.csv, cwd-scoped).
• Companion nvim integration (in the separate ~/.config/nvim repo) adds <leader>ts/tp/tr keymaps with auto-generated tids.

Other useful aliases:

• nv - Launch Neovim from custom installation path
• cj - Navigate to journal directory
• jr - Journal sync (pull, commit, push)
• hc - hc companies notes sync (pull, push)

Plugin Managers

• Vim: Vundle (installed to ~/.vim/bundle/Vundle.vim)
• Tmux: TPM - Tmux Plugin Manager (installed to ~/.tmux/plugins/tpm)
  • Plugins: tmux-resurrect, jimeh/tmux-themepack
• Bash: bash-git-prompt (installed to ~/.bash-git-prompt)

Package Dependencies

Base packages installed by setup_env.sh:

• tmux, vim, git, pspg, bat, fzf, ripgrep

Important Conventions

Machine-specific configuration

There are two gitignored files for machine-specific configuration, both sourced by .bashrc:

• .bashrc_local — secrets and credentials: database connection strings, passwords, tokens. Use dotfiles/.bashrc_local_example as a template.
• .bashrc_paths — PATH additions and tool initializations: neovim, cargo, nvm, java, etc. Use dotfiles/.bashrc_paths_example as a template.

On a new machine, copy both examples and fill them in:

cp dotfiles/.bashrc_local_example dotfiles/.bashrc_local
cp dotfiles/.bashrc_paths_example dotfiles/.bashrc_paths

When a tool (cargo, nvm, conda, etc.) auto-appends lines to .bashrc, git status will show the modification — that's your signal to move those lines to .bashrc_paths instead.

Symlink Pattern

When modifying dotfiles, remember they are symlinked. Changes are automatically tracked by git since the actual files are in the repository's dotfiles/ directory.

Git Commit Messages

This repository uses simple lowercase commit messages describing the change (e.g., "add cargo", "visidata", "install sdkman").