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
```bash
# Initial setup - installs packages, plugin managers, and creates symlinks
./setup_env.sh

# Individual tool installations
./install_postgres.sh      # PostgreSQL from official repository
./install_python3.sh       # Latest Python 3 from deadsnakes PPA
./install_java_dev.sh      # SDKMAN for Java development
./install_neovim.sh        # Latest Neovim release
./install_visidata.sh      # VisiData for terminal data exploration
```

### Git Operations
```bash
# 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

**Critical Files:**
- `dotfiles/.bashrc` - Main bash configuration with extensive aliases and functions
- `dotfiles/.bashrc_local` - Machine-specific environment variables (PG, MS connection strings)
- `dotfiles/.bashrc_local_example` - Template for setting up machine-specific configs
- `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
- `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
- 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` - Health/care 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

### Environment Variables
Machine-specific environment variables (database connections, tokens, passwords) belong in `dotfiles/.bashrc_local`, not `.bashrc`. This file is sourced by `.bashrc` and should contain sensitive or machine-specific configuration.

The `.bashrc_local` file is gitignored for security. Use `dotfiles/.bashrc_local_example` as a template when setting up a new machine. Copy it to `.bashrc_local` and fill in your actual credentials.

### 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
Based on recent commits, this repository uses simple lowercase commit messages describing the change (e.g., "add cargo", "visidata", "install sdkman").