← 输入框|github.com|刷新
Skip to content
smarkovikPublic

About

The setup I use on my mac

Resources

Stars

1 star

Watchers

1 watching

Forks

Latest commit

 

History

79 Commits

Folders and files

Repository files navigation

mac-setup

My personal machine setup — feel free to use, copy, clone, and contribute.

Targets Apple Silicon on current macOS. No prerequisites: Homebrew installs the Xcode Command Line Tools itself if they are missing.

Run it

git clone git@github.com:smarkovik/mac-setup.git
cd mac-setup
./mac-setup.sh

Or straight from the terminal:

cd /tmp && curl -fsSL -o mac-setup.zip https://github.com/smarkovik/mac-setup/archive/refs/heads/main.zip && unzip -oq mac-setup.zip && cd mac-setup-main && ./mac-setup.sh

It is safe to re-run

Every step is idempotent and reports when it has nothing to do, so this is meant to be run repeatedly — not just once on a fresh laptop.

./mac-setup.sh --dry-run              # show what would change, change nothing
./mac-setup.sh --list                 # list the steps
./mac-setup.sh --only macos-defaults  # run one step
./mac-setup.sh --force                # re-apply steps that would be skipped

The macOS defaults step compares every setting against its live value and writes only what differs, so it converges: change something in System Settings and the next run puts it back. Dock, Finder and SystemUIServer are restarted only when something actually changed, so a run with no drift closes none of your Finder windows. --force rewrites every setting regardless of its current value.

One step failing doesn't stop the rest

This is meant to be pushed to and re-run over time, not just for a fresh laptop, so a step that fails is reported and skipped rather than stopping everything after it - a broken Brewfile cask shouldn't block git, ssh, zsh, or opencode from doing their job. Each step also prints which number it is and how long it took:

==> [2/10] packages
     ...
 ===> step 'packages' failed after 41s (exit 1) - continuing with the remaining steps
 ===> once it is fixed, re-run just that step:
 ===>     ./mac-setup.sh --only packages

==> [3/10] python
     ...
 ===> finished in 96s with 1 step(s) needing attention:
 ===>   - packages (re-run: ./mac-setup.sh --only packages)

brew bundle itself already keeps installing the rest of the Brewfile past one bad cask - this is the same idea one level up, across steps. A cask that fails because of something already in /Applications (a version mismatch, usually) needs a manual look, not automatic deleting - rm -rf the app yourself, then --only packages again.

Layout

Path What it is
mac-setup.sh Orchestrator: flags, step ordering
Brewfile The package list — source of truth for what gets installed
scripts/lib.sh Shared logging, dry-run and defaults comparison helpers
scripts/10-homebrew.sh Install Homebrew, put it on PATH
scripts/20-packages.sh Apply the Brewfile
scripts/25-python.sh Put Homebrew's CPython ahead of Apple's on PATH
scripts/30-dirs.sh Home folder structure
scripts/40-git.sh Global git config
scripts/50-ssh.sh SSH key for GitHub
scripts/60-zsh.sh oh-my-zsh
scripts/65-opencode.sh Link OpenCode's config into this repo
scripts/70-macos-defaults.sh macOS UI preferences
scripts/80-local-code.sh Link local-code into ~/bin
config/opencode/opencode.json.tmpl The OpenCode config — edit this (source of truth)
bin/opencode-config Generates opencode.json from the template with only installed models
config/opencode/prompts/ System prompts for the planner/architect/debugger/reviewer agents
config/opencode/AGENTS.md Always-on global guidance OpenCode loads every session
bin/local-code Control panel: pull/run/wipe/sync the local coding models
scripts/90-passwordless-sudo.sh Opt-in, see below
tools/validate-brewfile.sh Check every Brewfile token exists
tools/audit-defaults.sh Find which key macOS really uses for a setting

Adding or removing packages

Edit the Brewfile and re-run. Removing a line does not uninstall anything; do that yourself with brew uninstall / brew uninstall --cask.

Do not reach for brew bundle cleanup. It lists everything installed that is not in the Brewfile — which is not drift, it is the rest of your machine. On a real install it proposed removing gh, awscli, ansible, pipx and ngrok. The Brewfile is the subset this repo manages, never an inventory of everything you have.

Before committing a new entry, check the token exists:

./tools/validate-brewfile.sh

brew bundle fails the entire file on one bad token, so a single typo takes every other package with it. CI runs this on a macOS runner for the same reason.

OpenCode configuration

config/opencode/opencode.json is generated from config/opencode/opencode.json.tmpl (the committed source of truth) by bin/opencode-config, then symlinked into ~/.config/opencode. The generator copies the template but keeps only the ollama models you have actually downloaded, so OpenCode's picker matches ollama list (see local-code below). Edit the template, then re-run the step — or local-code sync — to regenerate:

./mac-setup.sh --only opencode

If you already have a config there, it is moved aside to opencode.json.backup-<timestamp>, never overwritten. To keep those settings, merge them into the template and re-run.

It points at local model servers, not a cloud provider. Both entries use @ai-sdk/openai-compatible against an OpenAI-shaped endpoint on localhost, so neither needs an API key:

Provider baseURL Served by
ollama http://localhost:11434/v1 ollama serve
llamacpp http://127.0.0.1:8080/v1 llama-server

The ollama models are managed for you: local-code downloads the tiers and regenerates the config so only the ones you have appear. The llamacpp entry's single local model is whatever you point llama-server -m at. OpenCode sends the ID through verbatim, so a model not actually being served fails at request time, not at load time.

There are no credentials here to protect. If you ever do add a cloud provider, put the key in ~/.local/share/opencode/auth.json via opencode auth login — a directory this repo never reads, writes or links — or reference it rather than embedding it, since OpenCode resolves {env:VAR} and {file:path} at load time:

"apiKey": "{env:ANTHROPIC_API_KEY}"

JSON has no comments, so the notes live here rather than in the file. Full key reference — model, agent, mcp, permission, formatter, lsp — is at opencode.ai/docs/config.

local-code — the local model control panel

Three quant tiers of one model (unsloth/Qwen3-Coder-30B-A3B-Instruct-GGUF) — same weights, trading size and RAM for a little quality:

Tier Quant ~Size Ollama tag
small IQ4_XS 16 GB qwen3-coder:small
mid Q5_K_M 22 GB qwen3-coder:mid
big Q6_K 25 GB qwen3-coder:big

local-code (symlinked to ~/bin by scripts/80-local-code.sh) drives them — local-code help prints the full summary:

local-code list            # tiers, which are downloaded, disk free
local-code pull mid        # download a tier (or: small | big | all)
local-code run big         # pull if needed, start ollama, launch OpenCode
local-code wipe small      # delete a tier to free disk (or: mid | big | all)
local-code sync            # rebuild opencode.json to match what's downloaded

The picker shows only what you've downloaded. OpenCode can't auto-detect ollama models, so pull, wipe and sync regenerate opencode.json from ollama list — any installed tag is included, using the template's name/context-limit if it has an entry there, otherwise a generic one. Pulling a model outside the three tiers (e.g. another ollama.com model) needs no repo edit — just ollama pull it, then local-code sync.

Tiers download, they aren't ollama pulled. Hugging Face serves the GGUF blobs from a separate CDN host via a redirect ollama pull refuses ("blocked redirect to a different host"), so local-code fetches the file with curl (resumable) and builds the tag locally with ollama create.

The context window is baked in at 32k (PARAMETER num_ctx), not left to ollama's ~4k default. Override per pull if you have the RAM:

LOCAL_CODE_NUM_CTX=65536 local-code pull big

pull/wipe are the point: at 25 GB for the largest tier, pull what you need, run it, wipe it when done rather than let three quants sit on disk. Q8_0 isn't offered — on 48 GB it leaves almost no KV-cache headroom for a quality jump that's the flattest part of the curve on a sparse MoE.

Agents: planner, architect, debugger, reviewer

Four agents in config/opencode/opencode.json, each scoped to one job with its own model and permissions, prompts in config/opencode/prompts/:

Agent Mode Model Edit Bash
planner primary qwen3-coder:big deny ask
architect primary qwen3-coder:big deny ask
debugger subagent qwen3-coder:mid ask allow
reviewer subagent qwen3-coder:big deny deny

planner, architect and reviewer cannot edit files - they read and reason, so a bad call costs nothing. debugger can run commands and edit, because reproducing a failure and fixing it needs both.

The big/mid split is a quantization/RAM tradeoff of the same 30B model, not a capability tier: big (Q6) keeps a little more fidelity where there is no tight loop to stay fast for; debugger runs mid (Q5) because that loop is interactive and lighter matters more than the marginal quality of a higher quant. What actually differentiates the agents is their prompt and permissions, not the model behind them.

planner breaks a spec into small, vertically-sliced tasks before any code; architect reviews or designs structure; debugger reproduces and fixes; reviewer reads a diff for real, most-severe-first findings.

Invoke a subagent with @debugger or @reviewer in OpenCode, or switch to planner or architect as your primary agent.

AGENTS.md: always-on house style

config/opencode/AGENTS.md is symlinked into ~/.config/opencode and loaded by OpenCode on every session, so its guidance applies to every agent. It holds the default working style - lazy in the good way: YAGNI, reuse before writing, stdlib and native platform features before dependencies, the shortest change that actually works, root-cause over symptom. Edit it to change how every agent behaves by default.

This repo's AI setup lives entirely in OpenCode - agents, prompts and AGENTS.md, all under config/opencode/ - not in Claude Code. .claude/ is gitignored.

Platform: markdown agents, skills, and the doctor

