Personal dotfiles repository for editor, terminal, CLI, and local toolchain configuration.
This repository manages:
- Neovim configuration in
nvim/ - terminal and shell configuration in
terminal/,ghostty/,wezterm/,zellij/, andstarship/ - editor settings for VS Code in
vscode/ - Homebrew packages in
homebrew/Brewfile - Bun global packages in
bun/ - local setup and published CLI commands in
scripts/ - AI tool configuration in
ai/
Human-facing setup and usage live in this README. Repository-wide design decisions live under docs/. Agent-facing guidance lives in AGENTS.md.
Clone the repository and enter the working directory:
git clone [repository_url]
cd [cloned_repository_path]Install mise first if it is not already available in your shell.
brew install miseRun the standard install flow:
mise run installThis install flow links dotfiles-managed files, syncs published global commands, installs local mise tools, prepares Bun globals, and installs the repository pre-commit hook.
Common entrypoints:
mise run install
mise run relink
mise run install-pre-commit
mise run check-pre-commit
mise run format
mise run upgradeUseful direct commands after install:
add-worktree
add-worktree-remote
delete-worktree
reveal-repository-with-neovim
search-abbreviation
search-task
switch-branch
switch-branch-remotenvim/: Neovim configuration and plugin setupvscode/: VS Code settings and keybindingsscripts/local/: setup and repository-local scriptsscripts/global/: published standalone CLI commandsscripts/utils/: shared shell helpershomebrew/: trackedBrewfilebun/: Bun global packages managed in-reposheldon/: shell plugin manager config and abbreviationsai/: AI tool configuration and custom skillssrc/samples/: sample files for editor and LSP checks
Python development dependencies are managed with uv.
uv sync --group dev
uv run pre-commit installRun all checks:
uv run pre-commit run -aThe base ~/.gitconfig is managed as a symlink from this repository.
- Run
scripts/local/link-dotfiles.shto linkgit/.gitconfig - Put machine-specific overrides in
~/.gitconfig.local - Repositories fetched with
ghq getare expected under~/Git/ghq
When terminal/.zshrc is linked, add-worktree, add-worktree-remote, switch-branch, switch-branch-remote, and delete-worktree provide interactive branch and worktree management with fzf.
On macOS, scripts/local/link-dotfiles.sh also links VS Code user files under ~/Library/Application Support/Code/User.
If settings.json or keybindings.json already exist as real files, the script leaves them in place and prints a warning instead of overwriting them.
AI tool configuration is grouped under ai/.
- each skill under
ai/skills/is published directly into each tool's skills directory - the installer links individual skills under
~/.claude/skills/,~/.gemini/skills/,~/.codex/skills/, and~/.copilot/skills/ - canonical paths are managed through
mise/conf.d/env.toml - custom skills should respond in the user's request language unless the requested artifact has an explicit language requirement such as English commit messages
Prepare the Bun global environment with:
mise run install-bunThis links the managed Bun global directory and installs dependencies from bun/package.json.
Install tracked Homebrew packages:
brew bundle --file=homebrew/BrewfileUpdate the tracked Brewfile from the current machine state:
brew bundle dump --file=homebrew/Brewfile --forceThis repository uses mise as the main task entrypoint and discovery interface.
mise run installperforms the standard local setupmise run formatformats tracked source filesmise run check-pre-commitruns the full repository checks- published commands in
scripts/global/are also exposed through generatedmisetask wrappers
Repository-wide design and policy documents:
- docs/index.md
- docs/architecture.md
- docs/command-model.md
- docs/abbreviation-policy.md
- docs/operations.md
Subsystem-local policies: