macOS dev environment bootstrap — Homebrew, Zsh (uv/fnm/Go), Neovim, tmux, Git+gh, Ghostty, Docker (OrbStack), proxies (Hysteria2 / Shadowsocks / sing-box, client + server), system prefs. Modular, multi-select.

GitHub stars
9

Install

/plugin install setup@cc-plugins

Run it inside Claude Code after adding the marketplace with /plugin marketplace add yanmxa/cc-plugins.

Contents

Discovered from source

Skills 10

Setup Docker (via OrbStack)

Install OrbStack as the macOS Docker runtime. It's the fastest option on Apple Silicon, free for personal use, and ships with everything you need.

Why OrbStack

OrbStackDocker DesktopColima
Startup2-3s30-60s5-10s
Memory at idle<1GB4-8GB1-2GB
File mount speed5-10× fasterSlowSlow
GUIMenu bar icon onlyHeavy dashboardNone
Personal useFreeFreeFree
Kubernetes built-in✅ one toggle✅ but slower❌ separate setup
Linux VMs included✅❌❌

OrbStack on Apple Silicon is significantly faster than the alternatives — that's the main reason to pick it.

What gets installed

Just one cask: orbstack. It bundles:

  • Docker daemon + CLI
  • docker compose
  • docker buildx (multi-arch)
  • Kubernetes (toggle in settings)
  • Linux VM support (orb create)

No need to install docker, docker-compose, docker-buildx separately — they all come with it.

Quick setup

bash ${CLAUDE_SKILL_DIR}/scripts/setup-docker.sh

The script:

  1. Installs orbstack via Homebrew cask
  2. Opens the app once to trigger the setup wizard
  3. Tells you how to verify

After install, OrbStack auto-starts when you run any docker command — no manual colima start needed.

Verify

docker run hello-world
docker compose version
docker buildx version

Daily use

# Just use docker normally — OrbStack handles starting the VM
docker ps
docker compose up
docker build .

# CLI controls (optional — menu bar icon does the same)
orb status            # show VM state
orb stop              # stop VM (frees ~1GB RAM)
orb start             # start VM (rarely needed — auto-starts on docker call)
orb delete            # nuke the VM and start over

Multi-architecture builds

OrbStack is arm64 native on Apple Silicon. To build/run x86 images:

docker run --platform linux/amd64 ubuntu:22.04
docker buildx build --platform linux/amd64,linux/arm64 -t myimg .

Kubernetes (optional)

Open OrbStack → Settings → Kubernetes → toggle on. kubectl will work against the cluster automatically:

kubectl get nodes
kubectl run nginx --image=nginx

Linux VMs (bonus)

OrbStack can run lightweight Linux VMs side-by-side with Docker:

orb create ubuntu my-vm    # creates an Ubuntu VM
orb shell my-vm             # SSH into it (just-works, file sharing pre-mounted)

Faster than UTM/Parallels for "just give me a Linux shell" use cases.

License note

OrbStack is free for personal use and free for non-commercial use. Companies pay $8/user/month. For an individual developer working on personal projects or contributing to OSS, free.

Useful aliases (already in setup-zsh)

alias d='docker'
alias dc='docker compose'

Setup Ghostty

Set up a fully configured Ghostty terminal on macOS with MesloLGL Nerd Font, split pane keybindings, and an optimized config.

What gets installed

  • Ghostty (via Homebrew cask if not present)
  • MesloLGL Nerd Font (downloaded from nerd-fonts releases if not found)
  • Optimized config with these highlights:
    • Font: MesloLGL Nerd Font, size 14
    • Theme: Builtin Light
    • Split panes: Cmd+D (right), Cmd+Shift+D (down)
    • Navigate splits: Cmd+Alt+Arrow
    • Resize splits: Cmd+Ctrl+Arrow
    • Global quick terminal: `Ctrl+``
    • Copy-on-select, 50k scrollback, cursor block (no blink)
    • macOS tabs titlebar style

Quick setup

Run the bundled script which handles everything automatically — checking Ghostty, installing the font, backing up existing config, and deploying the optimized config:

bash ${CLAUDE_SKILL_DIR}/scripts/setup-ghostty.sh

The script backs up any existing ~/.config/ghostty/config before overwriting.

Manual / selective setup

If the user only wants part of the config, read the bundled config at ${CLAUDE_SKILL_DIR}/scripts/config and apply only the relevant sections to their existing config.

Key bindings reference

ActionBinding
Split rightCmd + D
Split downCmd + Shift + D
Close splitCmd + W
Navigate splitsCmd + Alt + Arrow
Resize splitsCmd + Ctrl + Arrow
Equalize splitsCmd + Shift + =
Increase fontCmd + =
Decrease fontCmd + -
Reset fontCmd + 0
Quick terminal`Ctrl + `` (global)

