Skip to content

CLAUDE.md

Latest commit

 

History

History
164 lines (106 loc) · 5.41 KB

CLAUDE.md

File metadata and controls

164 lines (106 loc) · 5.41 KB
Raw

CLAUDE.md

The global ~/.claude/CLAUDE.md (applies to all projects) is generated by dot_claude/CLAUDE.md. This file is scoped to this repo only.

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

What This Repository Is

This is a chezmoi-managed dotfiles repository for a Windows-primary development environment with Unix support. Chezmoi handles applying these files to the home directory.

Chezmoi Conventions

  • Files prefixed with dot_ map to dotfiles (e.g., dot_gitconfig.tmpl → ~/.gitconfig)
  • Files prefixed with run_once_ run once on first apply
  • Files prefixed with run_onchange_ run whenever the file content changes
  • Files ending in .tmpl are Go templates rendered by chezmoi using data from .chezmoi.toml.tmpl
  • AppData/ and dot_config/ mirror their target directory structure

Key Template Variables

Defined in .chezmoi.toml.tmpl and available in all .tmpl files:

  • {{ .name }} — "Gilbert Sanchez"
  • {{ .email }} — prompted on init
  • {{ .git_oss }} and {{ .git_work }} — separate OSS/work git directories (must end with /)
  • {{ .hasPwsh }} / {{ .pwshPath }} — whether pwsh is available
  • {{ .codespaces }} — true when running in GitHub Codespaces

External Dependencies

Managed in .chezmoiexternal.toml.tmpl — repos cloned automatically:

  • Windows: NeoVim config → AppData/Local/nvim; ZeBar Quiet Velvet theme
  • Unix: NeoVim config, Oh-My-Zsh, Tmux Plugin Manager, Vim plugins (airline, ctrlp, solarized)

All external repos refresh on a 168h (weekly) interval.

Package Management

Packages are defined in .chezmoidata/packages.json and installed by run_onchange_windows-install-packages.ps1.tmpl:

  • Chocolatey: chezmoi, espanso, gh, fzf, starship, wezterm, pwsh, etc.
  • PowerShell modules (PSGallery): Pester, Posh-Git, PSReadLine, Terminal-Icons, etc.

To add a package, edit .chezmoidata/packages.json — the install script reads from it.

PowerShell Profile Architecture

The PowerShell profile (dot_config/powershell/profile.ps1.tmpl) dot-sources scripts from ~/.local/share/powershell/Scripts/:

  • Initialize-Profile.ps1 — main entry point; loads other scripts
  • Functions.ps1 — custom functions, aliases, history picker
  • GitTools.ps1 — git utilities
  • ShellIntegration.ps1 — terminal/editor integration

The profile uses a hash-based change detection to skip reloading unchanged configs.

Git Configuration

dot_gitconfig.tmpl sets up dual-identity git using includeIf:

  • {{ .git_oss }} dir uses the main config
  • {{ .git_work }} dir uses a separate work identity

Notable custom aliases: sync (fetch+rebase+prune), stack/push-stack (branch stacking workflow), absorb (calls git-absorb).

Applying Changes

# Apply dotfiles to home directory
chezmoi apply

# Preview changes without applying
chezmoi diff

# Edit a managed file (opens in VS Code, applies on save)
chezmoi edit <file>

# Re-run a run_onchange script manually
chezmoi apply --force

Platform-Specific Files

Files excluded per platform via .chezmoiignore:

  • On Windows: dot_tmux.conf, dot_vimrc, dot_zshrc.tmpl, zsh scripts — these are Unix-only
  • On Unix: Windows-specific paths (AppData/, komorebi.json, etc.) are not managed

Espanso Prompts

AI prompt snippets live in AppData/Roaming/espanso/match/prompts.yml. Triggers use backtick prefix (e.g., `prompt, `rubrik). These are text-expansion templates for Claude/AI workflows.

Managed Claude Settings

Files in dot_claude are synced to all systems and should be system agnostic. When adding new "global" claude updates, they should be made to dot_claude\CLAUDE.md

Issue Reporting

When a problem is discovered with a tool or module (e.g., a failing chezmoi apply, broken install script, package manager error, unexpected PowerShell module behavior), use the AskUserQuestion tool to ask whether a GitHub issue should be opened before proceeding.

If the user says yes, file the issue against the relevant repo and include:

  • Description: A clear summary of the unexpected behavior
  • Environment: OS, tool/module version, shell version
  • Steps to reproduce:
    1. Minimal, self-contained reproduction (ideally a single command or config snippet)
    2. Exact command run and its full output
  • Expected behavior: What should have happened
  • Actual behavior: What actually happened, including the full error message/stack trace

PowerShell module example

**Module version**: x.x.x
**PowerShell version**: `$PSVersionTable` output (PSVersion, PSEdition, OS)
**OS**: Windows 11 / Ubuntu 22.04

## Steps to Reproduce
1. Install the module: `Install-Module ModuleName -Force`
2. Import and invoke:
   ```powershell
   Import-Module ModuleName
   Invoke-SomeFunction -Param 'value'
  1. Observe error

Expected

Actual

<full error output, including any inner exceptions>

Notes

<any relevant context, workarounds tried, etc.>


### chezmoi / dotfiles example

```markdown
**chezmoi version**: 2.x.x
**OS**: Windows 11 / Ubuntu 22.04
**Shell**: pwsh 7.x / bash 5.x

## Steps to Reproduce
1. Add the following to `.chezmoiexternal.toml.tmpl`:
   ...
2. Run `chezmoi apply`

## Expected
<what should have happened>

## Actual
Error: <full error output here>

## Notes
<any relevant context, workarounds tried, etc.>