From 6bcf9d10de51281d9e4565373a60c677ff970c36 Mon Sep 17 00:00:00 2001 From: Daniel Bauer Date: Sun, 16 Aug 2026 10:23:58 +0200 Subject: [PATCH] feat: create agents.md --- AGENTS.md | 43 +++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 44 +------------------------------------------- 2 files changed, 44 insertions(+), 43 deletions(-) create mode 100644 AGENTS.md mode change 100644 => 120000 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..9916614 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,43 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## What this repo is + +Personal dotfiles managed with [chezmoi](https://chezmoi.io). This directory (`~/.local/share/chezmoi`) is chezmoi's *source* directory — files here use chezmoi's naming conventions and are rendered/installed into `$HOME` on the target machine, they are not consumed directly from this path. + +**Use the `chezmoi` skill (`.claude/skills/chezmoi-skill/SKILL.md`) for any work in this repo.** It covers chezmoi's source-file naming conventions (`dot_`, `private_`, `executable_`, `.tmpl`), machine-specific templating patterns, the required `chezmoi apply --refresh-externals --force` flags, `.chezmoiremove`/`.chezmoiexternal.toml`, and troubleshooting — invoke it rather than re-deriving this from scratch. + +## Commands + +Preview and apply changes (run from anywhere; chezmoi finds the source dir automatically): + +```bash +chezmoi diff # preview pending changes before applying +chezmoi apply --refresh-externals --force # apply — always use both flags (force avoids interactive prompts Claude can't answer) +chezmoi cat # preview a rendered template's output +chezmoi execute-template '{{ .chezmoi.os }}' # test a template snippet in isolation +chezmoi re-add # pull an edited target file back into the source dir +chezmoi status # what's pending +``` + +Syncing to git (per README.md): + +```bash +chezmoi cd # cd into the source dir (this repo) +git add --all && git commit && git push +chezmoi update # pull + apply on another machine +``` + +There is no build, lint, or test suite — this is a config repo. "Testing" a change means `chezmoi diff`/`chezmoi cat` to check rendering, then `chezmoi apply --refresh-externals --force` and exercising the shell/tool it affects. + +## Architecture + +- **`run_onchange_before_NN_*.sh`** — idempotent setup scripts chezmoi re-runs whenever their content hash changes, in numeric order (`0` installs apt packages, `1` sets zsh as default shell and installs antidote, `20`+ install individual tools: fzf, diff-so-fancy, vim-plug, tmux plugin manager, lazygit, fonts, nbdime). New machine-setup steps should follow this pattern: a numbered `run_onchange_before_*.sh` with `set -euo pipefail` and an existence check so re-runs are no-ops. +- **`.chezmoi.toml.tmpl`** — chezmoi's own config template. Interactively prompts once for `github_email`/`machineClass` on a real terminal; when non-interactive (`stdinIsATTY` false), `CODESPACES` is set, or `.chezmoi.username` is `vscode` — auto-detected as `ephemeral`, overridable via `CHEZMOI_EPHEMERAL` — it skips prompting and instead reads `CHEZMOI_GITHUB_EMAIL` (may be left empty) and `CHEZMOI_MACHINE_CLASS` (defaults to `public`). `ephemeral` is written to `[data]` alongside `machineClass`/`github_email` and gates lifecycle-only setup (fonts — see `run_onchange_before_25_fonts.sh.tmpl`). `chezmoi apply` never auto-commits/pushes to this repo on any machine; sync manually per the Commands section below. +- **Shell startup chain**: `dot_zshrc` sources `bin/term-background` (must run before the p10k instant-prompt block, since it reads the tty for OSC 11 background detection) → p10k instant prompt → `~/.environment`(`dot_environment`) + optional `~/.environment.local` → `~/.aliases` (`dot_aliases`) + optional `~/.aliases.local` → antidote plugin load (plugin list in `dot_zsh_plugins.txt`) → `~/.p10k.zsh`. The `.local` files are gitignored, host-specific overrides — never add machine-specific values directly to the tracked files. +- **`dot_gitconfig.tmpl`** — templated on `.github_email`, whose `[user] email` line is omitted entirely when `.github_email` is empty (e.g. an ephemeral machine with no `CHEZMOI_GITHUB_EMAIL` set); wires up diff-so-fancy as the pager and nbdime for Jupyter notebook diffing. `~/.gitconfig.local` (untracked) is included for machine-specific overrides. +- **`private_dot_config/`** → installs to `~/.config/` with restrictive permissions (nvim, matplotlib styles, fontconfig). +- **`bin/`** → installs to `~/bin/`; `executable_term-background` detects terminal light/dark background via OSC 11 for theme-matching in nvim etc. +- **`.chezmoiignore`** lists source-repo-only paths (`README.md`, `.codex`, `.agents`, `CLAUDE.md`, `CLAUDE.local.md`, `key.txt.age`) that chezmoi should never install to `$HOME`, plus a `machineClass`-gated conditional excluding `.ssh/config.d/home`, `.ssh/config.d/web`, and `.claude/settings.json` on any machine that isn't `machineClass = "private"` — `~/.claude/settings.json` has no user-level `.local.json` merge mechanism, so machines with differing Claude Code config (e.g. `enabledPlugins`) manage that file by hand instead of via chezmoi. +- **Age encryption**: `key.txt.age` (repo root) is an age private key encrypted with a passphrase.`run_onchange_before_02_decrypt-age-key.sh.tmpl` decrypts it into `~/.config/chezmoi/key.txt`. diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index 9916614..0000000 --- a/CLAUDE.md +++ /dev/null @@ -1,43 +0,0 @@ -# CLAUDE.md - -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. - -## What this repo is - -Personal dotfiles managed with [chezmoi](https://chezmoi.io). This directory (`~/.local/share/chezmoi`) is chezmoi's *source* directory — files here use chezmoi's naming conventions and are rendered/installed into `$HOME` on the target machine, they are not consumed directly from this path. - -**Use the `chezmoi` skill (`.claude/skills/chezmoi-skill/SKILL.md`) for any work in this repo.** It covers chezmoi's source-file naming conventions (`dot_`, `private_`, `executable_`, `.tmpl`), machine-specific templating patterns, the required `chezmoi apply --refresh-externals --force` flags, `.chezmoiremove`/`.chezmoiexternal.toml`, and troubleshooting — invoke it rather than re-deriving this from scratch. - -## Commands - -Preview and apply changes (run from anywhere; chezmoi finds the source dir automatically): - -```bash -chezmoi diff # preview pending changes before applying -chezmoi apply --refresh-externals --force # apply — always use both flags (force avoids interactive prompts Claude can't answer) -chezmoi cat # preview a rendered template's output -chezmoi execute-template '{{ .chezmoi.os }}' # test a template snippet in isolation -chezmoi re-add # pull an edited target file back into the source dir -chezmoi status # what's pending -``` - -Syncing to git (per README.md): - -```bash -chezmoi cd # cd into the source dir (this repo) -git add --all && git commit && git push -chezmoi update # pull + apply on another machine -``` - -There is no build, lint, or test suite — this is a config repo. "Testing" a change means `chezmoi diff`/`chezmoi cat` to check rendering, then `chezmoi apply --refresh-externals --force` and exercising the shell/tool it affects. - -## Architecture - -- **`run_onchange_before_NN_*.sh`** — idempotent setup scripts chezmoi re-runs whenever their content hash changes, in numeric order (`0` installs apt packages, `1` sets zsh as default shell and installs antidote, `20`+ install individual tools: fzf, diff-so-fancy, vim-plug, tmux plugin manager, lazygit, fonts, nbdime). New machine-setup steps should follow this pattern: a numbered `run_onchange_before_*.sh` with `set -euo pipefail` and an existence check so re-runs are no-ops. -- **`.chezmoi.toml.tmpl`** — chezmoi's own config template. Interactively prompts once for `github_email`/`machineClass` on a real terminal; when non-interactive (`stdinIsATTY` false), `CODESPACES` is set, or `.chezmoi.username` is `vscode` — auto-detected as `ephemeral`, overridable via `CHEZMOI_EPHEMERAL` — it skips prompting and instead reads `CHEZMOI_GITHUB_EMAIL` (may be left empty) and `CHEZMOI_MACHINE_CLASS` (defaults to `public`). `ephemeral` is written to `[data]` alongside `machineClass`/`github_email` and gates lifecycle-only setup (fonts — see `run_onchange_before_25_fonts.sh.tmpl`). `chezmoi apply` never auto-commits/pushes to this repo on any machine; sync manually per the Commands section below. -- **Shell startup chain**: `dot_zshrc` sources `bin/term-background` (must run before the p10k instant-prompt block, since it reads the tty for OSC 11 background detection) → p10k instant prompt → `~/.environment`(`dot_environment`) + optional `~/.environment.local` → `~/.aliases` (`dot_aliases`) + optional `~/.aliases.local` → antidote plugin load (plugin list in `dot_zsh_plugins.txt`) → `~/.p10k.zsh`. The `.local` files are gitignored, host-specific overrides — never add machine-specific values directly to the tracked files. -- **`dot_gitconfig.tmpl`** — templated on `.github_email`, whose `[user] email` line is omitted entirely when `.github_email` is empty (e.g. an ephemeral machine with no `CHEZMOI_GITHUB_EMAIL` set); wires up diff-so-fancy as the pager and nbdime for Jupyter notebook diffing. `~/.gitconfig.local` (untracked) is included for machine-specific overrides. -- **`private_dot_config/`** → installs to `~/.config/` with restrictive permissions (nvim, matplotlib styles, fontconfig). -- **`bin/`** → installs to `~/bin/`; `executable_term-background` detects terminal light/dark background via OSC 11 for theme-matching in nvim etc. -- **`.chezmoiignore`** lists source-repo-only paths (`README.md`, `.codex`, `.agents`, `CLAUDE.md`, `CLAUDE.local.md`, `key.txt.age`) that chezmoi should never install to `$HOME`, plus a `machineClass`-gated conditional excluding `.ssh/config.d/home`, `.ssh/config.d/web`, and `.claude/settings.json` on any machine that isn't `machineClass = "private"` — `~/.claude/settings.json` has no user-level `.local.json` merge mechanism, so machines with differing Claude Code config (e.g. `enabledPlugins`) manage that file by hand instead of via chezmoi. -- **Age encryption**: `key.txt.age` (repo root) is an age private key encrypted with a passphrase.`run_onchange_before_02_decrypt-age-key.sh.tmpl` decrypts it into `~/.config/chezmoi/key.txt`. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file