Customization

After setup, edit ~/.config/ghostty/config directly. Common customizations:

  • Theme: Change theme to any built-in theme (ghostty +list-themes to see all)
  • Font: Change font-family and font-size
  • Padding: Adjust window-padding-x and window-padding-y
  • Keybindings: Add or modify keybind lines

Setup Git + GitHub CLI

Install git and GitHub CLI, then configure git for a new machine: identity, editor, pull/push defaults, aliases, credential helper, SSH key, gh auth, and global gitignore.

What gets done (in order)

  1. Install git via Homebrew (skips system git for newer version)
  2. Configure identity — user.name, user.email (prompts if not given)
  3. Set defaults — pull.rebase, push.autoSetupRemote, init.defaultBranch=main
  4. Set credential helper — osxkeychain (macOS only)
  5. Define aliases — lg, st, co, br, unstage, last, aliases
  6. Create global gitignore — ~/.gitignore_global (.env, *.pem, *_rsa, etc.)
  7. Generate SSH key — ~/.ssh/id_ed25519 (if not present) + add to ssh-agent
  8. Install gh CLI via Homebrew
  9. Run gh auth login — interactive (uploads SSH key to GitHub automatically)

Quick setup

bash ${CLAUDE_SKILL_DIR}/scripts/setup-git.sh

# Or with identity pre-set:
bash ${CLAUDE_SKILL_DIR}/scripts/setup-git.sh "Your Name" "you@example.com"

────────────────────────────────────────────────────────────────────

How GitHub authentication works (the two-layer model)

────────────────────────────────────────────────────────────────────

There are two independent credentials between your machine and GitHub. You generally want both:

LayerWhat it isUsed for
SSH key~/.ssh/id_ed25519 keypairgit clone git@github.com:..., git push, git pull
OAuth tokenStored by gh in macOS Keychaingh pr create, gh repo view, GitHub API calls, releases

They serve different purposes — SSH for git operations over the SSH transport, OAuth for the gh CLI which talks to the REST/GraphQL API.

The neat trick: gh auth login does both

When you run gh auth login and pick GitHub.com → SSH → upload key → browser, gh:

  1. Opens a browser → you authorize via OAuth → token stored in Keychain
  2. Uploads your ~/.ssh/id_ed25519.pub to GitHub for you — no manual copy-paste into web settings

After that, both git push and gh pr create work.

What setup-git.sh does on auth

1. SSH key exists?  → no  → generate id_ed25519 with email comment
                    → yes → keep
2. gh auth status?  → ok  → skip
                    → fail → run `gh auth login` interactively

When gh auth login runs, make these choices:

? What account do you want to log into?  → GitHub.com
? What is your preferred protocol?        → SSH
? Generate a new SSH key to add?          → No, use existing
? Choose SSH key                          → ~/.ssh/id_ed25519.pub  ← the one we just made
? Title for SSH key                       → <hostname-of-your-mac>
? How would you like to authenticate?     → Login with a web browser

Browser opens → enter the one-time code → done. SSH key gets uploaded automatically.

After setup — verify

# git basics
git config --list --global

# Test SSH connection to GitHub
ssh -T git@github.com
# Expected: "Hi <username>! You've successfully authenticated..."

# Test gh
gh auth status
# Expected: "Logged in to github.com account <username>"

# Both should agree on your username
gh api user --jq .login

Git aliases reference

AliasExpands to
git lgPretty one-line log with graph
git ststatus -sb
git cocheckout
git brbranch
git unstagereset HEAD --
git lastlog -1 HEAD
git aliasesList all defined aliases

Troubleshooting

SymptomLikely causeFix
Permission denied (publickey) on pushSSH key not on GitHubgh ssh-key add ~/.ssh/id_ed25519.pub
gh: command not found after installHomebrew bin not in PATHRestart shell: source ~/.zshrc
git push works but gh says "not logged in"OAuth missing, only SSH set upRe-run gh auth login
Pushed to wrong accountMultiple identities, gh defaultedgh auth switch or gh auth login --hostname github.com
Cloning into ... hangsFirst-time host key promptssh -T git@github.com once to accept
Need to use a 2nd GitHub accountSingle SSH key can't auth as two usersAdd per-host SSH config in ~/.ssh/config (see below)

Multiple GitHub accounts (advanced)

If you need a separate GitHub identity (e.g. work + personal), generate a 2nd key and add to ~/.ssh/config:

# ~/.ssh/config
Host github.com
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519

Host github-work
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519_work

Then clone with git@github-work:org/repo.git for the alt account.

Setup Hysteria 2

Three things this skill does:

  • Client — install + configure hysteria on THIS Mac, with shell aliases to control it
  • Server — SSH-deploy hysteria to a Linux VPS (binary + self-signed cert + systemd + firewall)
  • Diagnose — check both ends and fix common issues (port blocked by GFW, stale process, etc.)

Step 0 — ask

Always ask first: client, server, or diagnose?

Client

One command:

bash ${CLAUDE_SKILL_DIR}/scripts/setup-hysteria2.sh --service   # or --no-service for manual

This installs hysteria (Homebrew), deploys ~/.config/hysteria/config.yaml + aliases.sh, optionally creates a launchd plist. Never overwrites an existing config.yaml.

After setup, fill in server, auth, tls.pinSHA256 in config.yaml, then:

source ~/.zshrc
hy2start && hy2on

Architecture:

hy2on → hysteria(:1080 + :1081) → QUIC → 服务器
         SOCKS5       HTTP
端口进程说明
:1081hysteriaHTTP 代理,hy2on 的 http/https 指向这里
:1080hysteriaSOCKS5 代理,hy2on 的 all_proxy 指向这里

Commands

CommandAction
hy2start / hy2stop / hy2restartService control (launchd or manual)
hy2statusPID + mode + listening ports
hy2log / hy2logsTail / last 50 lines of logs
hy2editEdit config.yaml + auto-restart
hy2diagFull diagnostic: local + remote (SSH) + proxy test
hy2restart-allRestart both server (SSH) and client
hy2helpFull command reference
hy2on / hy2off / hy2proxystatusProxy env vars → HTTP_PROXY=http://:1081, ALL_PROXY=socks5://:1081
hy2ipCompare direct vs. proxy egress IP
hy2speedTest proxy download speed
gohy2 / stophy2Start+proxy+test / Stop+unset proxy

SSH config (for hy2diag / hy2restart-all)

Env varDefault
HY2_SSH_HOSTauto from config.yaml server field
HY2_SSH_USERroot
HY2_SSH_PORT22
HY2_SSH_KEY(optional) path to private key
HY2_SSH_PASS(optional) password (needs expect or sshpass)

Default ports: SOCKS5 :1080, HTTP :1081.

Server

bash ${CLAUDE_SKILL_DIR}/scripts/setup-hysteria2.sh --server --host <ip> \
  [--ssh-user root] [--ssh-port 22] [--ssh-key <path>] [--server-port 443] [--sni bing.com]

Requires key-based SSH (ssh-copy-id first). Installs hysteria, generates self-signed cert, writes /etc/hysteria/config.yaml, enables systemd, opens firewall. Prints ready-to-paste client credentials.

Diagnose

When something's wrong, run hy2diag (after source ~/.zshrc). It checks:

  • Local client: PID, ports, version, recent errors
  • Network: UDP reachability to server
  • Remote server (via SSH): systemd, version, firewall, logs, outbound test
  • Proxy: live CONNECT test

For SSH to server, set one of: HY2_SSH_KEY (key path), HY2_SSH_PASS (password, needs expect or sshpass). Server address is read from config.yaml automatically.

hy2restart-all restarts both server (SSH) and client in one go.

Common fixes

