dotfiles - GitLite

KO | EN

gitlite — search

#javascript #python #typescript #llm #android #deep-learning #linux #nodejs #windows #kubernetes #vue #awesome-list #mcp #open-source

dotfiles

(★ 422)

:round_pushpin: My dotfiles for macOS using Neovim, Zsh, and Ghostty + Tmux

파일 탐색기

최종 버전 다운로드 (.zip)

- settings.json
- - test.yml
- .asdfrc
- .tool-versions
- Brewfile
- - cheatsheet.md
  - CLAUDE.md
  - keybindings.json
  - settings.json
  - starship.toml
- .stow-local-ignore
- claude-code-neovim.md
- .gitconfig
- .gitignore_global
- .gitmessage
- .laptop.local
- .markdownlint-cli2.yaml
- .default-npm-packages
- .npmrc
- .hushlogin
- .ripgreprc
- .default-gems
- .gemrc
- .irbrc
- .pryrc
- .rubocop.yml
- .stow-local-ignore
- lint-shell
- run-tests
- .stow-local-ignore
- environment.sh
- .stow-local-ignore
- en.utf-8.add
- en.utf-8.add.spl
- en.utf-8.spl
- en.utf-8.sug
- es.utf-8.add
- es.utf-8.add.spl
- es.utf-8.spl
- fr.utf-8.spl
- ru.utf-8.spl
- uk.utf-8.spl
- - starship.toml
- .stow-local-ignore
- tmux-256color.terminfo
- xterm-256color-italic.terminfo
- - test_core_abbr.bats
- - test_bubo.bats
- - test_gbrm.bats
  - test_gcom.bats
  - test_gpum.bats
  - test_grbm.bats
- - common.bash
  - git_helpers.bash
  - shell_helpers.bash
- - test_merge_presets.bats
- - test_publish_artifact.bats
- - test_agent_safety.bats
- - test_claude_folding.bats
- .stow-local-ignore
- cleanup.bash
- .stow-local-ignore
- .yamllint
- .zshrc
- README.md
.editorconfig
.gitignore
.pre-commit-config.yaml
.shellcheckrc
.stow-local-ignore
CLAUDE.md
LICENSE
nerd-font-smoke-test.sh
README.md
setup.sh

# 설치 가이드

1. 코드 내려받기

git clone https://github.com/joshukraine/dotfiles

깃허브에서 프로젝트 코드 전체를 내 컴퓨터로 내려받습니다.

cd dotfiles

방금 내려받은 프로젝트 폴더 안으로 이동합니다.

2. 공식 설치 스크립트

쉬움 추천

사전 준비물

Homebrew macOS/Linux용 패키지 매니저입니다.

brew install zsh

Homebrew로 이미 빌드된 패키지를 바로 설치합니다. 소스 빌드가 필요 없습니다.

✅ 설치 후 새 터미널을 열고, 프로그램의 버전 확인 명령(예: --version)으로 정상 설치됐는지 확인하세요.

이 레포의 README에 적힌 실제 명령어를 그대로 가져왔습니다.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# My Dotfiles for macOS

![dotfiles screenshot][screenshot]

## 🤩 Highlights

- [Neovim][neovim] editor configured with [LazyVim][lazyvim]💤
- [Starship][starship] prompt
- [Zsh][zsh] shell with [zsh-abbr][zsh-abbr] for abbreviations
- Flexible, terminal-based dev environment with [ghostty][ghostty] 👻 + [Tmux][tmux]!
- [Claude Code][claude-code] with custom skills, permission presets, and safety hooks
- Fast, idempotent setup with [GNU Stow][gnu-stow]
- New Mac bootstrap based on thoughtbot's [Laptop][laptop]
- Support for both Apple Silicon and Intel Macs

