Agent-first dotfiles for macOS, Linux desktops, and SSH servers. Boring defaults for coding agents, beautiful terminals for humans.
- Quick Start
- What You Get
- Comparison
- Why Agent-First?
- Profiles
- Neovim, Shell & Tools
- Update & Maintain
- Acknowledgments
- License
curl -fsSL https://raw.githubusercontent.com/alohays/dotfiles/main/bootstrap/install.sh | sh -s --This clones the repo into ~/.dotfiles, auto-detects your environment
(macOS desktop / Linux desktop / SSH server), applies the matching profile,
installs default agent tools, and backs up existing configs with timestamps.
If an older dotfiles checkout already exists, the installer detects it,
asks once before replacing, and creates a timestamped backup.
From a local clone:
git clone git@github.com:alohays/dotfiles.git ~/.dotfiles
cd ~/.dotfiles
./bootstrap/install.shRequirements:
- macOS 10.15+ or Linux (Debian/Ubuntu)
- Python 3.11+
- git
Already know you want everything? Rich profile, all packages, all tools:
dotfiles --yolo installAuto-detects your OS, applies the rich profile (macos-desktop-rich or
linux-desktop-rich), installs all package tiers and all 10 agent tools,
and auto-approves prompts. SSH servers stay on the ssh-server profile.
Override individual phases with --skip-tools, --skip-apply, or
--profile <name>. Preview what would happen with --dry-run.
The base install gives you a clean, agent-friendly environment. If you also want Powerlevel10k prompts, syntax highlighting, and colorized CLI tools, apply a rich profile and install the extras:
dotfiles apply --profile macos-desktop-rich # or linux-desktop-rich
dotfiles tools install powerlevel10k
dotfiles tools install fast-syntax-highlighting
dotfiles tools install fzf-git
dotfiles packages --set visualSee docs/visual.md for the full visual guide, plugin categories, font guidance, and keybinding reference.
| Feature | Details | |
|---|---|---|
| 🚀 | One-command bootstrap | Auto-detects macOS, Linux, or SSH — applies the right profile |
| 🔥 | Yolo mode | One command: rich profile + all packages + all tools |
| 🧠 | Agent-first defaults | Stock keymaps, no aliases, no traps — agents just work |
| 🎨 | 37 Neovim plugins | Lazy-loaded, zero custom keybindings, LSP + completion + treesitter |
| ⚡ | Powerlevel10k prompt | Instant prompt, cloud segments (AWS/GCloud/Azure), transient mode |
| 📦 | 10 installable tools | RTK, agent-browser, slack-cli, googleworkspace-cli, fzf-git, and more |
| 🛡️ | Timestamped backups | Existing configs are backed up before any replacement |
| 🧪 | 78 isolated tests | Temp-HOME sandboxing — never touches your live dotfiles |
| 🖌️ | Colored CLI | ASCII banner with status indicators during install/update |
| 🔒 | Secrets stay local | Git identity, shell overrides, SSH config — never committed |
| 🔄 | Auto-migration | Recovers legacy zsh configs into local overlays automatically |
| alohays/dotfiles | chezmoi | yadm | GNU stow | |
|---|---|---|---|---|
| Agent-first defaults | ✅ | ❌ | ❌ | ❌ |
| Profile-based configs | 6 profiles | Templates | ❌ | ❌ |
| One-command bootstrap | ✅ | ✅ | ✅ | ❌ |
| Auto environment detection | ✅ | ❌ | ❌ | ❌ |
| Neovim plugin layer | 37 plugins | N/A | N/A | N/A |
| Agent tool installer | 10 tools | ❌ | ❌ | ❌ |
| Auto-migration from legacy | ✅ | ❌ | ❌ | ❌ |
| Local override pattern | Built-in | Templates | Alt files | Manual |
| Interactive git identity setup | ✅ | ❌ | ❌ | ❌ |
| Timestamped backups | ✅ | ❌ | ❌ | ❌ |
| Isolated test suite | 78 tests | ✅ | ❌ | ❌ |
Pre-AI dotfiles were optimized for one expert human who already knew every alias, keybinding, and shell hook by heart. Coding agents like Claude Code, Codex CLI, and Gemini CLI do not share that muscle memory.
Command-shadowing aliases make agents guess what ls actually does.
Custom keymaps force agents to discover non-standard bindings.
Shell traps and hidden hooks consume tokens explaining state that
upstream defaults would have made obvious.
This repo keeps the environment predictable and token-efficient for agents:
- Default CLI behavior instead of surprising aliases
- Stock tmux prefix and keymap
- No shell, terminal, or editor shortcut remaps
- Standard file locations and a predictable bootstrap/apply flow
- Proven agent-helpful tools like RTK installed by default
For humans, nothing is sacrificed:
- A comfortable, beautiful TUI-first experience
- Optional visual polish instead of mandatory theme stacks
- One-command bootstrap plus easy re-apply and update flows
- Local overrides and secrets kept out of the tracked repo
| Profile | Extends | Modules | Environment |
|---|---|---|---|
base |
— | core | Shared baseline |
macos-desktop |
base | + tmux, nvim, visual | macOS workstation |
macos-desktop-rich |
macos-desktop | + terminal, prompt | Full visual polish |
linux-desktop |
base | + tmux, nvim, visual | Linux workstation |
linux-desktop-rich |
linux-desktop | + terminal, prompt | Full visual polish |
ssh-server |
base | + ssh-server, tmux | Remote / no-sudo |
Profiles are auto-detected on install based on OS and environment. Override
with dotfiles apply --profile <name>. Each profile inherits from its
parent and adds modules incrementally, so macos-desktop-rich includes
everything in macos-desktop plus terminal emulator presets (WezTerm,
Alacritty) and the Powerlevel10k prompt layer. The ssh-server profile
skips desktop modules entirely and focuses on a lightweight tmux + core
setup suitable for remote machines without sudo.
37 lazy-loaded plugins with zero custom keybindings, using stock Neovim 0.10+ keys. All plugins are managed by lazy.nvim with automatic treesitter parser installation for 21 languages.
| Category | Highlights |
|---|---|
| Colorscheme | kanagawa (dragon theme) |
| Git | gitsigns, diffview, git-messenger |
| LSP | lspconfig, mason, mason-lspconfig, nvim-cmp, lsp_signature |
| UI | neo-tree, telescope, lualine (+ navic breadcrumbs), image.nvim |
| Treesitter | nvim-treesitter with 21 auto-installed language parsers |
| Editor | indent-blankline, nvim-colorizer, todo-comments, which-key |
| Notifications | nvim-notify, noice, dressing, fidget |
| Diagnostics | trouble |
| Markdown | render-markdown |
| AI | claudecode.nvim |
Standard keybindings are all Neovim 0.10+ built-ins: gd (go to
definition), gr (references), K (hover), [d/]d (diagnostics),
<C-n>/<C-p> (completion navigation), <C-y> (accept), <C-e>
(dismiss).
Telescope commands: :Telescope find_files, :Telescope live_grep,
:Telescope buffers. File explorer: :Neotree toggle left. Diagnostics:
:Trouble diagnostics. Diff: :DiffviewOpen, :DiffviewFileHistory.
See docs/visual.md for the full plugin list and keybinding reference.
Powerlevel10k with instant prompt, transient mode, and cloud segments for AWS, GCloud, and Azure. The prompt shows os_icon, directory, and git status on the left; execution time, background jobs, virtualenv, pyenv, node version, kubecontext, and clock on the right.
FZF keybindings are enabled in rich profiles:
- Ctrl-T -- file search with bat preview (falls back to cat)
- Ctrl-R -- history search
- Alt-C -- directory cd with eza tree preview (falls back to tree/ls)
fast-syntax-highlighting provides an upgrade path over standard zsh-syntax-highlighting. When installed, it is detected and activated automatically.
Shell startup is split into an explicit zsh/ tree (zshenv, zprofile,
zshrc, zsh.d/) that keeps the layout visible in the repo while thin
wrappers in HOME delegate into ~/.dotfiles/zsh/.
Toolchain auto-discovery covers Volta, NVM, FNM, pyenv, Conda, asdf,
nodenv, and mise paths so managed shell startup finds your tools without
manual PATH configuration. If only python3/pip3 exist, interactive
shells expose python/pip aliases automatically.
| Tool | Description | Install |
|---|---|---|
| rtk | AI-powered context for agents | dotfiles tools install rtk |
| nvim-plugins | Bootstrap lazy.nvim + treesitter | dotfiles tools install nvim-plugins |
| googleworkspace-cli | Google Workspace from terminal | dotfiles tools install googleworkspace-cli |
| agent-browser | Headless browser for agents | dotfiles tools install agent-browser |
| slack-cli | Slack from terminal | dotfiles tools install slack-cli |
| powerlevel10k | Rich zsh prompt theme | dotfiles tools install powerlevel10k |
| fast-syntax-highlighting | Enhanced zsh syntax coloring | dotfiles tools install fast-syntax-highlighting |
| fzf-git | Git-aware FZF pickers | dotfiles tools install fzf-git |
| zsh-plugins | Autosuggestions + completions | dotfiles tools install zsh-plugins |
| tmux-resurrect | Session persistence | dotfiles tools install tmux-resurrect |
List all tools with dotfiles tools list. Preview what an install does
before running it with dotfiles tools plan <name>.
Install all tools at once with dotfiles tools install --all. Preview
all plans with dotfiles tools plan --all. Tools that need authentication
(rtk, googleworkspace-cli, slack-cli) show their auth commands after
install. If a tool fails, installation continues for the rest and reports
a summary at the end.
| Tier | Contents | Install |
|---|---|---|
default |
git, neovim, zsh, tmux | dotfiles packages --set default |
agents |
ripgrep, fd, jq, fzf, git-delta | dotfiles packages --set agents |
visual |
eza, bat, tree | dotfiles packages --set visual |
Preview what a tier installs with dotfiles packages --set <tier> --print-plan.
Install all tiers at once with dotfiles packages --all.
dotfiles update # sync to origin/main, re-apply, re-check tools
dotfiles update --fast # sync + re-apply without tool checks
dotfiles apply # re-apply current profileLocal checkout changes are auto-stashed during update and preserved in
git stash for manual review. Auto-stashed changes can be inspected with
git stash list and restored with git stash pop. For branch or remote
overrides, or to disable auto-stashing, see dotfiles update --help.
Host-specific data stays outside the repo in local overlay files. See docs/local-overrides.md for local customization patterns including git identity, machine-local shell hooks, SSH host overrides, and secret management.
Architecture and contribution guidelines are documented in CONTRIBUTING.md.
A sincere shoutout to wookayin/dotfiles, the long-time inspiration behind much of this repo's structure, shell startup design, and visual philosophy. That style of thoughtful, deeply polished, personal dotfiles remains something to admire and aspire to.