SymptomLikely causeFix
connected to server then 30s timeoutPort blocked by GFW DPIChange to non-443 port (e.g. 8443)
Client stuck at "client mode"v2.12.x macOS binary bugPin to v2.8.2: download to ~/.local/bin/hysteria
Server outbound TCP all timeouthysteria process stale >2wsystemctl restart hysteria-server

Setup macOS

Bootstrap a macOS development environment with a multi-select component picker. Each component is also independently runnable from its own skill.

Components

IDWhat it installs
brewHomebrew (required by everything else)
zshOh My Zsh + plugins + powerlevel10k + uv + fnm + Go + self-contained .zshrc + ~/.env template
vimNeovim with full Lua config
tmuxtmux + TPM + Dracula theme + optimized keybindings
gitGit global config + GitHub CLI (gh auth) + SSH key + global gitignore
ghosttyGhostty terminal + MesloLGL Nerd Font + optimized config
hysteria2Hysteria 2 proxy client + launchd service + hy2start/hy2stop/hy2log shortcuts
shadowsocksShadowsocks client (shadowsocks-rust sslocal) + ssstart/ssstop/sslog
sing-boxsing-box client — one client for both Hysteria2 + Shadowsocks + sbstart/sbnode
prefsmacOS system preferences (4 dev-friendly defaults — see below)

How to invoke this skill

When invoked through Claude (recommended)

Always use AskUserQuestion to let the user multi-select components first. Then call the script with --components <ids>.

Suggested AskUserQuestion call:

  • question: "Which components do you want to install?"
  • multiSelect: true
  • options: one per component above, with the label as id — short description and value as the bare id

Defaults to recommend pre-checked: brew, zsh, git. Other components depend on user preference (proxy is regional, ghostty is a terminal choice, etc.).

After the user picks, run:

bash ${CLAUDE_SKILL_DIR}/scripts/setup-macos.sh --components <comma-separated-ids>

Direct CLI invocation (no Claude)

# Interactive Y/n picker for each component
bash ${CLAUDE_SKILL_DIR}/scripts/setup-macos.sh

# Explicit selection
bash ${CLAUDE_SKILL_DIR}/scripts/setup-macos.sh --components zsh,git,hysteria2

# Run everything
bash ${CLAUDE_SKILL_DIR}/scripts/setup-macos.sh --all

# Show available components
bash ${CLAUDE_SKILL_DIR}/scripts/setup-macos.sh --list

Language runtimes installed by zsh component

LanguageToolIsolation
PythonuvUV_PYTHON_PREFERENCE=only-managed; pip install blocked globally
Node.jsfnmauto-switches version via .node-version / .nvmrc
GoHomebrewgo.mod per-project isolation; binaries → $GOPATH/bin

Three-tier shell config layout (set up by zsh component)

FilePurposeTracked?
~/.zshrcGeneric config — plugins, PATH, runtimes, aliases✅ tracked
~/.envEnvironment variables / API keys (auto-exported)❌ chmod 600
~/.zshrc.localMachine-specific aliases / functions❌

What prefs actually changes (only 4 settings)

Intentionally minimal — only universally useful for developers, no personal-preference items:

SettingWhy it's universal
Finder.AppleShowAllExtensions = trueSee full filenames; avoid ambiguous names
Dock.show-recents = falseThe "recent apps" section is rarely useful, just clutter
screencapture.location = ~/Desktop/screenshots/Stop screenshots from cluttering the Desktop
DSDontWriteNetworkStores = trueDon't pollute shared SMB / network drives with .DS_Store

Things like Dock auto-hide, tap-to-click, fast key repeat, hidden files in Finder are personal preferences and are not changed.

Re-run individual components

Each component is also a standalone skill:

bash ~/.claude/plugins/setup/skills/setup-zsh/scripts/setup-zsh.sh
bash ~/.claude/plugins/setup/skills/setup-vim/scripts/setup-vim.sh
bash ~/.claude/plugins/setup/skills/setup-tmux/scripts/setup-tmux.sh
bash ~/.claude/plugins/setup/skills/setup-git/scripts/setup-git.sh
bash ~/.claude/plugins/setup/skills/setup-ghostty/scripts/setup-ghostty.sh
bash ~/.claude/plugins/setup/skills/setup-hysteria2/scripts/setup-hysteria2.sh
bash ~/.claude/plugins/setup/skills/setup-shadowsocks/scripts/setup-shadowsocks.sh
bash ~/.claude/plugins/setup/skills/setup-sing-box/scripts/setup-sing-box.sh

The proxy skills (hysteria2, shadowsocks) also have a --server mode that SSH-deploys the server side to a Linux VPS — not part of this macOS picker. See each skill's skill.md.

After setup

  1. Restart terminal (or source ~/.zshrc)
  2. Run p10k configure for the prompt
  3. In tmux: prefix + I to install TPM plugins
  4. Edit ~/.env to add API keys / secrets
  5. If hysteria2 was installed: edit ~/.config/hysteria/config.yaml, then hy2start

Setup Shadowsocks

Three things this skill does:

  • Client — install + configure Shadowsocks on THIS Mac (sslocal + sing-box HTTP layer)
  • Server — SSH-deploy to a Linux VPS (ssserver + systemd + firewall)
  • Diagnose — check both ends, restart, fix issues

Step 0 — ask

Always ask first: client, server, or diagnose?

Client

One command:

bash ${CLAUDE_SKILL_DIR}/scripts/setup-shadowsocks.sh --service   # or --no-service for manual

Installs shadowsocks-rust (Homebrew), deploys ~/.config/shadowsocks/config.json + aliases.sh + http-proxy.json (sing-box mixed port for HTTP), optionally creates a launchd plist. Never overwrites an existing config.json.

After setup, fill in server and password, then:

source ~/.zshrc
ssstart && sson

Architecture:

sson → :1082(sing-box) → :1084(sslocal) → TCP → 服务器
       对外统一口          内部 SOCKS5
端口进程说明
:1082sing-box对外统一口,sson 指向这里
:1084sslocal内部 SOCKS5,自动管理

Commands

CommandAction
ssstart / ssstop / ssrestartService control (launchd or manual)
ssstatusPID + mode + SOCKS5:1084 + HTTP:1082
sslog / sslogsTail / last 50 lines of logs
sseditEdit config.json + auto-restart
sshelpFull command reference
sson / ssoff / ssproxystatusProxy env vars (HTTP_PROXY=http://:1082, ALL_PROXY=socks5://:1082)
ssipCompare direct vs. proxy egress IP
ssspeedTest proxy download speed
goss / stopssStart+proxy+IP / Stop+unproxy

Default: SOCKS5 :1084 (sslocal), HTTP+SOCKS5 :1082 (sing-box).

Server

bash ${CLAUDE_SKILL_DIR}/scripts/setup-shadowsocks.sh --server --host <ip> \
  [--ssh-user root] [--ssh-port 22] [--ssh-key <path>] [--server-port 8388] [--method aes-256-gcm]

Requires key-based SSH (ssh-copy-id first). Installs shadowsocks-rust, writes /etc/shadowsocks-rust/config.json with server-generated password, enables systemd, opens firewall. Prints ready-to-paste client config.

Diagnose

SS is simple — TCP-based, no complex protocol issues. Check:

ssstatus         # local: running? ports listening?
sslogs           # any errors?
nc -zv <server> 8388   # TCP reachable?

Common fixes

SymptomLikely causeFix
Connection refusedsslocal not runningssstart
HTTP tools don't worksing-box layer downssrestart (restarts both)
timeoutGFW blocked port/IPChange server port or switch to hy2
Method not supportedOld Python ss clientUse shadowsocks-rust (Homebrew)

Setup sing-box Client

Install and configure a sing-box client on macOS. One local proxy port fronts both a Hysteria2 and a Shadowsocks outbound — switch with sbnode, or let auto pick the fastest. Optionally runs as a launchd background service. Edit one JSON, run one command.

It coexists with setup-hysteria2: sing-box defaults to port 1082, hysteria2 uses 1080/1081, so both can run at once. (sing-box already includes a Hysteria2 outbound, so most people run either sing-box or the standalone hysteria2 client — not both.)

File layout

~/.config/sing-box/
  config.json                        ← edit this (chmod 600, contains your auth)
  aliases.sh                         ← shell shortcuts
  sing-box.log / sing-box.err.log    ← runtime logs
~/Library/LaunchAgents/
  com.sing-box.client.plist          ← runs `sing-box run -c config.json`
                                       (ONLY in service mode — omitted in manual mode)

3–4 files (the plist exists only when you choose the launchd service), no wrappers, no env injection.

Quick setup

Step 1 — ask the user how it should run. Before running the script, use AskUserQuestion to let the user choose the startup mode:

  • Auto-start service (launchd) — starts automatically on login and is kept alive if it crashes. Best for a daily-driver machine. → pass --service
  • Manual only — no launchd; the user starts/stops it themselves with sbstart / sbstop. Best for a shared/temporary machine or when the user wants full control. → pass --no-service

Recommend Auto-start service as the default.

Step 2 — run the script with the chosen flag:

bash ${CLAUDE_SKILL_DIR}/scripts/setup-sing-box.sh --service      # or --no-service

If run non-interactively (e.g. orchestrated by setup-macos), the flag can be omitted and it defaults to --service.

The script:

  • Installs sing-box via Homebrew
  • Deploys config.json template (preserves existing — never overwrites real secrets)
  • Deploys aliases.sh
  • Generates the launchd plist only in --service mode (in --no-service mode it removes any pre-existing plist)
  • Adds source aliases.sh to ~/.zshrc.local

After setup — fill in 3 fields

sbedit           # opens config.json in $EDITOR, runs `sing-box check`, auto-restarts on save

Replace these placeholders (Hy2 and SS may point at different hosts — edit each server if so):

"server": "SERVER_HOST"        // both the hy2 and ss outbound
"password": "HY2_AUTH_TOKEN"   // in the hysteria2 outbound
"password": "SS_PASSWORD"      // in the shadowsocks outbound

Then:

source ~/.zshrc
sbstart          # start (validates config first)
sbstatus         # verify — shows current outbound + listening port
sbon             # set http/https/all_proxy → 127.0.0.1:1082 in this shell

Shortcut commands

Service control

These auto-detect the mode: with a plist they drive launchd; without one they start/stop the process directly.

CommandAction
sbstartStart (runs sing-box check first; launchd service or background process)
sbstopStop (unload service if present, then kill the process)
sbrestartRestart (launchctl kickstart -k, or stop+start in manual mode)
sbstatusPID + mode + current outbound + listening port
sblogTail stdout + stderr (Ctrl+C to exit)
sblogsLast 50 lines of logs
sbeditEdit config.json + validate + auto-restart
sbhelpFull command reference

Outbound switching

CommandAction
sbnodePrint the current default outbound
sbnode ss / sbnode hy2 / sbnode autoSwitch default outbound + restart (auto = url-test fastest)

Proxy control (current shell only)

sb-prefixed so they don't clash with setup-hysteria2's proxyon/proxyoff.

CommandAction
sbonSet http_proxy / https_proxy / all_proxy → sing-box mixed port
sboffUnset proxy env vars
sbproxystatusShow current proxy state
sbipCompare direct vs. proxy egress IP (labels current outbound)
sbspeedTest proxy download speed

Combo

CommandAction
gosbsbstart + sbon + sbip
stopsbsbstop + sboff

Default port

Mixed (SOCKS5 + HTTP on one port): 127.0.0.1:1082. To change, edit listen_port in config.json AND SB_MIXED_PORT in aliases.sh.

Security

  • config.json is chmod 600 — only your user can read it
  • The setup script never overwrites an existing config.json (keeps your secrets safe across re-runs)
  • aliases.sh and the plist ARE overwritten on re-run — they're managed code, not user data
  • sbstart / sbedit run sing-box check before (re)starting, so a bad edit never silently breaks the service
  • The launchd service (when used) runs as your user, not root
  • The Hysteria2 outbound uses tls.insecure: true to match a self-signed server (as deployed by setup-hysteria2 --server). sing-box has no SHA256 cert-pinning option, so pinning is not enforced client-side — the QUIC password still authenticates the server.

Related

  • setup-hysteria2 — standalone Hysteria2 client, and the server side (--server) that this client's hy2 outbound connects to
  • setup-shadowsocks — the Shadowsocks server (--server) that this client's ss outbound connects to

Setup tmux

Set up a fully configured tmux environment on macOS with an optimized configuration, Dracula theme, and essential plugins.

What gets installed

  • tmux (via Homebrew if not present)
  • TPM (Tmux Plugin Manager)
  • Plugins: vim-tmux-navigator, Dracula theme (cpu/ram/network status)
  • Optimized config with these highlights:
    • Prefix: Ctrl-a (instead of default Ctrl-b)
    • Pane splitting: prefix + \ (horizontal), prefix + - (vertical)
    • Vim-style pane resize: prefix + h/j/k/l
    • Alt+arrow pane switching (no prefix needed)
    • Native copy/paste with pbcopy (mouse select, double/triple-click)
    • Heavy pane borders with green active border
    • 50,000 lines history, auto-renumber windows
    • Ghostty hyperlinks passthrough, OSC 52 clipboard

Quick setup

Run the bundled script which handles everything automatically — installing tmux, backing up any existing config, deploying the optimized config, installing TPM and plugins:

bash ${CLAUDE_SKILL_DIR}/scripts/setup-tmux.sh

The script backs up any existing ~/.tmux.conf before overwriting.

Manual / selective setup

If the user only wants part of the config (e.g., just the keybindings or just the theme), read the bundled config at ${CLAUDE_SKILL_DIR}/scripts/tmux.conf and apply only the relevant sections to their existing config.

Key bindings reference

ActionBinding
PrefixCtrl-a
Split horizontalprefix + \
Split verticalprefix + -
Resize paneprefix + h/j/k/l
Zoom paneprefix + m
Switch paneAlt + arrow keys
Reload configprefix + r
Pasteprefix + p
Create named windowprefix + c

Customization

After setup, the user can modify ~/.tmux.conf directly. The config is structured with clear section comments. Common customizations:

  • Dracula plugins: Change @dracula-plugins to add/remove status bar widgets (battery, git, gpu-usage, weather, time, etc.)
  • Pane borders: Change pane-border-lines to simple, double, or number
  • Active border color: Modify pane-active-border-style (current: bright green)

Setup Vim / Neovim

Install Neovim and deploy kickstart.nvim as the default config — the official starting-point recommended by the Neovim community. Single-file init.lua you can read, understand, and customize.

What gets installed

Neovim (default)

  • Neovim via Homebrew
  • ripgrep + fd (used by Telescope and treesitter for fast search)
  • kickstart.nvim cloned to ~/.config/nvim/ (.git removed so it's yours to edit)

kickstart.nvim ships with:

  • LSP setup (Mason for managing language servers)
  • Treesitter (syntax + indentation)
  • Telescope (fuzzy finder)
  • nvim-cmp (completion)
  • which-key (keybinding hints)
  • gitsigns (git change indicators)
  • A clean colorscheme (tokyonight)

All in one readable init.lua file.

Vim (--vim-only fallback)

  • vim-plug plugin manager (official curl install)
  • Bundled vimrc with molokai theme, airline, polyglot

Quick setup

bash ${CLAUDE_SKILL_DIR}/scripts/setup-vim.sh

Modes:

FlagBehavior
(default)Install Neovim + kickstart.nvim
--neovim-onlySame as default
--vim-onlyInstall classic Vim with vim-plug only

The script backs up any existing ~/.config/nvim/ or ~/.vimrc before overwriting.

After install

Open nvim once — lazy.nvim auto-installs all plugins. To customize:

$EDITOR ~/.config/nvim/init.lua

The kickstart.nvim docs walk you through every section:

Why kickstart.nvim and not LazyVim/NvChad/...

  • Single file — read the whole config in one sitting
  • No abstractions — what you see is what runs
  • Officially blessed by the neovim core team
  • Easy to delete — if you outgrow it, you understand exactly what to keep

LazyVim / NvChad are great but opinionated and harder to debug if something breaks.

Switching to a different distribution

rm -rf ~/.config/nvim
git clone https://github.com/LazyVim/starter ~/.config/nvim       # LazyVim
# or:
git clone https://github.com/NvChad/starter ~/.config/nvim        # NvChad
nvim   # auto-bootstraps

Setup Zsh

Set up a fully configured Zsh environment with Oh My Zsh, essential plugins, powerlevel10k theme, and modern CLI tools (fzf, zoxide). Produces a self-contained ~/.zshrc with command -v guards for optional tools — no external file dependencies.

What gets installed

  • Oh My Zsh (if not already present)
  • Plugins: zsh-autosuggestions, zsh-completions, zsh-syntax-highlighting, fzf-tab, z
  • fzf (via Homebrew)
  • zoxide (smart cd replacement)
  • uv — Python package manager (replaces pyenv + pip + virtualenv)
  • fnm — fast Node.js version manager (replaces nvm, Rust-based)
  • Go (via Homebrew)
  • powerlevel10k theme
  • Self-contained ~/.zshrc — inlines all config, backs up the existing one

Environment isolation strategy

LanguageToolHow isolation works
PythonuvUV_PYTHON_PREFERENCE=only-managed — always uv-managed Python; pip install is intercepted and blocked
Node.jsfnmreads .node-version / .nvmrc per project; --use-on-cd auto-switches
Gobuilt-ingo.mod handles per-project deps natively; binaries go to $GOPATH/bin

Python workflow (uv)

uv python install 3.12      # install a Python version
uv init myproject            # new project (creates pyproject.toml + .venv)
uv venv                      # create venv in existing dir
uv pip install requests      # install into active venv
uv tool install ruff         # install CLI tool in isolated env (not global)
uv run script.py             # run script with auto-managed deps

conda/miniforge is still supported: if ~/miniforge3/ or ~/miniconda3/ exists, it's sourced automatically.

Node.js workflow (fnm)

fnm install 20               # install Node 20
fnm default 20               # set global default
echo "20" > .node-version    # fnm auto-switches when you cd into this dir

Three-tier config layout

A clean separation between portable config, secrets, and machine-specific tweaks:

FilePurposeTracked?
~/.zshrcMain shell config — plugins, PATH, language runtimes, aliases✅ tracked (dotfiles)
~/.envEnvironment variables, API keys, secrets — auto-exported on shell start❌ gitignored, chmod 600
~/.zshrc.localMachine-specific aliases / functions / work-only config❌ gitignored

Both ~/.env and ~/.zshrc.local are sourced after the main config, so they can override anything. The setup script creates starter templates if missing (and never overwrites existing files).

~/.env example

# Bare assignments — auto-exported (no `export` keyword needed)
OPENAI_API_KEY=sk-...
GITHUB_TOKEN=ghp_...
AWS_PROFILE=default

~/.zshrc.local example

# Work-only aliases that don't belong in dotfiles
alias work-vpn='sudo openconnect vpn.company.com'
alias prod-db='psql -h prod.example.com -U admin'

Self-contained .zshrc design

All guards are presence-based — missing tools are silently skipped:

  • Python: UV_PYTHON_PREFERENCE=only-managed + pip install interceptor; conda sourced only if dir exists
  • Node.js: fnm --use-on-cd for automatic per-project version switching
  • Go: GOPATH=$HOME/go set only when go is available
  • Optional tools (bun, cargo, gcloud) only activate when present
  • Explicit history: 50k entries, dedupe, share across sessions

Quick setup

bash ${CLAUDE_SKILL_DIR}/scripts/setup-zsh.sh

The script backs up any existing ~/.zshrc before overwriting.

Selective setup

bash ${CLAUDE_SKILL_DIR}/scripts/setup-zsh.sh --plugins-only
bash ${CLAUDE_SKILL_DIR}/scripts/setup-zsh.sh --theme-only
bash ${CLAUDE_SKILL_DIR}/scripts/setup-zsh.sh --tools-only
bash ${CLAUDE_SKILL_DIR}/scripts/setup-zsh.sh --env-only      # only create ~/.env, ~/.zshrc.local

Plugins reference

PluginPurpose
zsh-autosuggestionsFish-like suggestions as you type
zsh-completionsAdditional completion definitions
zsh-syntax-highlightingCommand syntax coloring
fzf-tabFuzzy completion with fzf
zDirectory frecency jumping

Built-in functions

FunctionPurpose
mkcd <dir>mkdir + cd in one step
extract <archive>Generic archive extractor (tar/zip/7z/rar/...)

Sponsors

Details

Marketplace
yanmxa/cc-plugins
Source
plugins/setup
Category
Setup

More from yanmxa/cc-plugins

All 10