> [!NOTE]
> This project previously supported [Fish shell][fish] alongside Zsh. Fish support was removed in [PR #135][pr-135] (`f158de9`). If you were using the Fish configuration, you can reference that PR to see what changed or recover code for your own setup.

## ⚡️ Quick Setup

Make sure macOS is up to date and you have installed the [required software](#-prerequisites).

Clone this repo.

```sh
git clone https://github.com/joshukraine/dotfiles.git ~/dotfiles
```

Read the setup script and check available options.

```sh
less ~/dotfiles/setup.sh
~/dotfiles/setup.sh --help
```

Preview what the setup script will do (dry-run mode).

```sh
~/dotfiles/setup.sh --dry-run
```

Run the setup script.

```sh
~/dotfiles/setup.sh
```

## ✅ Prerequisites

The dotfiles assume you are running macOS with (at minimum) the following software pre-installed:

- [Git][git]
- [Homebrew][homebrew] (including [coreutils][coreutils])
- [asdf][asdf]
- [Ruby][ruby]
- [Node.js][nodejs]
- [Zsh][zsh]
- [Neovim][neovim]
- [Starship][starship]

All of the above and more are installed with my fork of [Laptop][joshuas-laptop].

## 🌟 New Mac Bootstrap

This is what I would do if I bought a new Mac computer today. The steps below assume you have already completed the basics:

- Log in to iCloud
- Check for software updates
- [Install Xcode Command Line Tools][install-clt]

### 💻 1. Run my fork of thoughtbot's Laptop

&#9657; **[github.com/joshukraine/laptop][joshuas-laptop]**

Download the `mac` script:

```sh
curl --remote-name https://raw.githubusercontent.com/joshukraine/laptop/main/mac
```

Download `.local.laptop` for additional customizations:

```sh
curl --remote-name https://raw.githubusercontent.com/joshukraine/dotfiles/master/laptop/.laptop.local
```

Review both scripts before proceeding:

```sh
less mac
```

```sh
less .laptop.local
```

Execute the `mac` script:

```sh
sh mac 2>&1 | tee ~/laptop.log
```

I've made the following changes to my fork of Laptop:

- Install asdf via git instead of Homebrew
- Comment out Heroku-related code
- Comment out unused Homebrew taps and formulae

It is worth noting that the Laptop script (`mac`) is idempotent and can be safely run multiple times to ensure a consistent baseline configuration.

### ⚠️ 2. Check for Stow conflicts

The dotfiles `setup.sh` script uses [GNU Stow][gnu-stow] to symlink all the config files to your `$HOME` directory. If you already have an identically-named file/directory in `$HOME` (e.g. `~/.zshrc` leftover from installing Laptop), this will cause a conflict, and Stow will (rightly) abort with an error.

The setup script will try to detect and backup these files ahead of Stow, but it's still a good idea to check your `$HOME` directory as well as `$HOME/.config` and `$HOME/.local/bin`.

On a fresh machine, `setup.sh` also pre-creates `~/.claude` as a real directory so Stow links the Claude config files individually instead of folding the whole directory into one symlink (which would route Claude Code's runtime state into the repo). If you forked before this behavior existed and see Claude runtime files appearing in `git status`, see [Troubleshooting: `~/.claude` folding](#troubleshooting-claude-folding).

### 📍 3. Clone and setup the dotfiles

Clone

```sh
git clone https://github.com/joshukraine/dotfiles.git ~/dotfiles
```

Read and preview

```sh
less ~/dotfiles/setup.sh
~/dotfiles/setup.sh --help
~/dotfiles/setup.sh --dry-run  # Preview changes without applying them
```

Setup

```sh
~/dotfiles/setup.sh
```

If you do encounter Stow conflicts, resolve these and run setup again. The script is idempotent, so you can run it multiple times safely.

### ⚡️ 4. Install Zap

[Zap][zap] describes itself as a _"minimal zsh plugin manager that does what you expect."_

&#9657; **[zapzsh.com][zap]**

> [!IMPORTANT]
> After copying/pasting the install command for Zap, be sure to add the `--keep` flag to prevent Zap from replacing you existing `.zshrc` file.

### 🍺 5. Install remaining Homebrew packages

Review the included `Brewfile` and make desired adjustments.

```sh
less ~/Brewfile
```

Install the bundle.

```sh
brew bundle install
```

### 🛠️ 6. Complete post-install tasks

- [ ] Launch LazyVim (`nvim`) and run [`:checkhealth`][checkhealth]. Resolve errors and warnings. Plugins should install automatically on first launch.
- [ ] Add personal data as needed to `*.local` files such as `~/.gitconfig.local`, `~/.laptop.local`.
- [ ] (Optional) Set up [1Password CLI][1p-cli-start] for managing secrets.
- [ ] (Optional) Set up [1Password SSH key management][1p-cli-ssh].
- [ ] Install Tmux plugins with `<prefix> + I` (<https://github.com/tmux-plugins/tpm>)

## Zsh Setup

Zsh is now the default shell on macOS. However, it's helpful to add an entry enabling the Homebrew version of Zsh (`/opt/homebrew/bin/zsh` on Apple Silicon, `/usr/local/bin/zsh` on Intel) instead of the default (`/bin/zsh`) version.

Ensure that you have Zsh from Homebrew. (`which zsh`) If not:

```sh
brew install zsh
```

Add Zsh (Homebrew version) to `/etc/shells`:

```sh
# Apple Silicon Macs:
echo /opt/homebrew/bin/zsh | sudo tee -a /etc/shells

# Intel Macs:
echo /usr/local/bin/zsh | sudo tee -a /etc/shells

# Or use this universal command:
echo $(which zsh) | sudo tee -a /etc/shells
```

Set it as your default shell:

```sh
chsh -s $(which zsh)
```

Install [Zap][zap].

Restart your terminal.

## Abbreviations

One of the best ideas I picked up from using Fish shell is [abbreviations over aliases](https://www.sean.sh/log/when-an-alias-should-actually-be-an-abbr/). [zsh-abbr][zsh-abbr] brings this functionality to Zsh.

Abbreviations are managed directly in `zsh/.config/zsh-abbr/abbreviations.zsh`. You can edit this file directly, or use the `abbr add`/`abbr remove` commands in your shell.

### Smart Git Functions

The configuration includes intelligent git functions that automatically detect your main branch:

- `gpum` - Push current branch to origin with upstream tracking
- `grbm` - Rebase on main/master
- `gcom` - Checkout main/master
- `gbrm` - Remove branches merged into main/master

These functions work with both `main` and `master` branch names automatically.

## Staleness Reporting

`bubo` reports what in the environment has drifted, across every surface `setup.sh` installs: Homebrew, Zap and its plugins, tmux/tpm plugins, asdf plugins and tool versions, Neovim/lazy, and Mason. It prints the command to fix anything that is behind.

```bash
bubo
```

```text
tmux plugins (tpm)           2 stale, 2 current
  tpm                        99469c4 -> e261deb
  vim-tmux-navigator         c45243d -> e41c431
  fix: ~/.config/tmux/plugins/tpm/bin/update_plugins all

mason                        4 stale, 33 current
  registry data: 4h old
  tree-sitter-cli            v0.26.10 -> v0.26.11
  fix: nvim +Mason  (then press U)
```

**It installs and upgrades nothing.** Index and registry refreshes are permitted and unavoidable — `brew update` refreshes the tap index, and lazy fetches — but nothing changes version. Fixing is always a separate, deliberate act. `bubc` upgrades Homebrew; the other fix commands are printed next to whatever needs them.

Everything runs in parallel, because the cost is almost entirely network round trips: the clone probes alone take 4.2s sequentially against 0.6s in parallel. The full report costs about 3s, against 2.5s for the `brew update && brew outdated` that `bubo` used to be.

Two properties are worth knowing, because both were learned from real bugs:

- **A probe that cannot reach the network reports `UNKNOWN`, never "current".** A report that under-reports staleness is worse than no report, because it turns "I don't know" into "you're fine". Same reason a symbolic asdf pin like `stable` reports `UNKNOWN`: it resolves at runtime, so comparing it against a version number is not a comparison.
- **Clone staleness compares HEAD SHAs**, rather than asking whether the remote HEAD object exists locally. The latter is the obvious check and it silently lies — the object is routinely already in the local store from an earlier fetch even though `HEAD` never moved. It called both `tpm` and `vim-tmux-navigator` current while each sat a commit behind.

That second bug is not hypothetical: a stale Zap plugin clone kept a fixed-upstream bug alive locally for 10 months, and nothing surfaced it.

## Claude Code

[Claude Code][claude-code] is Anthropic's CLI tool for AI-assisted development. This repo includes a full configuration under the `claude/` directory, stowed to `~/.claude/`.

> [!TIP]
> Claude Code pairs well with [Neovim][neovim] via the [sidekick.nvim][sidekick-nvim] plugin, which is how I use it most of the time during development. My preferred layout runs Claude as a sibling tmux pane (60% editor / 40% Claude) rather than nested inside the editor — see **[Claude Code + Neovim][claude-code-neovim]** for the setup, the reasoning, and how sidekick sends editor context across panes.

### Skills

Custom [skills][agent-skills] provide structured workflows for the full development lifecycle:

| Skill | Purpose |
| ----- | ------- |
| `/autopilot` | Carry one well-scoped issue through the full dev loop autonomously, to a review-ready PR (or merge for small reversible changes) |
| `/autopilot-batch` | Fan out a queue of issues to parallel worktree subagents, each running `/autopilot`, with an Opus gating review per PR |
| `/autopilot-triage` | Vet open issues for autonomous resolution and queue the qualifying ones for `/autopilot-batch` |
| `/bootstrap-prd` | Scaffold PRD-driven development infrastructure into a new project |
| `/checkpoint` | Quick status update — what's done, in progress, and blocked |
| `/create-pr` | Create a PR with auto-linked issues and formatted description |
| `/debrief` | Comprehensive walkthrough of recent work with architecture rationale |
| `/drift-check` | Pre-PR advisory check for deviations from the project spec (read-only) |
| `/dustoff` | Read-only re-entry assessment for a dormant project, with a prioritized plan |
| `/md2pdf` | Convert a Markdown file to PDF with GitHub-style formatting |
| `/merge-pr` | Merge a PR with status checks, squash merge, and branch cleanup |
| `/plan-phase` | Draft implementation plan and create GitHub issues (no code written) |
| `/prd-view` | Render a PRD Markdown file as a rich HTML reading view in the browser |
| `/qa-handoff` | Prepare a hands-on QA testing guide (Rails apps or static/Hugo sites) for a completed PRD phase |
| `/qa-triage` | Triage a QA-labeled report, classify it, and draft the technical issue(s) |
| `/qa-triage-batch` | Fan out `/qa-triage` across the open QA reports, cluster shared root causes across them, and create the tech issues behind one gate |
| `/readme-refresh` | Audit and update a project README, or bootstrap a new one |
| `/resolve-issue` | Structured workflow for resolving a GitHub issue end-to-end |
| `/ruby-gc` | Audit asdf-installed Ruby versions against project pins and remove unreferenced ones (dry-run by default) |
| `/sidecar` | Research-only mode for a secondary session sharing a working dir — no tracked-file edits or git mutations |
| `/todoist-cli` | Manage Todoist tasks, projects, and labels via the `td` CLI |
| `/update-deps` | Dependabot-aware dependency updates with security audit, CI validation, and a unified PR |
| `/walkthrough` | Generate a browser walkthrough of a PR's user-facing changes |

### Permission Presets

Composable permission presets control what Claude Code is allowed to do in each project. A base preset covers universal operations (git, file editing, Unix tools), and framework overlays add project-specific tooling.

```bash
cc-rails      # base + Rails overlay
cc-hugo       # base + Hugo overlay
cc-js         # base + JavaScript/Node overlay
cc-dotfiles   # base + dotfiles overlay
cc-sprint     # all-inclusive sprint preset
cc-default    # base only
cc-clean      # remove project settings
cc-perms      # show active permission counts
```

Presets live in `claude/.claude/presets/` with a [README][presets-readme] explaining the design.

### Safety

- **Hooks** block `rm -rf` patterns and log all Bash commands
- **Deny rules** prevent force push, hard reset, `sudo`, and credential reads
- **Sandbox mode** enabled by default with filesystem and network restrictions

### Shell Abbreviations

Zsh abbreviations for quick access (via [zsh-abbr][zsh-abbr]):

| Abbreviation | Expands to |
| ------------ | ---------- |
| `cl` | `claude` |
| `clr` | `claude --resume` |
| `clc` | `claude --continue` |
| `clup` | `claude update` |

See `zsh/.config/zsh-abbr/abbreviations.zsh` for the full set (`clsp`, `clh`, `clv`, `clp`, `clcp`, `clmcp`).

### Other Configuration

- **`CLAUDE.md`** — Global development philosophy and coding standards applied across all projects
- **[`cheatsheet.md`][cheatsheet]** — Quick reference for keyboard shortcuts (including fullscreen scrolling and custom keybindings), commands, and context management tips
- **`starship.toml`** — Custom [Starship prompt][starship-claude] showing model, context window status, and token cost

### Troubleshooting: `~/.claude` folding

`setup.sh` creates `~/.claude` as a real directory before stowing, so a fresh install links the Claude config files individually. If you cloned **before** that fix landed, you may have a _folded_ `~/.claude` — a single symlink pointing back into the repo — which makes Claude Code write its runtime state (`sessions/`, `projects/`, `history.jsonl`, …) straight into your dotfiles. The tells: a flood of untracked `claude/.claude/…` entries in `git status`, and `ls -ld ~/.claude` showing a symlink (`lrwx…`) rather than a directory (`drwx…`).

To repair an already-folded `~/.claude`, quit all `claude` sessions and run:

```bash
cd ~/dotfiles

stow -D claude/                                  # detach the folded ~/.claude symlink
mkdir -p ~/.claude                               # recreate it as a real directory

git restore --staged claude/.claude/             # unstage anything Claude's writes added
git restore claude/.claude/settings.json         # discard Claude's auto-edit, if present
git clean -fd claude/.claude/                    # delete the leaked runtime state

stow claude/                                     # re-link only the managed config
```

Then confirm the result:

```bash
ls -ld ~/.claude               # expect a real directory (drwx…), not a symlink (lrwx…)
ls -la ~/.claude | grep ' -> ' # expect exactly: CLAUDE.md, settings.json, starship.toml, skills, docs, presets
```

If a stray symlink such as `sessions` still points into the repo, remove just that link (`rm ~/.claude/sessions`) and re-run the `git clean` above so a later `stow -R` can't fold it back.

## About Neovim Distributions

> [!TIP]
> **TL;DR:** Just install [LazyVim][lazyvim]💤

📺 [Zero to IDE with LazyVim][zero-to-ide-lazyvim-video]

Back in the day if you wanted to use Vim (and later Neovim) you had to code a ton of configuration on your own. With Vim we got Vimscript 🤢, but then came Neovim which brought us Lua 🤩. I went from ye olde crunchy `.vimrc` to the more adventurous `init.vim` to the blessed path of `init.lua`. 😇

Meanwhile, there were the VS Code boys across the fence, bragging about their fancy icons, shiny tabs, and the oh-so-cool LSP. I confess, I even tried VS Code for a bit. That didn't last long. 😬

But Neovim has caught up. And wow have they. caught. up. Not only do we have native LSP support in Neovim (have had for a while now — v0.5), but we are solidly in the era of pre-baked Neovim distributions that are really challenging the notion of Vim/Neovim as austere, command-line editors. (I will say that I think we owe a lot to VS Code for raising the bar here. But I'm still glad I'm with Neovim. 😉)

If you want a quick primer on Neovim distros, **check out the YouTube video below**. I started with [LunarVim][lunar-vim] (my first entry into distro-land) and now I'm with [LazyVim][lazyvim] and the [Folke gang][folke]. Bottom line: you can still config [Neovim from scratch][neovim-from-scratch] if you want to, but you can get a HUGE head-start by just grabbing a distro and tweaking it to your needs.

📺 [I tried Neovim Distributions so you don't have to][i-tried-neovim-distros-video]

Boy, when I reminisce about the days of writing PHP for Internet Explorer in BBEdit...

## My Favorite Programming Fonts

Over the years, I've branched out to explore a variety of mono-spaced fonts, both free and premium. Here is a list of my favorites.

### Free Fonts

_Included in my `Brewfile` and installed by default via [Homebrew Cask Fonts][homebrew-cask-fonts]_

- [Cascadia Code][cascadia-code]
- [Fira Code][fira-code]
- [Hack][hack]
- [JetBrains Mono][jetbrains-mono]
- [Monaspace Argon][monaspace]
- [Monaspace Neon][monaspace]
- [Symbols Nerd Font Mono][symbols-nerd-font-mono] (for icons only)

### Premium Fonts

_You have to give people money if you want these._ 🤑

- [Operator Mono][operator-mono]
- [MonoLisa][monolisa]
- [Comic Code][comic-code]

### Ligatures

I first discovered ligatures through [Fira Code][fira-code], which IMHO is probably the king of programming fonts. After using Fira Code, it's hard to go back to a sans-ligature typeface. Therefore all the fonts I've included in my fave's list _do_ include ligatures, although some have more than others.

> [!NOTE]
> Operator Mono does not include ligatures but [can be easily patched][operator-mono-lig] to add them.

## Nerd Fonts and Icons

Back in the day, I started using the [VimDevicons][devicons] plugin so I could have fancy file-type icons in Vim. (Remember NERDTree?) In order for this to work, one had to install patched "Nerd-font" versions of whatever programming font one wanted to use. For example:

```sh
# Original font
$ brew install --cask font-fira-code

# Patched variant
$ brew install --cask font-fira-code-nerd-font
```

Patching fonts with icons still works fine of course, and is, I think, pretty widely used. However, during my exploration of kitty, I discovered that [there is a different (better?) approach](https://sw.kovidgoyal.net/kitty/faq/#kitty-is-not-able-to-use-my-favorite-font) to icon fonts. It turns out, you don't need a patched version of your chosen mono-spaced font. You can get most if not all the icons you need and use them alongside _any_ font by just installing the `Symbols Nerd Font Mono` font.

Leveraging this approach depends on your terminal. In iTerm2, for example, you need to check "Use a different font for non-ASCII text" in the Preferences panel. Then select `Symbols Nerd Font Mono` font under "Non-ASCII font". (see screenshot below)

![iterm2-font-settings][iterm2-font-settings]

kitty does things a little differently. If you install a patched font, it will mostly work. Mostly. But the "kitty way" can be broken down in three steps:

1. Install a normal, un-patched mono-spaced font, such as `Cascadia Code`
2. Install a dedicated icon font, such as `Symbols Nerd Font Mono`
3. Create a set of Unicode symbol maps[^2] to tell kitty which font to use for which icons (symbols)

More work up front, maybe, but less guesswork in the long-term once you understand what's going on. And if you're using my dotfiles, you have it easy. **All the fonts you need are installed in `Brewfile`, and I have a set of Unicode symbol maps ready to go.** 😎

> [!NOTE]
> To learn more about Nerd fonts in terminals, as well as Unicode symbol maps and all the rest, be sure to check out [Effective Nerd Fonts in Multiple Terminals](https://youtu.be/mQdB_kHyZn8?si=1mY6_oXEE8hr8lAp&t=289) by [Elijah Manor](https://www.youtube.com/@ElijahManor)

### 🧪 Nerd Font Smoke Test

If you want to check whether icons and ligatures are working properly, try running the included `nerd-font-smoke-test.sh` script from the root of the `dotfiles` folder like so:

```sh
bash nerd-font-smoke-test.sh
```

If your terminal is configured correctly, the output of the test should look like this:

![smoke-test-output][smoke-test-output]

Again, thank you, Elijah Manor!

### Useful Font Links

- [Nerd Fonts][nerd-fonts]
- [Nerd Font Cheat Sheet][nerd-font-cheat-sheet]
- [Programming Fonts - Test Drive][programming-fonts]
- [Homebrew Cask Fonts][homebrew-cask-fonts]

## A Note about Vim performance and Ruby files

Once upon a time, I almost left Vim due to some crippling performance issues. These issues were particularly painful when editing Ruby files. I documented what I learned here:

&#9657; [What I've learned about slow performance in Vim](https://gist.github.com/joshukraine/3bfff4e9b553624b09789bc02cdd0ce6)

## Identifying Sources of Slow Startup Times (Zsh)

The `.zshrc` script can be profiled by touching the file `~/.zshrc.profiler` and starting a new login shell. To see the top 20 lines that are taking the most time use the `zshrc_profiler_view`. `zshrc_profiler` parameters are number of lines to show (20) and path to profiler log file (`$TMPDIR/zshrc_profiler.${PID}log`).

## Awesome Neovim Dotfiles, Distros, and Starters

- <https://github.com/LazyVim/lazyvim>
- <https://github.com/LunarVim/LunarVim>
- <https://github.com/NvChad/NvChad>
- <https://github.com/LunarVim/Launch.nvim>
- <https://github.com/folke/dot>
- <https://github.com/nvim-lua/kickstart.nvim>
- <https://github.com/ThePrimeagen/init.lua>
- <https://github.com/elijahmanor/dotfiles>
- <https://github.com/cpow/cpow-dotfiles>
- <https://github.com/josean-dev/dev-environment-files>
- <https://github.com/glepnir/nvim>
- <https://github.com/numToStr/dotfiles>
- <https://github.com/jdhao/nvim-config>
- <https://github.com/brainfucksec/neovim-lua>
- <https://github.com/disrupted/dotfiles>
- <https://github.com/topics/neovim-dotfiles>
- <https://github.com/topics/neovim-config>

## Some of my favorite dotfile repos

- Pro Vim (<https://github.com/Integralist/ProVim>)
- Trevor Brown (<https://github.com/Stratus3D/dotfiles>)
- Chris Toomey (<https://github.com/christoomey/dotfiles>)
- thoughtbot (<https://github.com/thoughtbot/dotfiles>)
- Lars Kappert (<https://github.com/webpro/dotfiles>)
- Ryan Bates (<https://github.com/ryanb/dotfiles>)
- Ben Orenstein (<https://github.com/r00k/dotfiles>)
- Joshua Clayton (<https://github.com/joshuaclayton/dotfiles>)
- Drew Neil (<https://github.com/nelstrom/dotfiles>)
- Kevin Suttle (<https://github.com/kevinSuttle/OSXDefaults>)
- Carlos Becker (<https://github.com/caarlos0/dotfiles>)
- Zach Holman (<https://github.com/holman/dotfiles/>)
- Mathias Bynens (<https://github.com/mathiasbynens/dotfiles/>)
- Paul Irish (<https://github.com/paulirish/dotfiles>)

## Helpful web resources on dotfiles, et al

- <http://dotfiles.github.io/>
- <https://medium.com/@webprolific/getting-started-with-dotfiles-43c3602fd789>
- <http://code.tutsplus.com/tutorials/setting-up-a-mac-dev-machine-from-zero-to-hero-with-dotfiles--net-35449>
- <https://github.com/webpro/awesome-dotfiles>
- <http://blog.smalleycreative.com/tutorials/using-git-and-github-to-manage-your-dotfiles/>
- <http://carlosbecker.com/posts/first-steps-with-mac-os-x-as-a-developer/>
- <https://mattstauffer.co/blog/setting-up-a-new-os-x-development-machine-part-1-core-files-and-custom-shell>

## Development

This repo ships a small test and lint suite. Run both from the `dotfiles` root.

Lint shell scripts with [shellcheck][shellcheck]:

```sh
./scripts/lint-shell
```

Run the [bats][bats] test suite:

```sh
./scripts/run-tests          # all tests
./scripts/run-tests git      # git function tests
./scripts/run-tests abbr     # abbreviation tests
./scripts/run-tests presets  # permission-preset merge tests
```

Both checks also run in CI on every push and pull request via [GitHub Actions][gh-actions] (`.github/workflows/test.yml`), which additionally lints Markdown with [markdownlint-cli2][markdownlint].

## Customization

Local customizations should be placed in `*.local` files:

- `~/.gitconfig.local` - Personal git configuration
- `~/.laptop.local` - Additional laptop setup customizations
- `~/.config/ghostty/config.local` - Personal ghostty overrides (keybinds, fonts, theme)
- `~/.config/tmux/tmux.conf.local` - Personal tmux overrides (extra plugins, key bindings, options)
- `~/.config/tmux/project-accent.local.sh` - Per-project status bar accent colors (see below)

### Per-project tmux accent

When several projects are open at once — one tmux session each, created with [`tat`](bin/.local/bin/tat) — the status bar can be color-coded per project so they're easy to tell apart. Both ends of the bar are accented: the session-name "pill" on the left and the hostname pill on the right, giving a matching color band on each side that's easy to catch at a glance. Sessions without a mapping keep the theme's default blue, so this is a no-op until you opt in.

To enable it, copy the example map and edit it:

```sh
cd ~/.config/tmux
cp project-accent.local.sh.example project-accent.local.sh
$EDITOR project-accent.local.sh
```

Map each session to a color in the `accent_for` function, keyed by the tmux session name (the `#S` shown in the pill):

```sh
accent_for() {
  case "$1" in
    my-work-app) printf '%s' "#ff966c" ;;  # orange
    my-side-proj) printf '%s' "#c3e88d" ;; # green
    *) printf '%s' "" ;;
  esac
}
```

Colors can be hex (`#rrggbb`), a named color (`red`), or `colour0`–`colour255`. The real `project-accent.local.sh` is gitignored, so your project names and color choices never leave your machine.

> **Note:** the lookup key is the **tmux session name**, not the directory path. With [`tat`](bin/.local/bin/tat) the session name is the current directory's basename with dots converted to dashes (a `foo.bar` directory becomes session `foo-bar`), so map it as `foo-bar`. Keying on the session name lets two checkouts that share a directory name (e.g. `bfo1` and `bfo2`) still get distinct colors.

Colors apply automatically to new sessions (via a `session-created` hook) and backfill existing sessions whenever tmux is reloaded. The color is driven entirely by the `@accent` user option, which the theme renders into both pills; if you switch away from TokyoNight Moon, parameterize the new theme's pills with `#{@accent}` — see the comments in `~/.config/tmux/themes/tokyonight_moon.tmux`.

## License

Copyright &copy; 2014–2026 Joshua Steele. [MIT License][license]

[^2]: <https://sw.kovidgoyal.net/kitty/conf/#opt-kitty.symbol_map>

[1p-cli-ssh]: https://developer.1password.com/docs/ssh
[1p-cli-start]: https://developer.1password.com/docs/cli/get-started
[agent-skills]: https://agentskills.io
[asdf]: https://asdf-vm.com/
[bats]: https://github.com/bats-core/bats-core
[claude-code]: https://docs.anthropic.com/en/docs/claude-code/overview
[claude-code-neovim]: claude/claude-code-neovim.md
[cascadia-code]: https://github.com/microsoft/cascadia-code
[cheatsheet]: claude/.claude/cheatsheet.md
[checkhealth]: https://neovim.io/doc/user/pi_health.html#:checkhealth
[comic-code]: https://tosche.net/fonts/comic-code
[coreutils]: https://formulae.brew.sh/formula/coreutils
[devicons]: https://github.com/ryanoasis/vim-devicons
[fira-code]: https://github.com/tonsky/FiraCode
[fish]: https://fishshell.com/
[folke]: https://github.com/folke
[gh-actions]: https://github.com/joshukraine/dotfiles/actions
[ghostty]: https://ghostty.org/
[git]: https://git-scm.com/
[gnu-stow]: https://www.gnu.org/software/stow/
[hack]: https://sourcefoundry.org/hack
[homebrew-cask-fonts]: https://github.com/Homebrew/homebrew-cask
[homebrew]: http://brew.sh
[i-tried-neovim-distros-video]: https://youtu.be/bbHtl0Pxzj8
[install-clt]: https://www.freecodecamp.org/news/install-xcode-command-line-tools/
[iterm2-font-settings]: https://res.cloudinary.com/dnkvsijzu/image/upload/v1700122897/screenshots/iterm2-config_xqevqo.png
[jetbrains-mono]: https://www.jetbrains.com/lp/mono/
[joshuas-laptop]: https://github.com/joshukraine/laptop
[laptop]: https://github.com/thoughtbot/laptop
[lazyvim]: https://www.lazyvim.org/
[license]: https://github.com/joshukraine/dotfiles/blob/master/LICENSE
[lunar-vim]: https://www.lunarvim.org/
[markdownlint]: https://github.com/DavidAnson/markdownlint-cli2
[monaspace]: https://monaspace.githubnext.com
[monolisa]: https://www.monolisa.dev/
[neovim-from-scratch]: https://youtu.be/J9yqSdvAKXY
[neovim]: https://neovim.io/
[nerd-font-cheat-sheet]: https://www.nerdfonts.com/cheat-sheet
[nerd-fonts]: https://www.nerdfonts.com/
[nodejs]: https://nodejs.org/
[operator-mono-lig]: https://github.com/kiliman/operator-mono-lig
[operator-mono]: https://www.typography.com/fonts/operator/styles/operatormonoscreensmart
[pr-135]: https://github.com/joshukraine/dotfiles/pull/135
[presets-readme]: claude/.claude/presets/README.md
[starship-claude]: https://github.com/martinemde/starship-claude
[programming-fonts]: https://app.programmingfonts.org/
[ruby]: https://www.ruby-lang.org/en
[screenshot]: https://res.cloudinary.com/dnkvsijzu/image/upload/v1700154289/screenshots/dotfiles-nov-2023_gx2wrw.png
[shellcheck]: https://www.shellcheck.net/
[sidekick-nvim]: https://github.com/folke/sidekick.nvim
[smoke-test-output]: https://res.cloudinary.com/dnkvsijzu/image/upload/v1700085278/screenshots/smoke-test_tddntp.png
[starship]: https://starship.rs/
[symbols-nerd-font-mono]: https://github.com/ryanoasis/nerd-fonts/releases/latest/download/NerdFontsSymbolsOnly.zip
[tmux]: https://github.com/tmux/tmux/wiki
[zap]: https://www.zapzsh.com/
[zero-to-ide-lazyvim-video]: https://youtu.be/N93cTbtLCIM
[zsh-abbr]: https://zsh-abbr.olets.dev/
[zsh]: https://zsh.sourceforge.io/