scripts/66-opencode-platform.sh (the step after opencode) symlinks three more things from config/opencode/ into ~/.config/opencode, so they install automatically on every ./mac-setup.sh and stay version-controlled here:

  • Markdown agents (agents/{builder,tester,security}.md) — agents defined as markdown with frontmatter, alongside the JSON planner/architect/… ones.
  • Skills (skills/<name>/SKILL.md) — reusable task playbooks OpenCode invokes on its own via the built-in skill tool, matching on each skill's description. Four ship here: feature-development, production-debugging, pull-request-review, security-review.
  • bin/github-mcp-via-gh.sh — the GitHub MCP, run through gh (no Docker, no PAT env; needs gh auth login).

Add a skill — create a folder and a SKILL.md; no config change needed:

config/opencode/skills/my-skill/SKILL.md
---
name: my-skill                       # lowercase-hyphens, matches the folder
description: Use when <the exact trigger situation>.   # what the model matches on
---
# My skill
1. Step one…

It goes live on the next ./mac-setup.sh (or --only opencode-platform) via the skills symlink. Keep the description sharp and trigger-y — a local model only reaches for a skill when it clearly matches the situation.

Per-project rules — OpenCode also reads an AGENTS.md at the root of whatever project you open, in addition to the global one above. Drop an AGENTS.md in a repo and it applies there automatically; nothing to configure.

Check it all — opencode-doctor (installed to ~/bin) verifies the symlinks, config, agents, skills, gh auth, and which model tiers are pulled.

LSP

"lsp": true

Turns on every language server OpenCode ships built-in support for, each activating only when its own project already satisfies it (a typescript dependency, pyright installed, and so on) - this repo doesn't install any of them for you. Gives every agent real go-to-definition and references instead of grepping for text, which matters most for architecture and review: "what else calls this" is a structural question, not a text search.

MCP: GitHub

"mcp": {
  "github": {
    "type": "local",
    "command": ["docker", "run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "-e", "GITHUB_TOOLSETS=repos,issues,pull_requests,actions,code_security", "ghcr.io/github/github-mcp-server"],
    "environment": { "GITHUB_PERSONAL_ACCESS_TOKEN": "{env:GITHUB_PERSONAL_ACCESS_TOKEN}" },
    "enabled": false
  }
}

Lets the reviewer agent look at a real PR - diffs, check runs, existing review threads - instead of only a local diff. Disabled by default. The runtime it needs is in the Brewfile (colima + docker); to turn it on:

  1. colima start - starts the container daemon (once per boot).
  2. Create a GitHub PAT and export GITHUB_PERSONAL_ACCESS_TOKEN.
  3. Flip enabled to true in config/opencode/opencode.json.

Sentry MCP (@sentry/mcp-server) is a reasonable second addition if you use Sentry, for the same reason - direct issue/error lookup instead of pasting stack traces in by hand - but it authenticates via an OAuth flow per account, so it isn't pre-wired here; add it the same way once you've looked at github.com/getsentry/sentry-mcp.

Checking a macOS setting is still real

defaults write succeeds against a key nothing reads, so a setting can be dead for years without any error — com.apple.menuextra.battery ShowPercent sat in here long after the battery item moved to Control Center in Big Sur. Reading the value back cannot detect that; only watching what the system itself writes can.

./tools/audit-defaults.sh                    # watch the domains we touch
./tools/audit-defaults.sh com.apple.dock     # or specific ones

It snapshots the domains, waits while you change one thing in System Settings, then diffs and names the key macOS actually writes today. Worth a pass after each major macOS release — there is no reliable published source for this, and the usual reference (macos-defaults.com) has no macOS 26 data at all.

Python

brew "python" tracks whatever Homebrew currently calls current, so this follows new releases rather than pinning a version.

python3 resolves to Homebrew's automatically, because the brew shellenv line puts /opt/homebrew/bin ahead of /usr/bin. Homebrew deliberately does not link an unversioned python/pip, so scripts/25-python.sh adds the formula's libexec/bin to PATH — that is what makes plain python and pip work. Apple's remains at /usr/bin/python3 if you need it explicitly.

If you are not me

Fork it. Three things are mine and you will want to change them:

  • git identity in scripts/40-git.sh. It only fills in what is not already set, so it will not overwrite yours — but on a fresh machine you would get mine. Override with GIT_USER_NAME / GIT_USER_EMAIL, or just edit the file.
  • macOS defaults in scripts/70-macos-defaults.sh are my preferences, including en_GB/EUR/Centimeters locale settings.
  • The Brewfile is the set of apps I actually run. It is a plain list — delete the lines you do not want.

Passwordless sudo

Not part of the default run. Nothing in this repo needs it — Homebrew prompts for its own sudo, and every defaults write here is user-level.

./mac-setup.sh --only passwordless-sudo    # enable
sudo rm /private/etc/sudoers.d/$(whoami)   # undo

It is permanent until you remove that file.

About

The setup I use on my mac

Resources

Stars

1 star

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages