
setup
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-pluginsRun it inside Claude Code after adding the marketplace with /plugin marketplace add yanmxa/cc-plugins.
Contents
Discovered from sourceSkills 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
| OrbStack | Docker Desktop | Colima | |
|---|---|---|---|
| Startup | 2-3s | 30-60s | 5-10s |
| Memory at idle | <1GB | 4-8GB | 1-2GB |
| File mount speed | 5-10× faster | Slow | Slow |
| GUI | Menu bar icon only | Heavy dashboard | None |
| Personal use | Free | Free | Free |
| 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 composedocker 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:
- Installs
orbstackvia Homebrew cask - Opens the app once to trigger the setup wizard
- 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
| Action | Binding |
|---|---|
| Split right | Cmd + D |
| Split down | Cmd + Shift + D |
| Close split | Cmd + W |
| Navigate splits | Cmd + Alt + Arrow |
| Resize splits | Cmd + Ctrl + Arrow |
| Equalize splits | Cmd + Shift + = |
| Increase font | Cmd + = |
| Decrease font | Cmd + - |
| Reset font | Cmd + 0 |
| Quick terminal | `Ctrl + `` (global) |
Customization
After setup, edit ~/.config/ghostty/config directly. Common customizations:
- Theme: Change
themeto any built-in theme (ghostty +list-themesto see all) - Font: Change
font-familyandfont-size - Padding: Adjust
window-padding-xandwindow-padding-y - Keybindings: Add or modify
keybindlines
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)
- Install git via Homebrew (skips system git for newer version)
- Configure identity —
user.name,user.email(prompts if not given) - Set defaults — pull.rebase, push.autoSetupRemote, init.defaultBranch=main
- Set credential helper —
osxkeychain(macOS only) - Define aliases —
lg,st,co,br,unstage,last,aliases - Create global gitignore —
~/.gitignore_global(.env,*.pem,*_rsa, etc.) - Generate SSH key —
~/.ssh/id_ed25519(if not present) + add to ssh-agent - Install gh CLI via Homebrew
- 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:
| Layer | What it is | Used for |
|---|---|---|
| SSH key | ~/.ssh/id_ed25519 keypair | git clone git@github.com:..., git push, git pull |
| OAuth token | Stored by gh in macOS Keychain | gh 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:
- Opens a browser → you authorize via OAuth → token stored in Keychain
- Uploads your
~/.ssh/id_ed25519.pubto 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
| Alias | Expands to |
|---|---|
git lg | Pretty one-line log with graph |
git st | status -sb |
git co | checkout |
git br | branch |
git unstage | reset HEAD -- |
git last | log -1 HEAD |
git aliases | List all defined aliases |
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
Permission denied (publickey) on push | SSH key not on GitHub | gh ssh-key add ~/.ssh/id_ed25519.pub |
gh: command not found after install | Homebrew bin not in PATH | Restart shell: source ~/.zshrc |
git push works but gh says "not logged in" | OAuth missing, only SSH set up | Re-run gh auth login |
| Pushed to wrong account | Multiple identities, gh defaulted | gh auth switch or gh auth login --hostname github.com |
Cloning into ... hangs | First-time host key prompt | ssh -T git@github.com once to accept |
| Need to use a 2nd GitHub account | Single SSH key can't auth as two users | Add 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
| 端口 | 进程 | 说明 |
|---|---|---|
:1081 | hysteria | HTTP 代理,hy2on 的 http/https 指向这里 |
:1080 | hysteria | SOCKS5 代理,hy2on 的 all_proxy 指向这里 |
Commands
| Command | Action |
|---|---|
hy2start / hy2stop / hy2restart | Service control (launchd or manual) |
hy2status | PID + mode + listening ports |
hy2log / hy2logs | Tail / last 50 lines of logs |
hy2edit | Edit config.yaml + auto-restart |
hy2diag | Full diagnostic: local + remote (SSH) + proxy test |
hy2restart-all | Restart both server (SSH) and client |
hy2help | Full command reference |
hy2on / hy2off / hy2proxystatus | Proxy env vars → HTTP_PROXY=http://:1081, ALL_PROXY=socks5://:1081 |
hy2ip | Compare direct vs. proxy egress IP |
hy2speed | Test proxy download speed |
gohy2 / stophy2 | Start+proxy+test / Stop+unset proxy |
SSH config (for hy2diag / hy2restart-all)
| Env var | Default |
|---|---|
HY2_SSH_HOST | auto from config.yaml server field |
HY2_SSH_USER | root |
HY2_SSH_PORT | 22 |
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
| Symptom | Likely cause | Fix |
|---|---|---|
connected to server then 30s timeout | Port blocked by GFW DPI | Change to non-443 port (e.g. 8443) |
| Client stuck at "client mode" | v2.12.x macOS binary bug | Pin to v2.8.2: download to ~/.local/bin/hysteria |
| Server outbound TCP all timeout | hysteria process stale >2w | systemctl 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
| ID | What it installs |
|---|---|
brew | Homebrew (required by everything else) |
zsh | Oh My Zsh + plugins + powerlevel10k + uv + fnm + Go + self-contained .zshrc + ~/.env template |
vim | Neovim with full Lua config |
tmux | tmux + TPM + Dracula theme + optimized keybindings |
git | Git global config + GitHub CLI (gh auth) + SSH key + global gitignore |
ghostty | Ghostty terminal + MesloLGL Nerd Font + optimized config |
hysteria2 | Hysteria 2 proxy client + launchd service + hy2start/hy2stop/hy2log shortcuts |
shadowsocks | Shadowsocks client (shadowsocks-rust sslocal) + ssstart/ssstop/sslog |
sing-box | sing-box client — one client for both Hysteria2 + Shadowsocks + sbstart/sbnode |
prefs | macOS 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 descriptionandvalueas 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
| Language | Tool | Isolation |
|---|---|---|
| Python | uv | UV_PYTHON_PREFERENCE=only-managed; pip install blocked globally |
| Node.js | fnm | auto-switches version via .node-version / .nvmrc |
| Go | Homebrew | go.mod per-project isolation; binaries → $GOPATH/bin |
Three-tier shell config layout (set up by zsh component)
| File | Purpose | Tracked? |
|---|---|---|
~/.zshrc | Generic config — plugins, PATH, runtimes, aliases | ✅ tracked |
~/.env | Environment variables / API keys (auto-exported) | ❌ chmod 600 |
~/.zshrc.local | Machine-specific aliases / functions | ❌ |
What prefs actually changes (only 4 settings)
Intentionally minimal — only universally useful for developers, no personal-preference items:
| Setting | Why it's universal |
|---|---|
Finder.AppleShowAllExtensions = true | See full filenames; avoid ambiguous names |
Dock.show-recents = false | The "recent apps" section is rarely useful, just clutter |
screencapture.location = ~/Desktop/screenshots/ | Stop screenshots from cluttering the Desktop |
DSDontWriteNetworkStores = true | Don'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--servermode that SSH-deploys the server side to a Linux VPS — not part of this macOS picker. See each skill'sskill.md.
After setup
- Restart terminal (or
source ~/.zshrc) - Run
p10k configurefor the prompt - In tmux:
prefix + Ito install TPM plugins - Edit
~/.envto add API keys / secrets - If hysteria2 was installed: edit
~/.config/hysteria/config.yaml, thenhy2start
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
| 端口 | 进程 | 说明 |
|---|---|---|
:1082 | sing-box | 对外统一口,sson 指向这里 |
:1084 | sslocal | 内部 SOCKS5,自动管理 |
Commands
| Command | Action |
|---|---|
ssstart / ssstop / ssrestart | Service control (launchd or manual) |
ssstatus | PID + mode + SOCKS5:1084 + HTTP:1082 |
sslog / sslogs | Tail / last 50 lines of logs |
ssedit | Edit config.json + auto-restart |
sshelp | Full command reference |
sson / ssoff / ssproxystatus | Proxy env vars (HTTP_PROXY=http://:1082, ALL_PROXY=socks5://:1082) |
ssip | Compare direct vs. proxy egress IP |
ssspeed | Test proxy download speed |
goss / stopss | Start+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
| Symptom | Likely cause | Fix |
|---|---|---|
Connection refused | sslocal not running | ssstart |
| HTTP tools don't work | sing-box layer down | ssrestart (restarts both) |
timeout | GFW blocked port/IP | Change server port or switch to hy2 |
| Method not supported | Old Python ss client | Use 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-boxvia Homebrew - Deploys
config.jsontemplate (preserves existing — never overwrites real secrets) - Deploys
aliases.sh - Generates the launchd plist only in
--servicemode (in--no-servicemode it removes any pre-existing plist) - Adds
source aliases.shto~/.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.
| Command | Action |
|---|---|
sbstart | Start (runs sing-box check first; launchd service or background process) |
sbstop | Stop (unload service if present, then kill the process) |
sbrestart | Restart (launchctl kickstart -k, or stop+start in manual mode) |
sbstatus | PID + mode + current outbound + listening port |
sblog | Tail stdout + stderr (Ctrl+C to exit) |
sblogs | Last 50 lines of logs |
sbedit | Edit config.json + validate + auto-restart |
sbhelp | Full command reference |
Outbound switching
| Command | Action |
|---|---|
sbnode | Print the current default outbound |
sbnode ss / sbnode hy2 / sbnode auto | Switch 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.
| Command | Action |
|---|---|
sbon | Set http_proxy / https_proxy / all_proxy → sing-box mixed port |
sboff | Unset proxy env vars |
sbproxystatus | Show current proxy state |
sbip | Compare direct vs. proxy egress IP (labels current outbound) |
sbspeed | Test proxy download speed |
Combo
| Command | Action |
|---|---|
gosb | sbstart + sbon + sbip |
stopsb | sbstop + 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.jsonis 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.shand the plist ARE overwritten on re-run — they're managed code, not user datasbstart/sbeditrunsing-box checkbefore (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: trueto match a self-signed server (as deployed bysetup-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'shy2outbound connects tosetup-shadowsocks— the Shadowsocks server (--server) that this client'sssoutbound 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 defaultCtrl-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
- Prefix:
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
| Action | Binding |
|---|---|
| Prefix | Ctrl-a |
| Split horizontal | prefix + \ |
| Split vertical | prefix + - |
| Resize pane | prefix + h/j/k/l |
| Zoom pane | prefix + m |
| Switch pane | Alt + arrow keys |
| Reload config | prefix + r |
| Paste | prefix + p |
| Create named window | prefix + 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-pluginsto add/remove status bar widgets (battery, git, gpu-usage, weather, time, etc.) - Pane borders: Change
pane-border-linestosimple,double, ornumber - 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/(.gitremoved 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
vimrcwith molokai theme, airline, polyglot
Quick setup
bash ${CLAUDE_SKILL_DIR}/scripts/setup-vim.sh
Modes:
| Flag | Behavior |
|---|---|
| (default) | Install Neovim + kickstart.nvim |
--neovim-only | Same as default |
--vim-only | Install 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
| Language | Tool | How isolation works |
|---|---|---|
| Python | uv | UV_PYTHON_PREFERENCE=only-managed — always uv-managed Python; pip install is intercepted and blocked |
| Node.js | fnm | reads .node-version / .nvmrc per project; --use-on-cd auto-switches |
| Go | built-in | go.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:
| File | Purpose | Tracked? |
|---|---|---|
~/.zshrc | Main shell config — plugins, PATH, language runtimes, aliases | ✅ tracked (dotfiles) |
~/.env | Environment variables, API keys, secrets — auto-exported on shell start | ❌ gitignored, chmod 600 |
~/.zshrc.local | Machine-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 installinterceptor; conda sourced only if dir exists - Node.js: fnm
--use-on-cdfor automatic per-project version switching - Go:
GOPATH=$HOME/goset only whengois 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
| Plugin | Purpose |
|---|---|
| zsh-autosuggestions | Fish-like suggestions as you type |
| zsh-completions | Additional completion definitions |
| zsh-syntax-highlighting | Command syntax coloring |
| fzf-tab | Fuzzy completion with fzf |
| z | Directory frecency jumping |
Built-in functions
| Function | Purpose |
|---|---|
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